README revision 76138
1-*- text -*- 2RELNOTESng README 3Bruce A. Mah <bmah@freebsd.org> 4$FreeBSD: head/release/doc/README 76138 2001-04-29 19:24:32Z 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/sgml/*.dsl 22 Architecture-dependent stylesheets. These stylesheets support 23 the arch= attribute on (all?) DocBook elements. Currently- 24 supported values are: i386, alpha. 25share/sgml/release.ent 26 Release information. Need to update the entry definitions in 27 this file when rolling new revisions; these should take effect 28 in all documents. 29 30*/relnotes/common/ 31 Directory for multi-architecture release notes files. 32*/relnotes/*/ 33 Directories for architecture-specific release notes files. 34 35*/hardware/common/ 36 Directory for multi-architecture hardware notes files. 37*/hardware/*/ 38 Directories for architecture-specific hardware notes files. 39 40*/installation/common/ 41 Directory for multi-architecture installation notes files. 42 Note that the FreeBSD DocProj build infrastructure does 43 not handle documents (or subdirectories) named "install" 44 well, so we call our document "installation" and do 45 a hack when it gets installed into a distribution to fix 46 this up. 47*/installation/*/ 48 Directories for architecture-specific release notes files. 49 50*/errata/ 51 Directory for errata document. 52 53*/readme/ 54 Directory for (introductory) document. 55 56If building the release notes "standalone" (in other words, not part 57of a release), it may be necessary (depending on the relative 58locations of the checked-out src/ and doc/ directories) to set the 59DOC_PREFIX Makefile variable to point to the top directory of the doc/ 60tree. For example: 61 62 % make DOC_PREFIX=/usr/doc all 63 64All definition of the "current" version of FreeBSD is contained in the 65share/sgml/release.ent file; release engineers should peruse the 66contents of this file carefully when doing version number bumps. 67 68When creating content for the architecture-dependent files, authors 69should use the arch= attribute to elements that are specific to a 70particular machine architecture. The value of this attribute should 71be a single word that indicates for which architecture the current 72element will be included. For example: 73 74 <para arch="alpha">Alpha-specific text</para> 75 76The currently-supported architectures are i386 and alpha. As of this 77writing there is no mechanism for supporting multiple architectures 78(i.e. arch="alpha,ia64"), but with some work in the stylesheets this 79should be possible. 80 81When creating a translation, make a new directory under this 82directory with a language code (paralleling the DocProj directory 83structure). 84 85RELNOTESng is supported in the FreeBSD release-build process. For 86now, the building of RELNOTESng is enabled by RELNOTESNG=YES when 87building a release. Note that setting RELNOTESng requires that both 88NODOC and NOPORTS *not* be set, as RELNOTESng require parts of 89both. Eventually, RELNOTESNG will be made the default. 90 91Release builders can set which language gets built with the 92RELNOTESNG_LANG variable; note that this is different from the 93DOC_LANG variable because (at least intially) most languages 94will have localized DocProj files but not localized release notes. 95The default language, if none is specified, is en_US.ISO_8859-1. 96 97