README revision 76222
1-*- text -*- 2RELNOTESng README 3Bruce A. Mah <bmah@freebsd.org> 4$FreeBSD: head/release/doc/README 76222 2001-05-02 22:02:50Z bmah $ 5 6This is the top-level directory for RELNOTESng, a re-write of 7FreeBSD's *.TXT documentation files. They have been converted to 8DocBook, and versions of the documents can be now be built for various 9supported architectures. The output files can be rendered in any 10format supported by the FreeBSD Documentation Project (for example, 11ASCII text, PDF, PS, HTML). 12 13RELNOTESng requires that the FreeBSD doc/ sources are installed; it 14leverages off of much of the DocProj build infrastructure, including 15DocBook extensions and stylesheets. If the doc/ sources are not 16installed in /usr/src, their location should be specified with the 17DOC_PREFIX Makefile variable. RELNOTESng also requires the DocProj 18build tools, which can easily be installed with the textproc/docproj 19port in the Ports Collection. 20 21share/mk/doc.relnotes.mk 22 Common Makefile definitions for RELNOTESng. These definitions 23 mostly accomodate the fact that we're building DocProj-like 24 documents outside the doc/ tree. 25share/sgml/release.dsl 26 Language-neutral stylesheet. This stylesheet supports 27 the arch= attribute on (all?) DocBook elements; elements with 28 an arch= attribute are only included in the output if their 29 value is equal to the value of the &arch; entity. In the 30 future, arch= could be a list of possible &arch; entity values 31 that match, such as "i386,alpha". 32share/sgml/release.ent 33 Release information. Need to update the entry definitions in 34 this file when rolling new revisions; these should take effect 35 in all documents. 36 37*/relnotes/common/ 38 Directory for multi-architecture release notes files. 39*/relnotes/*/ 40 Directories for architecture-specific release notes files. 41 42*/hardware/common/ 43 Directory for multi-architecture hardware notes files. 44*/hardware/*/ 45 Directories for architecture-specific hardware notes files. 46 47*/installation/common/ 48 Directory for multi-architecture installation notes files. 49 Note that the FreeBSD DocProj build infrastructure does 50 not handle documents (or subdirectories) named "install" 51 well, so we call our document "installation" and do 52 a hack when it gets installed into a distribution to fix 53 this up. 54*/installation/*/ 55 Directories for architecture-specific release notes files. 56 57*/errata/ 58 Directory for errata document. 59 60*/readme/ 61 Directory for (introductory) document. 62 63If building the release notes "standalone" (in other words, not part 64of a release), it may be necessary (depending on the relative 65locations of the checked-out src/ and doc/ directories) to set the 66DOC_PREFIX Makefile variable to point to the top directory of the doc/ 67tree. For example: 68 69 % make DOC_PREFIX=/usr/doc all 70 71All definition of the "current" version of FreeBSD is contained in the 72share/sgml/release.ent file; release engineers should peruse the 73contents of this file carefully when doing version number bumps. 74 75When creating content for the architecture-dependent files, authors 76should use the arch= attribute to elements that are specific to a 77particular machine architecture. The value of this attribute should 78be a single word that indicates for which architecture the current 79element will be included. For example: 80 81 <para arch="alpha">Alpha-specific text</para> 82 83The currently-supported architectures are i386 and alpha. As of this 84writing there is no mechanism for supporting multiple architectures 85(i.e. arch="alpha,ia64"), but with some work in the stylesheets this 86should be possible. 87 88When creating a translation, make a new directory under this 89directory with a language code (paralleling the DocProj directory 90structure). 91 92RELNOTESng is supported in the FreeBSD release-build process. For 93now, the building of RELNOTESng is enabled by RELNOTESNG=YES when 94building a release. Note that setting RELNOTESng requires that both 95NODOC and NOPORTS *not* be set, as RELNOTESng require parts of 96both. Eventually, RELNOTESNG will be made the default. 97 98Release builders can set which language gets built with the 99RELNOTESNG_LANG variable; note that this is different from the 100DOC_LANG variable because (at least intially) most languages 101will have localized DocProj files but not localized release notes. 102The default language, if none is specified, is en_US.ISO_8859-1. 103 104