README revision 268351
1272343Sngie-*- text -*- 2272343SngieRELNOTESng README 3272343SngieBruce A. Mah <bmah@freebsd.org> 4272343Sngie$FreeBSD: head/release/doc/README 268351 2014-07-07 00:27:09Z marcel $ 5272343Sngie 6272343SngieThis is the top-level directory for RELNOTESng, a re-write of 7272343SngieFreeBSD's *.TXT documentation files. They have been converted to 8272343SngieDocBook, and versions of the documents can be now be built for various 9272343Sngiesupported architectures. The output files can be rendered in any 10272343Sngieformat supported by the FreeBSD Documentation Project (for example, 11272343SngieASCII text, PDF, PS, HTML). 12272343Sngie 13272343SngieRELNOTESng requires that the FreeBSD doc/ sources are installed; it 14272343Sngieleverages off of much of the DocProj build infrastructure, including 15272343SngieDocBook extensions and stylesheets. If the doc/ sources are not 16272343Sngieinstalled in /usr/src, their location should be specified with the 17272343SngieDOC_PREFIX Makefile variable. RELNOTESng also requires the DocProj 18272343Sngiebuild tools, which can easily be installed with the textproc/docproj 19272343Sngieport in the Ports Collection. 20272343Sngie 21272343SngieNotable files and directories: 22272343Sngie 23272343Sngieshare/mk/doc.relnotes.mk 24272343Sngie Common Makefile definitions for RELNOTESng. These definitions 25272343Sngie mostly accommodate the fact that we're building DocProj-like 26272343Sngie documents outside the doc/ tree. 27272343Sngieshare/xml/catalog 28272343Sngie Main SGML catalog for all language-neutral (and default EN) 29272343Sngie stylesheet and entity files. Can be overridden if needed for 30272343Sngie translations. 31272343Sngieshare/xml/default.dsl 32272343Sngie All documents build with this file as a stylesheet. All it 33272343Sngie does is to make it possible to use the document catalogs to 34272343Sngie locate the "real" stylesheet by reference, rather than having 35272343Sngie to specify it by pathname. 36272343Sngieshare/xml/release.dsl 37272343Sngie Language-neutral stylesheet. This stylesheet supports 38272343Sngie the arch= attribute on (all?) DocBook elements; elements with 39272343Sngie an arch= attribute are only included in the output if their 40272343Sngie value is equal to the value of the &arch; entity. In the 41272343Sngie future, arch= could be a list of possible &arch; entity values 42272343Sngie that match, such as "i386,sparc64". 43272343Sngieshare/xml/release.ent 44272343Sngie Release information. Need to update the entry definitions in 45272343Sngie this file when rolling new revisions; these should take effect 46272343Sngie in all documents. 47272343Sngie 48272343Sngieen_US.ISO8859-1/share/xml/release.dsl 49272343Sngie Language-dependent stylesheet for en, but also the default for 50272343Sngie translations if they don't override the settings here. This 51272343Sngie stylesheet sets the email footer at the bottom of HTML pages, 52272343Sngie as well as a few other parameters. If necessary for 53272343Sngie translations, this file can be overridden with 54272343Sngie */share/xml/release.dsl and */share/xml/catalog. 55272343Sngie 56272343Sngie*/relnotes/common/ 57272343Sngie Directory for multi-architecture release notes files. 58272343Sngie*/relnotes/*/ 59272343Sngie Directories for architecture-specific release notes files. 60272343Sngie 61272343Sngie*/hardware/common/ 62272343Sngie Directory for multi-architecture hardware notes files. 63272343Sngie*/hardware/*/ 64272343Sngie Directories for architecture-specific hardware notes files. 65272343Sngie 66272343Sngie*/installation/common/ 67272343Sngie Directory for multi-architecture installation notes files. 68272343Sngie Note that the FreeBSD DocProj build infrastructure does 69272343Sngie not handle documents (or subdirectories) named "install" 70272343Sngie well, so we call our document "installation" and do 71272343Sngie a hack when it gets installed into a distribution to fix 72272343Sngie this up. 73272343Sngie*/installation/*/ 74272343Sngie Directories for architecture-specific release notes files. 75272343Sngie 76272343Sngie*/errata/ 77272343Sngie Directory for errata document. 78272343Sngie 79272343Sngie*/readme/ 80272343Sngie Directory for (introductory) document. 81272343Sngie 82272343SngieIf building the release notes "standalone" (in other words, not part 83272343Sngieof a release), it may be necessary (depending on the relative 84272343Sngielocations of the checked-out src/ and doc/ directories) to set the 85272343SngieDOC_PREFIX Makefile variable to point to the top directory of the doc/ 86272343Sngietree. For example: 87272343Sngie 88272343Sngie % make DOC_PREFIX=/usr/doc all 89272343Sngie 90272343SngieAll definition of the "current" version of FreeBSD is contained in the 91272343Sngieshare/xml/release.ent file; release engineers should peruse the 92272343Sngiecontents of this file carefully when doing version number bumps. 93272343Sngie 94272343SngieWhen creating content for the architecture-dependent files, authors 95272343Sngieshould use the arch= attribute to elements that are specific to a 96272343Sngieparticular machine architecture. The value of this attribute should 97272343Sngiebe a single word that indicates for which architecture the current 98272343Sngieelement will be included. For example: 99272343Sngie 100272343Sngie <para arch="sparc64">SPARC64-specific text</para> 101272343Sngie 102272343SngieThe currently-supported architectures are amd64, arm, i386, pc98, 103272343Sngiepowerpc and sparc64. An element may appear for multiple architectures 104272343Sngieby specifying a comma-separated list of architectures 105272343Sngie(i.e. arch="sparc64,amd64"). 106272343Sngie 107272343SngieWhen creating a translation, make a new directory under this 108272343Sngiedirectory with a language code (paralleling the DocProj directory 109272343Sngiestructure). If necessary, new language-dependent HTML footers can be 110272343Sngiegenerated by making a new language-dependent 111272343Sngie${LANG}/share/xml/release.dsl, a ${LANG}/share/xml/catalog that 112272343Sngiepoints to it, and a new definition in the Makefiles that adds 113272343Sngie${LANG}/share/xml/catalog to EXTRA_CATALOGS. Except for the Makefile 114272343Sngiechanges, this is the same procedure that is used for creating a new 115272343Sngietranslation for DocProj files. 116272343Sngie 117272343SngieRELNOTESng is now enabled by default in the FreeBSD release-build 118272343Sngieprocess. It can be disabled by setting NODOC=YES when building a 119272343Sngierelease (note that this is the same variable that disables DocProj 120272343Sngiedocumentation builds). 121272343Sngie 122272343SngieRelease builders can set which language gets built with the 123272343SngieRELNOTES_LANG variable; note that this is different from the 124272343SngieDOC_LANG variable because (at least initially) most languages 125272343Sngiewill have localized DocProj files but not localized release notes. 126272343SngieThe default language, if none is specified, is en_US.ISO8859-1. 127272343Sngie 128272343Sngie