README revision 86150
155714Skris-*- text -*- 255714SkrisRELNOTESng README 355714SkrisBruce A. Mah <bmah@freebsd.org> 455714Skris$FreeBSD: head/release/doc/README 86150 2001-11-06 21:17:25Z olgeni $ 555714Skris 655714SkrisThis is the top-level directory for RELNOTESng, a re-write of 755714SkrisFreeBSD's *.TXT documentation files. They have been converted to 855714SkrisDocBook, and versions of the documents can be now be built for various 955714Skrissupported architectures. The output files can be rendered in any 1055714Skrisformat supported by the FreeBSD Documentation Project (for example, 1155714SkrisASCII text, PDF, PS, HTML). 1255714Skris 1368651SkrisRELNOTESng requires that the FreeBSD doc/ sources are installed; it 1455714Skrisleverages off of much of the DocProj build infrastructure, including 1555714SkrisDocBook extensions and stylesheets. If the doc/ sources are not 1655714Skrisinstalled in /usr/src, their location should be specified with the 1755714SkrisDOC_PREFIX Makefile variable. RELNOTESng also requires the DocProj 1855714Skrisbuild tools, which can easily be installed with the textproc/docproj 1955714Skrisport in the Ports Collection. 2055714Skris 2155714SkrisNotable files and directories: 2255714Skris 2355714Skrisshare/mk/doc.relnotes.mk 2455714Skris Common Makefile definitions for RELNOTESng. These definitions 2555714Skris mostly accommodate the fact that we're building DocProj-like 26109998Smarkm documents outside the doc/ tree. 2755714Skrisshare/sgml/catalog 2855714Skris Main SGML catalog for all language-neutral (and default EN) 2955714Skris stylesheet and entity files. Can be overridden if needed for 3068651Skris translations. 3155714Skrisshare/sgml/default.dsl 32109998Smarkm All documents build with this file as a stylesheet. All it 3355714Skris does is to make it possible to use the document catalogs to 3455714Skris locate the "real" stylesheet by reference, rather than having 3555714Skris to specify it by pathname. 3655714Skrisshare/sgml/release.dsl 3755714Skris Language-neutral stylesheet. This stylesheet supports 3855714Skris the arch= attribute on (all?) DocBook elements; elements with 3955714Skris an arch= attribute are only included in the output if their 4055714Skris value is equal to the value of the &arch; entity. In the 4155714Skris future, arch= could be a list of possible &arch; entity values 4255714Skris that match, such as "i386,alpha". 4355714Skrisshare/sgml/release.ent 4455714Skris Release information. Need to update the entry definitions in 4555714Skris this file when rolling new revisions; these should take effect 4655714Skris in all documents. 4755714Skris 4855714Skrisen_US.ISO8859-1/share/sgml/release.dsl 4955714Skris Language-dependent stylesheet for en, but also the default for 50109998Smarkm translations if they don't override the settings here. This 51109998Smarkm stylesheet sets the email footer at the bottom of HTML pages, 52109998Smarkm as well as a few other parameters. If necessary for 53109998Smarkm translations, this file can be overridden with 5455714Skris */share/sgml/release.dsl and */share/sgml/catalog. 5555714Skris 5655714Skris*/relnotes/common/ 5755714Skris Directory for multi-architecture release notes files. 5855714Skris*/relnotes/*/ 5955714Skris Directories for architecture-specific release notes files. 6055714Skris 6155714Skris*/hardware/common/ 6255714Skris Directory for multi-architecture hardware notes files. 6355714Skris*/hardware/*/ 6455714Skris Directories for architecture-specific hardware notes files. 6555714Skris 6655714Skris*/installation/common/ 6755714Skris Directory for multi-architecture installation notes files. 6855714Skris Note that the FreeBSD DocProj build infrastructure does 6955714Skris not handle documents (or subdirectories) named "install" 7055714Skris well, so we call our document "installation" and do 7155714Skris a hack when it gets installed into a distribution to fix 7255714Skris this up. 7355714Skris*/installation/*/ 7455714Skris Directories for architecture-specific release notes files. 7555714Skris 7655714Skris*/errata/ 7755714Skris Directory for errata document. 7855714Skris 7955714Skris*/readme/ 8055714Skris Directory for (introductory) document. 8155714Skris 8255714SkrisIf building the release notes "standalone" (in other words, not part 8355714Skrisof a release), it may be necessary (depending on the relative 8455714Skrislocations of the checked-out src/ and doc/ directories) to set the 8555714SkrisDOC_PREFIX Makefile variable to point to the top directory of the doc/ 8655714Skristree. For example: 8755714Skris 8855714Skris % make DOC_PREFIX=/usr/doc all 8955714Skris 9055714SkrisAll definition of the "current" version of FreeBSD is contained in the 9155714Skrisshare/sgml/release.ent file; release engineers should peruse the 9255714Skriscontents of this file carefully when doing version number bumps. 9355714Skris 9455714SkrisWhen creating content for the architecture-dependent files, authors 9555714Skrisshould use the arch= attribute to elements that are specific to a 9655714Skrisparticular machine architecture. The value of this attribute should 9755714Skrisbe a single word that indicates for which architecture the current 9855714Skriselement will be included. For example: 9955714Skris 10055714Skris <para arch="alpha">Alpha-specific text</para> 10155714Skris 10255714SkrisThe currently-supported architectures are i386 and alpha. As of this 10355714Skriswriting there is no mechanism for supporting multiple architectures 10455714Skris(i.e. arch="alpha,ia64"), but with some work in the stylesheets this 10555714Skrisshould be possible. 10655714Skris 10755714SkrisWhen creating a translation, make a new directory under this 10855714Skrisdirectory with a language code (paralleling the DocProj directory 10955714Skrisstructure). If necessary, new language-dependent HTML footers can be 11055714Skrisgenerated by making a new language-dependent 11155714Skris${LANG}/share/sgml/release.dsl, a ${LANG}/share/sgml/catalog that 11255714Skrispoints to it, and a new definition in the Makefiles that adds 11355714Skris${LANG}/share/sgml/catalog to EXTRA_CATALOGS. Except for the Makefile 11455714Skrischanges, this is the same procedure that is used for creating a new 11555714Skristranslation for DocProj files. 11655714Skris 11755714SkrisRELNOTESng is now enabled by default in the FreeBSD release-build 118process. It can be disabled by setting NODOC=YES when building a 119release (note that this is the same variable that disables DocProj 120documentation builds). 121 122Release builders can set which language gets built with the 123RELNOTES_LANG variable; note that this is different from the 124DOC_LANG variable because (at least initially) most languages 125will have localized DocProj files but not localized release notes. 126The default language, if none is specified, is en_US.ISO8859-1. 127 128