Notes for how to prepare release documentation

Prerequisites

  1. Install textproc/docproj.

  2. Checkout svn+ssh://svn.freebsd.org/doc/head to ${DOCBASE} (~/doc, for example).

  3. Checkout svn+ssh://svn.freebsd.org/base/stable/10 to ${SRCBASE} (~/src, for example).

Build instructions

 % cd ${SRCBASE}/release/doc/en_US_ISO8859-1
 % make DOC_PREFIX=${DOCBASE}

After the above commands, release/doc/* directories will have article.html:

The source files are */article.xml. Note that the hardware notes is not a simple XML->HTML translation. It extract hardware support information from ${SRCPREFIX}/share/man/man4*/*. So, just checking out ${SRCPREFIX}/release/doc does not work.

The resulting HTML files are used in ${DOCBASE}/en_US.ISO8859-1/htdocs/releases/{N.N}R/. The following rule is used for the filenames:

These files are copied and committed for each release. Do not directly edit the HTML file. Update the XML source and build an HTML result whenever possible.

TODO items for 10.0R

  1. First, please review readme/article.xml, installation/article.xml, and hardware/article.xml first. These are really outdated and need to be updated. Edit the source file and check if the build works. You can commit your change, but please submit it to me if you are not sure of XML syntax.
  2. The release notes needs to be trimmed and fixing some old tricks in the stylesheet. So, I will commit the necessary changes shortly and split the contents and document structure to simplify the updating work for individual items.

ReleaseEngineering/ReleaseNotesPreparation (last edited 2013-12-17T00:23:55+0000 by CraigRodrigues)