diff options
Diffstat (limited to 'release/doc/README')
| -rw-r--r-- | release/doc/README | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/release/doc/README b/release/doc/README new file mode 100644 index 000000000000..a46779d78f1f --- /dev/null +++ b/release/doc/README @@ -0,0 +1,127 @@ +-*- 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, pc98, +powerpc and sparc64. An element may appear for multiple architectures +by specifying a comma-separated list of architectures +(i.e. arch="sparc64,amd64"). + +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. + |