README revision 78040
1306196Sjkim-*- text -*- 2110010SmarkmRELNOTESng README 3110010SmarkmBruce A. Mah <bmah@freebsd.org> 4160819Ssimon$FreeBSD: head/release/doc/README 78040 2001-06-11 01:48:17Z ache $ 5110010Smarkm 6110010SmarkmThis is the top-level directory for RELNOTESng, a re-write of 7110010SmarkmFreeBSD's *.TXT documentation files. They have been converted to 8110010SmarkmDocBook, and versions of the documents can be now be built for various 9110010Smarkmsupported architectures. The output files can be rendered in any 10110010Smarkmformat supported by the FreeBSD Documentation Project (for example, 11110010SmarkmASCII text, PDF, PS, HTML). 12110010Smarkm 13110010SmarkmRELNOTESng requires that the FreeBSD doc/ sources are installed; it 14110010Smarkmleverages off of much of the DocProj build infrastructure, including 15110010SmarkmDocBook extensions and stylesheets. If the doc/ sources are not 16110010Smarkminstalled in /usr/src, their location should be specified with the 17110010SmarkmDOC_PREFIX Makefile variable. RELNOTESng also requires the DocProj 18110010Smarkmbuild tools, which can easily be installed with the textproc/docproj 19110010Smarkmport in the Ports Collection. 20215698Ssimon 21215698SsimonNotable files and directories: 22215698Ssimon 23215698Ssimonshare/mk/doc.relnotes.mk 24215698Ssimon Common Makefile definitions for RELNOTESng. These definitions 25110010Smarkm mostly accomodate the fact that we're building DocProj-like 26110010Smarkm documents outside the doc/ tree. 27110010Smarkmshare/sgml/catalog 28110010Smarkm Main SGML catalog for all language-neutral (and default EN) 29110010Smarkm stylesheet and entity files. Can be overridden if needed for 30110010Smarkm translations. 31110010Smarkmshare/sgml/default.dsl 32110010Smarkm All documents build with this file as a stylesheet. All it 33110010Smarkm does is to make it possible to use the document catalogs to 34110010Smarkm locate the "real" stylesheet by reference, rather than having 35110010Smarkm to specify it by pathname. 36110010Smarkmshare/sgml/release.dsl 37110010Smarkm Language-neutral stylesheet. This stylesheet supports 38110010Smarkm the arch= attribute on (all?) DocBook elements; elements with 39110010Smarkm an arch= attribute are only included in the output if their 40110010Smarkm value is equal to the value of the &arch; entity. In the 41276864Sjkim future, arch= could be a list of possible &arch; entity values 42276864Sjkim that match, such as "i386,alpha". 43110010Smarkmshare/sgml/release.ent 44110010Smarkm Release information. Need to update the entry definitions in 45215698Ssimon this file when rolling new revisions; these should take effect 46215698Ssimon in all documents. 47215698Ssimon 48215698Ssimonen_US.ISO8859-1/share/sgml/release.dsl 49160819Ssimon Language-dependent stylesheet for en, but also the default for 50215698Ssimon translations if they don't override the settings here. This 51160819Ssimon stylesheet sets the email footer at the bottom of HTML pages, 52160819Ssimon as well as a few other parameters. If necessary for 53276864Sjkim translations, this file can be overridden with 54276864Sjkim */share/sgml/release.dsl and */share/sgml/catalog. 55276864Sjkim 56110010Smarkm*/relnotes/common/ 57276864Sjkim Directory for multi-architecture release notes files. 58276864Sjkim*/relnotes/*/ 59276864Sjkim Directories for architecture-specific release notes files. 60276864Sjkim 61276864Sjkim*/hardware/common/ 62276864Sjkim Directory for multi-architecture hardware notes files. 63215698Ssimon*/hardware/*/ 64276864Sjkim Directories for architecture-specific hardware notes files. 65276864Sjkim 66276864Sjkim*/installation/common/ 67276864Sjkim Directory for multi-architecture installation notes files. 68276864Sjkim Note that the FreeBSD DocProj build infrastructure does 69215698Ssimon not handle documents (or subdirectories) named "install" 70276864Sjkim well, so we call our document "installation" and do 71110010Smarkm a hack when it gets installed into a distribution to fix 72110010Smarkm this up. 73110010Smarkm*/installation/*/ 74110010Smarkm Directories for architecture-specific release notes files. 75110010Smarkm 76110010Smarkm*/errata/ 77110010Smarkm Directory for errata document. 78110010Smarkm 79110010Smarkm*/readme/ 80110010Smarkm Directory for (introductory) document. 81110010Smarkm 82110010SmarkmIf building the release notes "standalone" (in other words, not part 83110010Smarkmof a release), it may be necessary (depending on the relative 84110010Smarkmlocations of the checked-out src/ and doc/ directories) to set the 85110010SmarkmDOC_PREFIX Makefile variable to point to the top directory of the doc/ 86110010Smarkmtree. For example: 87110010Smarkm 88110010Smarkm % make DOC_PREFIX=/usr/doc all 89110010Smarkm 90110010SmarkmAll definition of the "current" version of FreeBSD is contained in the 91110010Smarkmshare/sgml/release.ent file; release engineers should peruse the 92110010Smarkmcontents of this file carefully when doing version number bumps. 93110010Smarkm 94110010SmarkmWhen creating content for the architecture-dependent files, authors 95110010Smarkmshould use the arch= attribute to elements that are specific to a 96110010Smarkmparticular machine architecture. The value of this attribute should 97110010Smarkmbe a single word that indicates for which architecture the current 98110010Smarkmelement will be included. For example: 99110010Smarkm 100110010Smarkm <para arch="alpha">Alpha-specific text</para> 101110010Smarkm 102110010SmarkmThe currently-supported architectures are i386 and alpha. As of this 103110010Smarkmwriting there is no mechanism for supporting multiple architectures 104110010Smarkm(i.e. arch="alpha,ia64"), but with some work in the stylesheets this 105110010Smarkmshould be possible. 106110010Smarkm 107110010SmarkmWhen creating a translation, make a new directory under this 108110010Smarkmdirectory with a language code (paralleling the DocProj directory 109110010Smarkmstructure). If necessary, new language-dependent HTML footers can be 110110010Smarkmgenerated by making a new language-dependent 111110010Smarkm${LANG}/share/sgml/release.dsl, a ${LANG}/share/sgml/catalog that 112110010Smarkmpoints to it, and a new definition in the Makefiles that adds 113110010Smarkm${LANG}/share/sgml/catalog to EXTRA_CATALOGS. Except for the Makefile 114110010Smarkmchanges, this is the same procedure that is used for creating a new 115110010Smarkmtranslation for DocProj files. 116110010Smarkm 117110010SmarkmRELNOTESng is now enabled by default in the FreeBSD release-build 118110010Smarkmprocess. It can be disabled by setting NODOC=YES when building a 119110010Smarkmrelease (note that this is the same variable that disables DocProj 120110010Smarkmdocumentation builds). 121110010Smarkm 122110010SmarkmRelease builders can set which language gets built with the 123110010SmarkmRELNOTES_LANG variable; note that this is different from the 124110010SmarkmDOC_LANG variable because (at least intially) most languages 125110010Smarkmwill have localized DocProj files but not localized release notes. 126110010SmarkmThe default language, if none is specified, is en_US.ISO8859-1. 127110010Smarkm 128110010Smarkm