docdescr.doc revision dd088c154c34096ba157fdba6c4891da6f33a2fc 
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
5scripts  and some xsl  scripts and xml files, I  thought it might be good
6to save others some time  by setting down the basic information about how
7the library documentation  is created.  I intend to enhance this process,
8but will keep this document up-to-date for  everyone's information.  Note
9that this document does not  apply to the subdirectory  "tutorial", which
10is separately maintained by John Fleck.
11
12  There are a relatively  small number of files  which form the "core" of
13the document directory.  All  the other files in the directory can be re-
14generated using  the information  present in these  core files,  plus the
15actual library  source files (*.[ch]) in the parent  directory  "../" and
16it's descendants include  and include/libxml.  These core files, together
17with a brief description of each, are as follows:-
18
19xml.html           The "main page", manually produced by Daniel Veillard
20news.html          The latest news, extracted from xml.html by site.xsl
21
22benchmark.gif      Illustrations used for the "main page" and subsidiaries
23gnome2.png                              -------
24Libxml2-Logo-180x168.gif                   |
25libxml.gif                                 |
26linus.gif                                  |
27redhat.gif                                 |
28structure.gif                             \ /
29w3c.png                                    -
30
31apibuild.py        Python script which generates the file libxml2-api.xml
32parsedecl.py       Python secipt which generates the file libxml2-refs.xml
33
34api.xsl            xslt script to generate API cross-references APIchunk*.html
35                     using information from libxml2-api.xml and libxml2-refs.xml
36news.xsl           xslt script to generate ../NEWS from news.html
37site.xsl           xslt script imported by api.xsl, generates most top-level
38                     pages from news.html
39xsa.xsl            xslt script to generate libxml.xsa from news.html
40
41xmlcatalog.1       Man page for xml catalogs, built from xmlcatalog_man.xml DocBook
42		   source with "make xmlcatalog.1" or "make all"
43xmllint.1          Man page for xmllint program, built from xmllint.xml DocBook
44		   source with "make xmllint.1" or "make all"
45
46libxml-doc.el      Control script for displaying docs under emacs
47
48
49  Given the above files, the generation of the complete documentation (as
50provided on the web by xmlsoft.org) can be created with the following steps:
51
52NOTE:  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
561) 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
662) 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
743) 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
804) Generate the contents and cross-referencing pages:
81       xsltproc --nonet --html api.xsl xml.html
82
835) Generate the NEWS file in the top directory:
84       xsltproc --nonet --output ../NEWS news.xsl news.html
85
866) Generate the XML Software Autoupdate file libxml2.xsa:
87       make libxml2.xsa, or,
88       xsltproc --nonet --output libxml2.xsa xsa.xsl news.html
89
907) 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.
94The search engine is then set up using the script index.py, using
95libxml2-api.xml, the HTML web pages generated above, and the HTML
96mailing list archives at gnome.org.
97
98
99Last update:  30 November 2003
100
101