/release/doc/README

https://bitbucket.org/freebsd/freebsd-head/ · #! · 127 lines · 107 code · 20 blank · 0 comment · 0 complexity · 39c9a9506639f958c907d56146d8726e MD5 · raw file

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