README.guide

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.