README revision 158627
1285SN/A-*- text -*- 2367SN/ARELNOTESng README 3285SN/ABruce A. Mah <bmah@freebsd.org> 4285SN/A$FreeBSD: head/release/doc/README 158627 2006-05-15 21:10:34Z wilko $ 5285SN/A 6285SN/AThis is the top-level directory for RELNOTESng, a re-write of 7285SN/AFreeBSD's *.TXT documentation files. They have been converted to 8285SN/ADocBook, and versions of the documents can be now be built for various 9285SN/Asupported architectures. The output files can be rendered in any 10285SN/Aformat supported by the FreeBSD Documentation Project (for example, 11285SN/AASCII text, PDF, PS, HTML). 12285SN/A 13285SN/ARELNOTESng requires that the FreeBSD doc/ sources are installed; it 14285SN/Aleverages off of much of the DocProj build infrastructure, including 15285SN/ADocBook extensions and stylesheets. If the doc/ sources are not 16285SN/Ainstalled in /usr/src, their location should be specified with the 17285SN/ADOC_PREFIX Makefile variable. RELNOTESng also requires the DocProj 18285SN/Abuild tools, which can easily be installed with the textproc/docproj 19285SN/Aport in the Ports Collection. 20285SN/A 21285SN/ANotable files and directories: 22285SN/A 23285SN/Ashare/mk/doc.relnotes.mk 24285SN/A Common Makefile definitions for RELNOTESng. These definitions 25285SN/A mostly accommodate the fact that we're building DocProj-like 26285SN/A documents outside the doc/ tree. 27285SN/Ashare/sgml/catalog 28285SN/A Main SGML catalog for all language-neutral (and default EN) 29285SN/A stylesheet and entity files. Can be overridden if needed for 30285SN/A translations. 31285SN/Ashare/sgml/default.dsl 32285SN/A All documents build with this file as a stylesheet. All it 33285SN/A does is to make it possible to use the document catalogs to 34285SN/A locate the "real" stylesheet by reference, rather than having 35285SN/A to specify it by pathname. 36285SN/Ashare/sgml/release.dsl 37285SN/A Language-neutral stylesheet. This stylesheet supports 38285SN/A the arch= attribute on (all?) DocBook elements; elements with 39285SN/A an arch= attribute are only included in the output if their 40285SN/A value is equal to the value of the &arch; entity. In the 41285SN/A future, arch= could be a list of possible &arch; entity values 42285SN/A that match, such as "i386,sparc64". 43285SN/Ashare/sgml/release.ent 44285SN/A Release information. Need to update the entry definitions in 45285SN/A this file when rolling new revisions; these should take effect 46285SN/A in all documents. 47285SN/A 48285SN/Aen_US.ISO8859-1/share/sgml/release.dsl 49285SN/A Language-dependent stylesheet for en, but also the default for 50285SN/A translations if they don't override the settings here. This 51285SN/A stylesheet sets the email footer at the bottom of HTML pages, 52285SN/A as well as a few other parameters. If necessary for 53285SN/A translations, this file can be overridden with 54285SN/A */share/sgml/release.dsl and */share/sgml/catalog. 55285SN/A 56285SN/A*/relnotes/common/ 57285SN/A Directory for multi-architecture release notes files. 58285SN/A*/relnotes/*/ 59285SN/A Directories for architecture-specific release notes files. 60285SN/A 61285SN/A*/hardware/common/ 62285SN/A Directory for multi-architecture hardware notes files. 63285SN/A*/hardware/*/ 64285SN/A Directories for architecture-specific hardware notes files. 65285SN/A 66285SN/A*/installation/common/ 67285SN/A Directory for multi-architecture installation notes files. 68285SN/A Note that the FreeBSD DocProj build infrastructure does 69285SN/A not handle documents (or subdirectories) named "install" 70285SN/A well, so we call our document "installation" and do 71285SN/A a hack when it gets installed into a distribution to fix 72285SN/A this up. 73285SN/A*/installation/*/ 74285SN/A Directories for architecture-specific release notes files. 75285SN/A 76285SN/A*/errata/ 77285SN/A Directory for errata document. 78285SN/A 79285SN/A*/readme/ 80285SN/A Directory for (introductory) document. 81285SN/A 82285SN/AIf building the release notes "standalone" (in other words, not part 83285SN/Aof a release), it may be necessary (depending on the relative 84285SN/Alocations of the checked-out src/ and doc/ directories) to set the 85285SN/ADOC_PREFIX Makefile variable to point to the top directory of the doc/ 86285SN/Atree. For example: 87285SN/A 88285SN/A % make DOC_PREFIX=/usr/doc all 89367SN/A 90285SN/AAll definition of the "current" version of FreeBSD is contained in the 91367SN/Ashare/sgml/release.ent file; release engineers should peruse the 92285SN/Acontents of this file carefully when doing version number bumps. 93285SN/A 94285SN/AWhen creating content for the architecture-dependent files, authors 95285SN/Ashould use the arch= attribute to elements that are specific to a 96367SN/Aparticular machine architecture. The value of this attribute should 97285SN/Abe a single word that indicates for which architecture the current 98285SN/Aelement will be included. For example: 99285SN/A 100285SN/A <para arch="sparc64">SPARC64-specific text</para> 101285SN/A 102285SN/AThe currently-supported architectures are i386, sparc64, and 103285SN/Aia64. An element may appear for multiple architectures by specifying 104285SN/Aa comma-separated list of architectures (i.e. arch="sparc64,ia64"). 105285SN/A 106285SN/AWhen creating a translation, make a new directory under this 107285SN/Adirectory with a language code (paralleling the DocProj directory 108285SN/Astructure). If necessary, new language-dependent HTML footers can be 109285SN/Agenerated by making a new language-dependent 110285SN/A${LANG}/share/sgml/release.dsl, a ${LANG}/share/sgml/catalog that 111285SN/Apoints to it, and a new definition in the Makefiles that adds 112285SN/A${LANG}/share/sgml/catalog to EXTRA_CATALOGS. Except for the Makefile 113285SN/Achanges, this is the same procedure that is used for creating a new 114285SN/Atranslation for DocProj files. 115285SN/A 116285SN/ARELNOTESng is now enabled by default in the FreeBSD release-build 117285SN/Aprocess. It can be disabled by setting NODOC=YES when building a 118285SN/Arelease (note that this is the same variable that disables DocProj 119285SN/Adocumentation builds). 120285SN/A 121285SN/ARelease builders can set which language gets built with the 122285SN/ARELNOTES_LANG variable; note that this is different from the 123285SN/ADOC_LANG variable because (at least initially) most languages 124367SN/Awill have localized DocProj files but not localized release notes. 125285SN/AThe default language, if none is specified, is en_US.ISO8859-1. 126285SN/A 127285SN/A