[Plplot-cvs] SF.net SVN: plplot:[11337] trunk/doc/docbook/README.developers

[<ai...@us...>]

Revision: 11337
          http://plplot.svn.sourceforge.net/plplot/?rev=11337&view=rev
Author:   airwin
Date:     2010-11-19 22:58:46 +0000 (Fri, 19 Nov 2010)

Log Message:
-----------
Add a list of the back-end tools used to build PLplot documentation
in various formats from our DocBook source files.

Modified Paths:
--------------
    trunk/doc/docbook/README.developers

Modified: trunk/doc/docbook/README.developers
===================================================================
--- trunk/doc/docbook/README.developers	2010-11-19 20:08:26 UTC (rev 11336)
+++ trunk/doc/docbook/README.developers	2010-11-19 22:58:46 UTC (rev 11337)
@@ -31,14 +31,65 @@
 is only available on Linux so you will need a Linux system to do a
 documentation build.
 
-If you are in a hurry you can validate your changes to the files in
-doc/docbook/src by simply typing the
+The DocBook Back-end Tool Chains
+================================
 
+PLplot uses a number of different applications to generate
+PLplot documentation in various formats from our source DocBook XML files.
+
+1.  man pages.
+
+Our man pages are generated with a configured home-brew perl script
+bin/api2man.pl(.in). That script uses XML::DOM::Parser to parse the
+combination of plplotdoc.xml (for entity definitions) and api.xml
+(the subset of our DocBook source files which describes our core
+library's API) to obtain the information used to generate the man
+pages.
+
+2. info pages.
+
+Our info pages are generated by a combination of 
+
+bin/info-clean.pl --> db2x_xsltproc --> db2x_texixml --> makeinfo
+
+where info-clean.pl is a home-brew perl script required (as far as I
+can tell from reading comments in it) to get around some of the
+db2x_xsltproc limitations.  db2x_xsltproc and db2x_texixml are from
+the docbook2x package.
+
+3. web pages.
+
+Our web pages are generated with openjade.
+
+4. dvi file
+
+Our dvi file is generated by
+
+openjade --> jadetex
+
+
+5. PostScript file
+
+Our PostScript file is generated from the above dvi file
+using dvips.
+
+
+6. pdf file
+
+openjade --> pdfjadetex
+
+Validation
+==========
+
+Validation checks that the PLplot Docbook files in doc/docbook/src are
+well-formed XML and correspond to the DocBook schema.  You can perform
+such validation by typing the
+
 make validate
 
 command at the top of the build tree.  This make target is only available if
 the PLplot CMake-based build system has found the onsgmls software
-application (which is distributed as part of openjade) on your system. This
+application (which is distributed as part of OpenSP) on your system. This
 quick check works regardless of whether you decide to build the
 documentation with -DBUILD_DOC=ON or not. Using "make validate" is
 especially useful if you are just making a series of simple changes to the


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.