Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.

README.guide

0.  Format

    We're writing the Developer Guide in reStructured Text.  Once we're

    happy with the content, we'll output XML and convert that to

    DocBook-XML to hand over to Documentation for final production.

    Heading in rST are based on over- and underlining.  Heading levels

    are a document-specific convention; our levels are as follows:

    ====   ----

    ==== , ---- , ==== , ---- , ~~~~, ````, ^^^^

    Inconsistencies with this ordering will lead to document build

    failure.

1.  Files

    guide-main.rst is the Developer Guide's outline.  It contains the

    main document directives; it may also contain shorter sections,

    prior to being broken out into separate files.

    Each file should begin with its appropriate heading for the Guide as

    a whole.

1.1.  Titles

    Titles are always mixed case.  Particular levels may be set in

    capitals or small capitals by style sheet.

2.  Rest of the directory

    Files not starting with guide- are legacy documents from earlier in

    the project.  If you are rewriting one of these to fit into the

    Guide, please rename them; if you don't feel you're the owner,

    extract the content, and add an "XXX Copied to guide-....rst" in the

    original file.

3.  Tools

    You can obtain docutils by using easy_install via

    $ pfexec easy_install docutils

    With a straight docutils installation, you can build the "html"

    target out of the Makefile.

    To build the PDF version, you will need a pdflatex-capable TeX

    installation, such as TeX Live, which is available for download at

    http://www.tug.org/texlive/

    The Makefile and docutils expect that the TeX executables are

    available via the path.