/release/doc/README

  1-*- text -*-
  2RELNOTESng README
  3Bruce A. Mah <bmah@freebsd.org>
  4$FreeBSD$
  5
  6This is the top-level directory for RELNOTESng, a re-write of
  7FreeBSD's *.TXT documentation files.  They have been converted to
  8DocBook, and versions of the documents can be now be built for various
  9supported architectures.  The output files can be rendered in any
 10format supported by the FreeBSD Documentation Project (for example,
 11ASCII text, PDF, PS, HTML).
 12
 13RELNOTESng requires that the FreeBSD doc/ sources are installed; it
 14leverages off of much of the DocProj build infrastructure, including
 15DocBook extensions and stylesheets.  If the doc/ sources are not
 16installed in /usr/src, their location should be specified with the
 17DOC_PREFIX Makefile variable.  RELNOTESng also requires the DocProj
 18build tools, which can easily be installed with the textproc/docproj
 19port in the Ports Collection.
 20
 21Notable files and directories:
 22
 23share/mk/doc.relnotes.mk
 24	Common Makefile definitions for RELNOTESng.  These definitions
 25	mostly accommodate the fact that we're building DocProj-like
 26	documents outside the doc/ tree.
 27share/xml/catalog
 28	Main SGML catalog for all language-neutral (and default EN)
 29	stylesheet and entity files.  Can be overridden if needed for
 30	translations.
 31share/xml/default.dsl
 32	All documents build with this file as a stylesheet.  All it
 33	does is to make it possible to use the document catalogs to
 34	locate the "real" stylesheet by reference, rather than having
 35	to specify it by pathname.
 36share/xml/release.dsl
 37	Language-neutral stylesheet.  This stylesheet supports
 38	the arch= attribute on (all?) DocBook elements; elements with
 39	an arch= attribute are only included in the output if their
 40	value is equal to the value of the &arch; entity.  In the
 41	future, arch= could be a list of possible &arch; entity values
 42	that match, such as "i386,sparc64".
 43share/xml/release.ent
 44	Release information.  Need to update the entry definitions in
 45	this file when rolling new revisions; these should take effect
 46	in all documents.
 47
 48en_US.ISO8859-1/share/xml/release.dsl
 49	Language-dependent stylesheet for en, but also the default for
 50	translations if they don't override the settings here.  This
 51	stylesheet sets the email footer at the bottom of HTML pages,
 52	as well as a few other parameters.  If necessary for
 53	translations, this file can be overridden with
 54	*/share/xml/release.dsl and */share/xml/catalog.
 55
 56*/relnotes/common/
 57	Directory for multi-architecture release notes files.
 58*/relnotes/*/
 59	Directories for architecture-specific release notes files.
 60
 61*/hardware/common/
 62	Directory for multi-architecture hardware notes files.
 63*/hardware/*/
 64	Directories for architecture-specific hardware notes files.
 65
 66*/installation/common/
 67	Directory for multi-architecture installation notes files.
 68	Note that the FreeBSD DocProj build infrastructure does
 69	not handle documents (or subdirectories) named "install" 
 70	well, so we call our document "installation" and do
 71	a hack when it gets installed into a distribution to fix
 72	this up.
 73*/installation/*/
 74	Directories for architecture-specific release notes files.
 75
 76*/errata/
 77	Directory for errata document.
 78
 79*/readme/
 80	Directory for (introductory) document.
 81
 82If building the release notes "standalone" (in other words, not part
 83of a release), it may be necessary (depending on the relative
 84locations of the checked-out src/ and doc/ directories) to set the
 85DOC_PREFIX Makefile variable to point to the top directory of the doc/
 86tree.  For example:
 87
 88	 % make DOC_PREFIX=/usr/doc all
 89
 90All definition of the "current" version of FreeBSD is contained in the
 91share/xml/release.ent file; release engineers should peruse the
 92contents of this file carefully when doing version number bumps.
 93
 94When creating content for the architecture-dependent files, authors
 95should use the arch= attribute to elements that are specific to a
 96particular machine architecture.  The value of this attribute should
 97be a single word that indicates for which architecture the current
 98element will be included.  For example:
 99
100	<para arch="sparc64">SPARC64-specific text</para>
101
102The currently-supported architectures are amd64, arm, i386, ia64,
103pc98, powerpc, and sparc64.  An element may appear for multiple
104architectures by specifying a comma-separated list of architectures
105(i.e. arch="sparc64,ia64").
106
107When creating a translation, make a new directory under this
108directory with a language code (paralleling the DocProj directory
109structure).  If necessary, new language-dependent HTML footers can be
110generated by making a new language-dependent
111${LANG}/share/xml/release.dsl, a ${LANG}/share/xml/catalog that
112points to it, and a new definition in the Makefiles that adds
113${LANG}/share/xml/catalog to EXTRA_CATALOGS.  Except for the Makefile
114changes, this is the same procedure that is used for creating a new
115translation for DocProj files.
116
117RELNOTESng is now enabled by default in the FreeBSD release-build
118process.  It can be disabled by setting NODOC=YES when building a
119release (note that this is the same variable that disables DocProj
120documentation builds).
121
122Release builders can set which language gets built with the 
123RELNOTES_LANG variable; note that this is different from the 
124DOC_LANG variable because (at least initially) most languages
125will have localized DocProj files but not localized release notes.
126The default language, if none is specified, is en_US.ISO8859-1.
127