/release/doc/README
https://bitbucket.org/freebsd/freebsd-head/ · #! · 127 lines · 107 code · 20 blank · 0 comment · 0 complexity · 39c9a9506639f958c907d56146d8726e MD5 · raw file
- -*- 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.