README revision 76082
176082Sbmah-*- text -*- 276082SbmahRELNOTESng README 376082SbmahBruce A. Mah <bmah@freebsd.org> 476082Sbmah$FreeBSD: head/release/doc/README 76082 2001-04-27 21:28:02Z 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 5676082SbmahAll definition of the "current" version of FreeBSD is contained in the 5776082Sbmahshare/sgml/release.ent file; release engineers should peruse the 5876082Sbmahcontents of this file carefully when doing version number bumps. 5976082Sbmah 6076082SbmahWhen creating content for the architecture-dependent files, authors 6176082Sbmahshould use the arch= attribute to elements that are specific to a 6276082Sbmahparticular machine architecture. The value of this attribute should 6376082Sbmahbe a single word that indicates for which architecture the current 6476082Sbmahelement will be included. For example: 6576082Sbmah 6676082Sbmah <para arch="alpha">Alpha-specific text</para> 6776082Sbmah 6876082SbmahThe currently-supported architectures are i386 and alpha. As of this 6976082Sbmahwriting there is no mechanism for supporting multiple architectures 7076082Sbmah(i.e. arch="alpha,ia64"), but with some work in the stylesheets this 7176082Sbmahshould be possible. 7276082Sbmah 7376082SbmahWhen creating a translation, make a new directory under this 7476082Sbmahdirectory with a language code (paralleling the DocProj directory 7576082Sbmahstructure). 7676082Sbmah 7776082SbmahRELNOTESng is supported in the FreeBSD release-build process. For 7876082Sbmahnow, the building of RELNOTESng is enabled by RELNOTESNG=YES when 7976082Sbmahbuilding a release. Note that setting RELNOTESng requires that both 8076082SbmahNODOC and NOPORTS *not* be set, as RELNOTESng require parts of 8176082Sbmahboth. Eventually, RELNOTESNG will be made the default. 8276082Sbmah 8376082SbmahRelease builders can set which language gets built with the 8476082SbmahRELNOTESNG_LANG variable; note that this is different from the 8576082SbmahDOC_LANG variable because (at least intially) most languages 8676082Sbmahwill have localized DocProj files but not localized release notes. 8776082SbmahThe default language, if none is specified, is en_US.ISO_8859-1. 8876082Sbmah 89