129 lines
5.3 KiB
Plaintext
129 lines
5.3 KiB
Plaintext
-*- text -*-
|
|
RELNOTESng README
|
|
Bruce A. Mah <bmah@freebsd.org>
|
|
$FreeBSD$
|
|
|
|
This is the top-level directory for RELNOTESng, a re-write of
|
|
FreeBSD's *.TXT documentation files. They have been converted to
|
|
DocBook, and versions of the documents can be now be built for various
|
|
supported architectures. The output files can be rendered in any
|
|
format supported by the FreeBSD Documentation Project (for example,
|
|
ASCII text, PDF, PS, HTML).
|
|
|
|
RELNOTESng requires that the FreeBSD doc/ sources are installed; it
|
|
leverages off of much of the DocProj build infrastructure, including
|
|
DocBook extensions and stylesheets. If the doc/ sources are not
|
|
installed in /usr/src, their location should be specified with the
|
|
DOC_PREFIX Makefile variable. RELNOTESng also requires the DocProj
|
|
build tools, which can easily be installed with the textproc/docproj
|
|
port in the Ports Collection.
|
|
|
|
Notable files and directories:
|
|
|
|
share/mk/doc.relnotes.mk
|
|
Common Makefile definitions for RELNOTESng. These definitions
|
|
mostly accomodate the fact that we're building DocProj-like
|
|
documents outside the doc/ tree.
|
|
share/sgml/catalog
|
|
Main SGML catalog for all language-neutral (and default EN)
|
|
stylesheet and entity files. Can be overridden if needed for
|
|
translations.
|
|
share/sgml/default.dsl
|
|
All documents build with this file as a stylesheet. All it
|
|
does is to make it possible to use the document catalogs to
|
|
locate the "real" stylesheet by reference, rather than having
|
|
to specify it by pathname.
|
|
share/sgml/release.dsl
|
|
Language-neutral stylesheet. This stylesheet supports
|
|
the arch= attribute on (all?) DocBook elements; elements with
|
|
an arch= attribute are only included in the output if their
|
|
value is equal to the value of the &arch; entity. In the
|
|
future, arch= could be a list of possible &arch; entity values
|
|
that match, such as "i386,alpha".
|
|
share/sgml/release.ent
|
|
Release information. Need to update the entry definitions in
|
|
this file when rolling new revisions; these should take effect
|
|
in all documents.
|
|
|
|
en_US.ISO_8859-1/share/sgml/release.dsl
|
|
Language-dependent stylesheet for en, but also the default for
|
|
translations if they don't override the settings here. This
|
|
stylesheet sets the email footer at the bottom of HTML pages,
|
|
as well as a few other parameters. If necessary for
|
|
translations, this file can be overridden with
|
|
*/share/sgml/release.dsl and */share/sgml/catalog.
|
|
|
|
*/relnotes/common/
|
|
Directory for multi-architecture release notes files.
|
|
*/relnotes/*/
|
|
Directories for architecture-specific release notes files.
|
|
|
|
*/hardware/common/
|
|
Directory for multi-architecture hardware notes files.
|
|
*/hardware/*/
|
|
Directories for architecture-specific hardware notes files.
|
|
|
|
*/installation/common/
|
|
Directory for multi-architecture installation notes files.
|
|
Note that the FreeBSD DocProj build infrastructure does
|
|
not handle documents (or subdirectories) named "install"
|
|
well, so we call our document "installation" and do
|
|
a hack when it gets installed into a distribution to fix
|
|
this up.
|
|
*/installation/*/
|
|
Directories for architecture-specific release notes files.
|
|
|
|
*/errata/
|
|
Directory for errata document.
|
|
|
|
*/readme/
|
|
Directory for (introductory) document.
|
|
|
|
If building the release notes "standalone" (in other words, not part
|
|
of a release), it may be necessary (depending on the relative
|
|
locations of the checked-out src/ and doc/ directories) to set the
|
|
DOC_PREFIX Makefile variable to point to the top directory of the doc/
|
|
tree. For example:
|
|
|
|
% make DOC_PREFIX=/usr/doc all
|
|
|
|
All definition of the "current" version of FreeBSD is contained in the
|
|
share/sgml/release.ent file; release engineers should peruse the
|
|
contents of this file carefully when doing version number bumps.
|
|
|
|
When creating content for the architecture-dependent files, authors
|
|
should use the arch= attribute to elements that are specific to a
|
|
particular machine architecture. The value of this attribute should
|
|
be a single word that indicates for which architecture the current
|
|
element will be included. For example:
|
|
|
|
<para arch="alpha">Alpha-specific text</para>
|
|
|
|
The currently-supported architectures are i386 and alpha. As of this
|
|
writing there is no mechanism for supporting multiple architectures
|
|
(i.e. arch="alpha,ia64"), but with some work in the stylesheets this
|
|
should be possible.
|
|
|
|
When creating a translation, make a new directory under this
|
|
directory with a language code (paralleling the DocProj directory
|
|
structure). If necessary, new language-dependent HTML footers can be
|
|
generated by making a new language-dependent
|
|
${LANG}/share/sgml/release.dsl, a ${LANG}/share/sgml/catalog that
|
|
points to it, and a new definition in the Makefiles that adds
|
|
${LANG}/share/sgml/catalog to EXTRA_CATALOGS. Except for the Makefile
|
|
changes, this is the same procedure that is used for creating a new
|
|
translation for DocProj files.
|
|
|
|
RELNOTESng is now enabled by default in the FreeBSD release-build
|
|
process. It can be disabled by setting NORELNOTES=YES when building a
|
|
release. Note that RELNOTESng requires that NODOC *not* be set, as
|
|
RELNOTESng require parts of the doc/ tree. Eventually, RELNOTESNG
|
|
will be made the default.
|
|
|
|
Release builders can set which language gets built with the
|
|
RELNOTES_LANG variable; note that this is different from the
|
|
DOC_LANG variable because (at least intially) most languages
|
|
will have localized DocProj files but not localized release notes.
|
|
The default language, if none is specified, is en_US.ISO_8859-1.
|
|
|