README revision 77211
176082Sbmah-*- text -*- 276082SbmahRELNOTESng README 376082SbmahBruce A. Mah <bmah@freebsd.org> 476082Sbmah$FreeBSD: head/release/doc/README 77211 2001-05-25 23:52:26Z 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 2176254SbmahNotable files and directories: 2276254Sbmah 2376222Sbmahshare/mk/doc.relnotes.mk 2476222Sbmah Common Makefile definitions for RELNOTESng. These definitions 2576222Sbmah mostly accomodate the fact that we're building DocProj-like 2676222Sbmah documents outside the doc/ tree. 2776254Sbmahshare/sgml/catalog 2876254Sbmah Main SGML catalog for all language-neutral (and default EN) 2976254Sbmah stylesheet and entity files. Can be overridden if needed for 3076254Sbmah translations. 3176254Sbmahshare/sgml/default.dsl 3276254Sbmah All documents build with this file as a stylesheet. All it 3376254Sbmah does is to make it possible to use the document catalogs to 3476254Sbmah locate the "real" stylesheet by reference, rather than having 3576254Sbmah to specify it by pathname. 3676222Sbmahshare/sgml/release.dsl 3776222Sbmah Language-neutral stylesheet. This stylesheet supports 3876222Sbmah the arch= attribute on (all?) DocBook elements; elements with 3976222Sbmah an arch= attribute are only included in the output if their 4076222Sbmah value is equal to the value of the &arch; entity. In the 4176222Sbmah future, arch= could be a list of possible &arch; entity values 4276222Sbmah that match, such as "i386,alpha". 4376082Sbmahshare/sgml/release.ent 4476082Sbmah Release information. Need to update the entry definitions in 4576082Sbmah this file when rolling new revisions; these should take effect 4676082Sbmah in all documents. 4776082Sbmah 4876254Sbmahen_US.ISO_8859-1/share/sgml/release.dsl 4976254Sbmah Language-dependent stylesheet for en, but also the default for 5076254Sbmah translations if they don't override the settings here. This 5176254Sbmah stylesheet sets the email footer at the bottom of HTML pages, 5276254Sbmah as well as a few other parameters. If necessary for 5376254Sbmah translations, this file can be overridden with 5476254Sbmah */share/sgml/release.dsl and */share/sgml/catalog. 5576254Sbmah 5676082Sbmah*/relnotes/common/ 5776082Sbmah Directory for multi-architecture release notes files. 5876082Sbmah*/relnotes/*/ 5976082Sbmah Directories for architecture-specific release notes files. 6076082Sbmah 6176082Sbmah*/hardware/common/ 6276082Sbmah Directory for multi-architecture hardware notes files. 6376082Sbmah*/hardware/*/ 6476082Sbmah Directories for architecture-specific hardware notes files. 6576082Sbmah 6676082Sbmah*/installation/common/ 6776082Sbmah Directory for multi-architecture installation notes files. 6876082Sbmah Note that the FreeBSD DocProj build infrastructure does 6976082Sbmah not handle documents (or subdirectories) named "install" 7076082Sbmah well, so we call our document "installation" and do 7176082Sbmah a hack when it gets installed into a distribution to fix 7276082Sbmah this up. 7376082Sbmah*/installation/*/ 7476082Sbmah Directories for architecture-specific release notes files. 7576082Sbmah 7676082Sbmah*/errata/ 7776082Sbmah Directory for errata document. 7876082Sbmah 7976082Sbmah*/readme/ 8076082Sbmah Directory for (introductory) document. 8176082Sbmah 8276138SbmahIf building the release notes "standalone" (in other words, not part 8376138Sbmahof a release), it may be necessary (depending on the relative 8476138Sbmahlocations of the checked-out src/ and doc/ directories) to set the 8576138SbmahDOC_PREFIX Makefile variable to point to the top directory of the doc/ 8676138Sbmahtree. For example: 8776138Sbmah 8876138Sbmah % make DOC_PREFIX=/usr/doc all 8976138Sbmah 9076082SbmahAll definition of the "current" version of FreeBSD is contained in the 9176082Sbmahshare/sgml/release.ent file; release engineers should peruse the 9276082Sbmahcontents of this file carefully when doing version number bumps. 9376082Sbmah 9476082SbmahWhen creating content for the architecture-dependent files, authors 9576082Sbmahshould use the arch= attribute to elements that are specific to a 9676082Sbmahparticular machine architecture. The value of this attribute should 9776082Sbmahbe a single word that indicates for which architecture the current 9876082Sbmahelement will be included. For example: 9976082Sbmah 10076082Sbmah <para arch="alpha">Alpha-specific text</para> 10176082Sbmah 10276082SbmahThe currently-supported architectures are i386 and alpha. As of this 10376082Sbmahwriting there is no mechanism for supporting multiple architectures 10476082Sbmah(i.e. arch="alpha,ia64"), but with some work in the stylesheets this 10576082Sbmahshould be possible. 10676082Sbmah 10776082SbmahWhen creating a translation, make a new directory under this 10876082Sbmahdirectory with a language code (paralleling the DocProj directory 10976254Sbmahstructure). If necessary, new language-dependent HTML footers can be 11076254Sbmahgenerated by making a new language-dependent 11176254Sbmah${LANG}/share/sgml/release.dsl, a ${LANG}/share/sgml/catalog that 11276254Sbmahpoints to it, and a new definition in the Makefiles that adds 11376254Sbmah${LANG}/share/sgml/catalog to EXTRA_CATALOGS. Except for the Makefile 11476254Sbmahchanges, this is the same procedure that is used for creating a new 11576254Sbmahtranslation for DocProj files. 11676082Sbmah 11777211SbmahRELNOTESng is now enabled by default in the FreeBSD release-build 11877211Sbmahprocess. It can be disabled by setting NORELNOTES=YES when building a 11977211Sbmahrelease. Note that RELNOTESng requires that NODOC *not* be set, as 12077211SbmahRELNOTESng require parts of the doc/ tree. Eventually, RELNOTESNG 12177211Sbmahwill be made the default. 12276082Sbmah 12376082SbmahRelease builders can set which language gets built with the 12477211SbmahRELNOTES_LANG variable; note that this is different from the 12576082SbmahDOC_LANG variable because (at least intially) most languages 12676082Sbmahwill have localized DocProj files but not localized release notes. 12776082SbmahThe default language, if none is specified, is en_US.ISO_8859-1. 12876082Sbmah 129