release/doc/README

   1 -*- text -*-
   2 RELNOTESng README
   3 Bruce A. Mah <bmah@freebsd.org>
   4 $FreeBSD: src/release/doc/README,v 1.7.2.3 2002/03/12 05:25:13 bmah Exp $
   5 $DragonFly: src/release/doc/Attic/README,v 1.2 2003/06/17 04:27:19 dillon Exp $
   6
   7 This is the top-level directory for RELNOTESng, a re-write of
   8 FreeBSD's *.TXT documentation files.  They have been converted to
   9 DocBook, and versions of the documents can be now be built for various
  10 supported architectures.  The output files can be rendered in any
  11 format supported by the FreeBSD Documentation Project (for example,
  12 ASCII text, PDF, PS, HTML).
  13
  14 RELNOTESng requires that the FreeBSD doc/ sources are installed; it
  15 leverages off of much of the DocProj build infrastructure, including
  16 DocBook extensions and stylesheets.  If the doc/ sources are not
  17 installed in /usr/src, their location should be specified with the
  18 DOC_PREFIX Makefile variable.  RELNOTESng also requires the DocProj
  19 build tools, which can easily be installed with the textproc/docproj
  20 port in the Ports Collection.
  21
  22 Notable files and directories:
  23
  24 share/mk/doc.relnotes.mk
  25         Common Makefile definitions for RELNOTESng.  These definitions
  26         mostly accomodate the fact that we're building DocProj-like
  27         documents outside the doc/ tree.
  28 share/sgml/catalog
  29         Main SGML catalog for all language-neutral (and default EN)
  30         stylesheet and entity files.  Can be overridden if needed for
  31         translations.
  32 share/sgml/default.dsl
  33         All documents build with this file as a stylesheet.  All it
  34         does is to make it possible to use the document catalogs to
  35         locate the "real" stylesheet by reference, rather than having
  36         to specify it by pathname.
  37 share/sgml/release.dsl
  38         Language-neutral stylesheet.  This stylesheet supports
  39         the arch= attribute on (all?) DocBook elements; elements with
  40         an arch= attribute are only included in the output if their
  41         value is equal to the value of the &arch; entity.  In the
  42         future, arch= could be a list of possible &arch; entity values
  43         that match, such as "i386,alpha".
  44 share/sgml/release.ent
  45         Release information.  Need to update the entry definitions in
  46         this file when rolling new revisions; these should take effect
  47         in all documents.
  48
  49 en_US.ISO8859-1/share/sgml/release.dsl
  50         Language-dependent stylesheet for en, but also the default for
  51         translations if they don't override the settings here.  This
  52         stylesheet sets the email footer at the bottom of HTML pages,
  53         as well as a few other parameters.  If necessary for
  54         translations, this file can be overridden with
  55         */share/sgml/release.dsl and */share/sgml/catalog.
  56
  57 */relnotes/common/
  58         Directory for multi-architecture release notes files.
  59 */relnotes/*/
  60         Directories for architecture-specific release notes files.
  61
  62 */hardware/common/
  63         Directory for multi-architecture hardware notes files.
  64 */hardware/*/
  65         Directories for architecture-specific hardware notes files.
  66
  67 */installation/common/
  68         Directory for multi-architecture installation notes files.
  69         Note that the FreeBSD DocProj build infrastructure does
  70         not handle documents (or subdirectories) named "install"
  71         well, so we call our document "installation" and do
  72         a hack when it gets installed into a distribution to fix
  73         this up.
  74 */installation/*/
  75         Directories for architecture-specific release notes files.
  76
  77 */errata/
  78         Directory for errata document.
  79
  80 */readme/
  81         Directory for (introductory) document.
  82
  83 If building the release notes "standalone" (in other words, not part
  84 of a release), it may be necessary (depending on the relative
  85 locations of the checked-out src/ and doc/ directories) to set the
  86 DOC_PREFIX Makefile variable to point to the top directory of the doc/
  87 tree.  For example:
  88
  89          % make DOC_PREFIX=/usr/doc all
  90
  91 All definition of the "current" version of FreeBSD is contained in the
  92 share/sgml/release.ent file; release engineers should peruse the
  93 contents of this file carefully when doing version number bumps.
  94
  95 When creating content for the architecture-dependent files, authors
  96 should use the arch= attribute to elements that are specific to a
  97 particular machine architecture.  The value of this attribute should
  98 be a single word that indicates for which architecture the current
  99 element will be included.  For example:
 100
 101         <para arch="alpha">Alpha-specific text</para>
 102
 103 The currently-supported architectures are i386 and alpha.
 104 An element may appear for multiple architectures by specifying
 105 a comma-separated list of architectures (i.e. arch="alpha,ia64").
 106
 107 When creating a translation, make a new directory under this
 108 directory with a language code (paralleling the DocProj directory
 109 structure).  If necessary, new language-dependent HTML footers can be
 110 generated by making a new language-dependent
 111 ${LANG}/share/sgml/release.dsl, a ${LANG}/share/sgml/catalog that
 112 points to it, and a new definition in the Makefiles that adds
 113 ${LANG}/share/sgml/catalog to EXTRA_CATALOGS.  Except for the Makefile
 114 changes, this is the same procedure that is used for creating a new
 115 translation for DocProj files.
 116
 117 RELNOTESng is now enabled by default in the FreeBSD release-build
 118 process.  It can be disabled by setting NODOC=YES when building a
 119 release (note that this is the same variable that disables DocProj
 120 documentation builds).
 121
 122 Release builders can set which language gets built with the
 123 RELNOTES_LANG variable; note that this is different from the
 124 DOC_LANG variable because (at least intially) most languages
 125 will have localized DocProj files but not localized release notes.
 126 The default language, if none is specified, is en_US.ISO8859-1.
 127