README revision 76138
176082Sbmah-*- text -*- 276082SbmahRELNOTESng README 376082SbmahBruce A. Mah <bmah@freebsd.org> 476082Sbmah$FreeBSD: head/release/doc/README 76138 2001-04-29 19:24:32Z bmah $ 576082Sbmah 676082SbmahThis is the top-level directory for RELNOTESng, a re-write of 776082SbmahFreeBSD's *.TXT documentation files. They have been converted to 876082SbmahDocBook, and versions of the documents can be now be built for various 976082Sbmahsupported architectures. The output files can be rendered in any 1076082Sbmahformat supported by the FreeBSD Documentation Project (for example, 1176082SbmahASCII text, PDF, PS, HTML). 1276082Sbmah 1376082SbmahRELNOTESng requires that the FreeBSD doc/ sources are installed; it 1476082Sbmahleverages off of much of the DocProj build infrastructure, including 1576082SbmahDocBook extensions and stylesheets. If the doc/ sources are not 1676082Sbmahinstalled in /usr/src, their location should be specified with the 1776082SbmahDOC_PREFIX Makefile variable. RELNOTESng also requires the DocProj 1876082Sbmahbuild tools, which can easily be installed with the textproc/docproj 1976082Sbmahport in the Ports Collection. 2076082Sbmah 2176082Sbmahshare/sgml/*.dsl 2276082Sbmah Architecture-dependent stylesheets. These stylesheets support 2376082Sbmah the arch= attribute on (all?) DocBook elements. Currently- 2476082Sbmah supported values are: i386, alpha. 2576082Sbmahshare/sgml/release.ent 2676082Sbmah Release information. Need to update the entry definitions in 2776082Sbmah this file when rolling new revisions; these should take effect 2876082Sbmah in all documents. 2976082Sbmah 3076082Sbmah*/relnotes/common/ 3176082Sbmah Directory for multi-architecture release notes files. 3276082Sbmah*/relnotes/*/ 3376082Sbmah Directories for architecture-specific release notes files. 3476082Sbmah 3576082Sbmah*/hardware/common/ 3676082Sbmah Directory for multi-architecture hardware notes files. 3776082Sbmah*/hardware/*/ 3876082Sbmah Directories for architecture-specific hardware notes files. 3976082Sbmah 4076082Sbmah*/installation/common/ 4176082Sbmah Directory for multi-architecture installation notes files. 4276082Sbmah Note that the FreeBSD DocProj build infrastructure does 4376082Sbmah not handle documents (or subdirectories) named "install" 4476082Sbmah well, so we call our document "installation" and do 4576082Sbmah a hack when it gets installed into a distribution to fix 4676082Sbmah this up. 4776082Sbmah*/installation/*/ 4876082Sbmah Directories for architecture-specific release notes files. 4976082Sbmah 5076082Sbmah*/errata/ 5176082Sbmah Directory for errata document. 5276082Sbmah 5376082Sbmah*/readme/ 5476082Sbmah Directory for (introductory) document. 5576082Sbmah 5676138SbmahIf building the release notes "standalone" (in other words, not part 5776138Sbmahof a release), it may be necessary (depending on the relative 5876138Sbmahlocations of the checked-out src/ and doc/ directories) to set the 5976138SbmahDOC_PREFIX Makefile variable to point to the top directory of the doc/ 6076138Sbmahtree. For example: 6176138Sbmah 6276138Sbmah % make DOC_PREFIX=/usr/doc all 6376138Sbmah 6476082SbmahAll definition of the "current" version of FreeBSD is contained in the 6576082Sbmahshare/sgml/release.ent file; release engineers should peruse the 6676082Sbmahcontents of this file carefully when doing version number bumps. 6776082Sbmah 6876082SbmahWhen creating content for the architecture-dependent files, authors 6976082Sbmahshould use the arch= attribute to elements that are specific to a 7076082Sbmahparticular machine architecture. The value of this attribute should 7176082Sbmahbe a single word that indicates for which architecture the current 7276082Sbmahelement will be included. For example: 7376082Sbmah 7476082Sbmah <para arch="alpha">Alpha-specific text</para> 7576082Sbmah 7676082SbmahThe currently-supported architectures are i386 and alpha. As of this 7776082Sbmahwriting there is no mechanism for supporting multiple architectures 7876082Sbmah(i.e. arch="alpha,ia64"), but with some work in the stylesheets this 7976082Sbmahshould be possible. 8076082Sbmah 8176082SbmahWhen creating a translation, make a new directory under this 8276082Sbmahdirectory with a language code (paralleling the DocProj directory 8376082Sbmahstructure). 8476082Sbmah 8576082SbmahRELNOTESng is supported in the FreeBSD release-build process. For 8676082Sbmahnow, the building of RELNOTESng is enabled by RELNOTESNG=YES when 8776082Sbmahbuilding a release. Note that setting RELNOTESng requires that both 8876082SbmahNODOC and NOPORTS *not* be set, as RELNOTESng require parts of 8976082Sbmahboth. Eventually, RELNOTESNG will be made the default. 9076082Sbmah 9176082SbmahRelease builders can set which language gets built with the 9276082SbmahRELNOTESNG_LANG variable; note that this is different from the 9376082SbmahDOC_LANG variable because (at least intially) most languages 9476082Sbmahwill have localized DocProj files but not localized release notes. 9576082SbmahThe default language, if none is specified, is en_US.ISO_8859-1. 9676082Sbmah 97