128 lines
5.3 KiB
Plaintext
128 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 accommodate the fact that we're building DocProj-like
|
|
documents outside the doc/ tree.
|
|
share/xml/catalog
|
|
Main SGML catalog for all language-neutral (and default EN)
|
|
stylesheet and entity files. Can be overridden if needed for
|
|
translations.
|
|
share/xml/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/xml/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,sparc64".
|
|
share/xml/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.ISO8859-1/share/xml/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/xml/release.dsl and */share/xml/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/xml/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="sparc64">SPARC64-specific text</para>
|
|
|
|
The currently-supported architectures are amd64, arm, i386, ia64,
|
|
pc98, powerpc, and sparc64. An element may appear for multiple
|
|
architectures by specifying a comma-separated list of architectures
|
|
(i.e. arch="sparc64,ia64").
|
|
|
|
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/xml/release.dsl, a ${LANG}/share/xml/catalog that
|
|
points to it, and a new definition in the Makefiles that adds
|
|
${LANG}/share/xml/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 NODOC=YES when building a
|
|
release (note that this is the same variable that disables DocProj
|
|
documentation builds).
|
|
|
|
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 initially) most languages
|
|
will have localized DocProj files but not localized release notes.
|
|
The default language, if none is specified, is en_US.ISO8859-1.
|
|
|