This directory holds the DocBook (DB) documentation for BRL-CAD. Over
time, this should become the repository for all tutorials, man pages,
and other non-autogenerated, formatted documentation for BRL-CAD.

The xsl stylesheets for docbook are presently in the
"resources/other/standard" directory.

The current structure is as follows:

articles/
	Individual articles on specific topics - oed and tire live here,
	as well as the articles that made up the appendices of Vol III.

books/
	Either compilations of smaller documents into large works, or
	individual self contained works.  Most of Volume III is in a
	single file in this subtree.

lessons/
	Individual documents intended to teach some aspect of BRL-CAD
	to new users/students.  At this time it contains the individual
	lessons that made up Volume II.

resources/
	The DocBook xsl files are contained within the "other"
	subdirectory.  Also included there are various directories and
	files associated with DB validation, fonts, snd hyphenation.
	The "brlcad" subdirectory contains files customized for
	BRL-CAD products including common files and images.

system/
	Documentation similar to traditional Unix "man" pages - focused
	documentation on specific parts of BRL-CAD.  There is a template
        for authors of mged command man pages at:

          ./system/mann/mged_cmd_template.xml

presentations/
	Copies of briefings (slides or slides converted to documents,
	e.g., "Introduction to Tcl/Tk."


LANGUAGE CONSIDERATIONS
-----------------------

English documents are in 'en' sub-directories.  Other languages are
found in standard two-character sub-directories.  See, for example,
the Spanish translations in 'lessons/es'.  Currently, the following
language codes may be found in various sub-directories:

  * en - English
  * es - Spanish
  * hy - Armenian
  * it - Italian
  * ru - Russian

See <http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes> for one
listing of ISO language codes.

English DocBook source files are expected to be ASCII with xhtml
unicode markup for non-ASCII symbols.  Other language source files
should be in UTF-8.

Notes on equation generation in svg, lists of common symbols and their
unicode DB symbols, and other notes on DB authoring tips are found in
the file 'README.DB_authors_notes'.

The text character code requirements may eventually be enforced by a
pre-commit hook script.

CONVERTING MAN FORMAT TO DOCBBOOK
---------------------------------

The doclifter program (available in a Debian or Ubuntu distribution)
can give a first-order conversion from the man page format (roff,
nroff, troff, or groff) to DocBook xml.

DOCBOOK PROCESSING
------------------

Currently there are three products generated from DB source:  

  * man pages

  * html documents

  * pdf documents

There are some external tools required in order to produce those
documents:

  For all DB documents (man, html, and pdf):

    * xsltproc
        a program that comes with libxslt (see http://xmlsoft.org/XSLT/)

    * saxon-he
        an Open Source java xslt processor (capable of using XSLT 2.0
        and the new DB XSLT 2.0 stylesheets released on 2011-08-25
        [not yet used or provided with BRL-CAD]) (see
        http://saxon.sourceforge.net/)

  For pdf documents:

    * fop
        a java program provide by the Apache Software Foundation; note
        that a minimum of version 1.0 is required to use the
        hyphenation binaries provided in thre resources sub-directory
        (see http://xmlgraphics.apache.org/fop/).  Also, version 1.0
        has some new font support features and we recommend using that
        version (or later) for DB processing.

    * Java
        a working Java run-time environment

    * scribus
        an Open Source page layout program; use to convert eps to svg
        (see http://www.scribus.net)

  For checking the well-formedness of any xml document:

    * xmllint
        a program that comes with libxml2 (see http://xmlsoft.org/)

  For creating and editing svg equations:

    * LibreOffice
        a free office suite whose text editor can be used to create
        and edit equations and export them to MathML (mml) files (see
        http://www.libreoffice.org/)

    * Inkscape
        a powerful and free vector drawing editor (see
        http://inkscape.org)

    * math2svg 
        a program (from the SVGMath suite) to convert MathML xml
        format to SVG xml format (see
        http://http://grigoriev.ru/svgmath/ and
        http://sourceforge.net/projects/svgmath/)

        Note that the output sometimes needs further editing either
        manually or by inkscape.

See this link for help in installing fop 1.0 and saxon-he on Ubuntu:

  http://johnbokma.com/mexit/2011/07/04/

VALIDATION
----------

It is possible to add a validation step to DocBook compilation by
defining the CMake variable BRLCAD_EXTRADOCS_VALIDATE to ON.

By default, this will use xmllint to validate the xml files as
they are built.

In order to use a different validation program the user must obtain some
external tools that are not presently part of the BRL-CAD package:

  For the 'msv' validation method (a recommended method):

    * msv 
        Oracle Multi-Schema XML Validator (MSV) (see http://msv.java.net/)

    * Java
        a working Java run-time environment

  For the 'nvdl' validation method:

    * onvdl.jar
        a Java jar file with the oNVDL validation tool (see 
        https://sourceforge.net/projects/onvdl/

    * Java
        a working Java run-time environment

  For the 'rnv' validation method:

    * rnv
        http://sourceforge.net/projects/rnv/

    * expat library
        present in most Linux/Unix distributions, see
        http://expat.sourceforge.net/

To use these tools, a <toolname>.cmake.in file must be present
in the misc/CMake source directory.  This file tells CMake how
to run the tool in question.  Examples for msv and rnv are already
present - see misc/CMake/rnv.cmake.in and misc/CMake/msv.cmake.in

Once the correct file is present, configure CMake with options
similar to the following (alter for your specific tool):

cmake .. -DBRLCAD_EXTRADOCS_VALIDATE=ON -DVALIDATE_EXECUTABLE=msv
    
 
OTHER CONSIDERATIONS
--------------------

These documents make extensive use of the XInclude modular
documentation specification. Consequently, the contents of any one
particular "document" may be scattered over many other documents.
This design direction is intended to allow re-use of standard
definitions and descriptions in multiple documents serving multiple
purposes.  When a definition is updated for one document,
re-generation of other documents will incorporate the update as well
without requiring redundant editing.

Caution - the BRL-CAD build logic is not aware of the interlinking of
various xml files using xinclude.  This means that a change on one document
may make other output files out of date, and this will not trigger a
re-build of those files automatically.

Notes:

* When rendered to html output and placed on a server, there may arise
  a problem where the server supplies the page as ISO-8859-1 encoded
  despite them actually using UTF-8.  To combat this problem in the
  case of the Apache web server, an .htaccess file in the directory 
  with the line:

    AddDefaultCharset UTF-8

  should let Apache know to use UTF-8 encoding for these pages.
