xref: /freebsd-11.0-release/release/doc/README

-*- text -*-
RELNOTESng README
Bruce A. Mah <bmah@freebsd.org>
$FreeBSD: head/release/doc/README 241096 2012-10-01 11:26:49Z gabor $

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.