1                     Notes on the libxml2 Documentation
  2              Prepared by: William Brack <wbrack@mmm.com.hk>
  3  	    
  4    After spending a  lot of time tracing through  Makefile.am, some Python
  5  scripts  and some xsl  scripts and xml files, I  thought it might be good
  6  to save others some time  by setting down the basic information about how
  7  the library documentation  is created.  I intend to enhance this process,
  8  but will keep this document up-to-date for  everyone's information.  Note
  9  that this document does not  apply to the subdirectory  "tutorial", which
 10  is separately maintained by John Fleck.
 11  
 12    There are a relatively  small number of files  which form the "core" of
 13  the document directory.  All  the other files in the directory can be re-
 14  generated using  the information  present in these  core files,  plus the
 15  actual library  source files (*.[ch]) in the parent  directory  "../" and
 16  it's descendants include  and include/libxml.  These core files, together
 17  with a brief description of each, are as follows:-
 18  
 19  xml.html           The "main page", manually produced by Daniel Veillard
 20  news.html          The latest news, extracted from xml.html by site.xsl
 21  
 22  benchmark.gif      Illustrations used for the "main page" and subsidiaries
 23  gnome2.png                              -------
 24  Libxml2-Logo-180x168.gif                   |
 25  libxml.gif                                 |
 26  linus.gif                                  |
 27  redhat.gif                                 |
 28  structure.gif                             \ /
 29  w3c.png                                    -
 30  
 31  apibuild.py        Python script which generates the file libxml2-api.xml
 32  parsedecl.py       Python script which generates the file libxml2-refs.xml
 33  
 34  api.xsl            xslt script to generate API cross-references APIchunk*.html
 35                       using information from libxml2-api.xml and libxml2-refs.xml
 36  news.xsl           xslt script to generate ../NEWS from news.html
 37  site.xsl           xslt script imported by api.xsl, generates most top-level
 38                       pages from news.html
 39  xsa.xsl            xslt script to generate libxml.xsa from news.html
 40  
 41  xmlcatalog.1       Man page for xml catalogs, built from xmlcatalog_man.xml DocBook
 42  		   source with "make xmlcatalog.1" or "make all"
 43  xmllint.1          Man page for xmllint program, built from xmllint.xml DocBook
 44  		   source with "make xmllint.1" or "make all"
 45  
 46  libxml-doc.el      Control script for displaying docs under emacs
 47  
 48  
 49    Given the above files, the generation of the complete documentation (as
 50  provided on the web by xmlsoft.org) can be created with the following steps:
 51  
 52  NOTE:  Steps 1 through 7 are performed with the command "make rebuild";
 53         Steps 3 and 5 through 7 are performed with the command "make all"
 54  
 55  
 56  1) Generate libxml2-api.xml:
 57         ./apibuild.py
 58  
 59      This script is a more recent addition to the documentation generation.
 60      Instead of using the information from the gtk-doc routines, it actually
 61      re-processes all the the library source files, extracting information
 62      about the api (exported procedures and symbols, together with information
 63      from the source comments within these).  It produces an xml file which
 64      contains all of this information, "libxml2-api.xml".
 65  
 66  2) Generate libxml2-refs.xml:
 67         ./parsedecl.py
 68  
 69      This script produces the summary
 70      xml file "libxml2-refs.xml".  Historically, it also used to produce
 71      information on the api's in the file "libxml2-api.xml", but that step is
 72      now being done by a separate script.
 73  
 74  3) Generate the site's main pages:
 75         xsltproc --nonet --html --output index.html site.xsl xml.html
 76  
 77      All of the "top-level" pages (except xmlreader.html and guidelines.html)
 78      which have navigation framing, are generated from this step
 79  
 80  4) Generate the contents and cross-referencing pages:
 81         xsltproc --nonet --html api.xsl xml.html
 82  
 83  5) Generate the NEWS file in the top directory:
 84         xsltproc --nonet --output ../NEWS news.xsl news.html
 85  
 86  6) Generate the XML Software Autoupdate file libxml2.xsa:
 87         make libxml2.xsa, or,
 88         xsltproc --nonet --output libxml2.xsa xsa.xsl news.html
 89  
 90  7) Manually generate xmlcatalog.1 and xmllint.1 using manpages/docbook.xsl
 91     stylesheet in docbook stylesheets. "make all" also takes care of this.
 92  
 93    After these steps have been done, the documentation is complete.
 94  The search engine is then set up using the script index.py, using
 95  libxml2-api.xml, the HTML web pages generated above, and the HTML
 96  mailing list archives at gnome.org.
 97  
 98  
 99  Last update:  30 November 2003
100