README revision 241096
176082Sbmah-*- text -*- 276082SbmahRELNOTESng README 376082SbmahBruce A. Mah <bmah@freebsd.org> 476082Sbmah$FreeBSD: head/release/doc/README 241096 2012-10-01 11:26:49Z gabor $ 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 2586150Solgeni mostly accommodate the fact that we're building DocProj-like 2676222Sbmah documents outside the doc/ tree. 27241096Sgaborshare/xml/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. 31241096Sgaborshare/xml/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. 36241096Sgaborshare/xml/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 42158627Swilko that match, such as "i386,sparc64". 43241096Sgaborshare/xml/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 48241096Sgaboren_US.ISO8859-1/share/xml/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 54241096Sgabor */share/xml/release.dsl and */share/xml/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 91241096Sgaborshare/xml/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 100158627Swilko <para arch="sparc64">SPARC64-specific text</para> 10176082Sbmah 102198114ShrsThe currently-supported architectures are amd64, arm, i386, ia64, 103198114Shrspc98, powerpc, and sparc64. An element may appear for multiple 104198114Shrsarchitectures by specifying a comma-separated list of architectures 105198114Shrs(i.e. arch="sparc64,ia64"). 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 111241096Sgabor${LANG}/share/xml/release.dsl, a ${LANG}/share/xml/catalog that 11276254Sbmahpoints to it, and a new definition in the Makefiles that adds 113241096Sgabor${LANG}/share/xml/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 11877494Sbmahprocess. It can be disabled by setting NODOC=YES when building a 11977494Sbmahrelease (note that this is the same variable that disables DocProj 12077494Sbmahdocumentation builds). 12176082Sbmah 12276082SbmahRelease builders can set which language gets built with the 12377211SbmahRELNOTES_LANG variable; note that this is different from the 12486150SolgeniDOC_LANG variable because (at least initially) most languages 12576082Sbmahwill have localized DocProj files but not localized release notes. 12678040SacheThe default language, if none is specified, is en_US.ISO8859-1. 12776082Sbmah 128