doc/docdescr.doc

                   Notes on the libxml2 Documentation
            Prepared by: William Brack <wbrack@mmm.com.hk>
	    
  After spending a  lot of time tracing through  Makefile.am, some Python
scripts  and some xsl  scripts and xml files, I  thought it might be good
to save others some time  by setting down the basic information about how
the library documentation  is created.  I intend to enhance this process,
but will keep this document up-to-date for  everyone's information.  Note
that this document does not  apply to the subdirectory  "tutorial", which
is separately maintained by John Fleck.

  There are a relatively  small number of files  which form the "core" of
the document directory.  All  the other files in the directory can be re-
generated using  the information  present in these  core files,  plus the
actual library  source files (*.[ch]) in the parent  directory  "../" and
it's descendants include  and include/libxml.  These core files, together
with a brief description of each, are as follows:-

xml.html           The "main page", manually produced by Daniel Veillard
news.html          The latest news, extracted from xml.html by site.xsl

benchmark.gif      Illustrations used for the "main page" and subsidiaries
gnome2.png                              -------
Libxml2-Logo-180x168.gif                   |
libxml.gif                                 |
linus.gif                                  |
redhat.gif                                 |
structure.gif                             \ /
w3c.png                                    -

apibuild.py        Python script which generates the file libxml2-api.xml
parsedecl.py       Python secipt which generates the file libxml2-refs.xml

api.xsl            xslt script to generate API cross-references APIchunk*.html
                     using information from libxml2-api.xml and libxml2-refs.xml
news.xsl           xslt script to generate ../NEWS from news.html
site.xsl           xslt script imported by api.xsl, generates most top-level
                     pages from news.html
xsa.xsl            xslt script to generate libxml.xsa from news.html

xmlcatalog.1       Man page for xml catalogs
xmllint.1          Man page for xmllint program

libxml-doc.el      Control script for displaying docs under emacs


  Given the above files, the generation of the complete documentation (as
provided on the web by xmlsoft.org) can be created with the following steps:

NOTE:  Steps 1 through 5 are performed with the command "make rebuild";
       Step 6 must be accomplished manually.
       Steps 7 and 8 are performed with the command "make web"

1) Generate libxml-decl.txt, libxml-decl-list.txt and libxml-sections.txt:
       gtkdoc-scan --module=libxml --source-dir=../ \
         --ignore-headers="acconfig.h config.h win32config.h trio.h triostr.h 
                           triop.h config-m ac.h XMLTestPrefix2.h  XMLTestPrefix.h
                           triodef.h trionan.h xlink.h libxml.h libx ml2-py.h
                           libxml_wrap.h"

   These three files are used by the gdk-doc routines in the following steps.

2) Generate the sgml documentation in the subdirectory "tmpl":
       gtkdoc-mktmpl --module=libxml

3) Generate the xml documentation in the subdirectory "xml":
       gtkdoc-mkdb --module=libxml --source-dir=../ --output-format=xml \
         --main-sgml-file=gnome-xml.xml

    This also generates the file gnome-xml.xml.
    Note that, in order to produce "readable" documentation, the file
    gnome-xml.xml should be manually edited in order to put in appropriate
    titles.

4) Generate the main html documentation in the subdirectory "html":
       cd html
       gtkdoc-mkhtml libxml ../gnome-xml.xml
       cd ../

    Note that the file index.html is really not suitable, so a manual
    substitution of a generic index is done.

5) Generate libxml2-api.xml:
       ./apibuild.py

    This script is a more recent addition to the documentation generation.
    Instead of using the information from the gtk-doc routines, it actually
    re-processes all the the library source files, extracting information
    about the api (exported procedures and symbols, together with information
    from the source comments within these).  It produces an xml file which
    contains all of this information, "libxml2-api.xml".

6) Generate libxml2-refs.xml:
       ./parsedecl.py

    This script uses the *.txt files generated by Step 1, together with the
    files in the subdirectory xml produced in Step 3, and produces the summary
    xml file "libxml2-refs.xml".  Historically, it also used to produce
    information on the api's in the file "libxml2-api.xml", but that step is
    now being done by a separate script.

7) Generate the site's main page:
       xsltproc --nonet --html --output index.html site.xsl xml.html

    All of the "top-level" pages (except xmlreader.html and guidelines.html)
    which have navigation framing, are generated from this step

8) Generate the contents and cross-referencing pages:
       xsltproc --nonet --html api.xsl xml.html

9) Generate the NEWS file in the top directory:
       xsltproc --nonet --output ../NEWS news.xsl news.html

10)Generate the XML Software Autoupdate file libxml2.xsa:
       xsltproc --nonet --output libxml2.xsa xsa.xsl news.html

11)Manually generate xmlcatalog.1 and xmllint.1 using manpages/docbook.xsl
   stylesheet in docbook stylesheets

  After these steps have been done, the documentation is complete.
The search engine is then set up using the script index.py, using
libxml2-api.xml, the HTML web pages generated above, and the HTML
mailing list archives at gnome.org.


Last update:  15 November 2003