Edit
kc3-lang/libxml2/doc/docdescr.doc
Jan Pokorný
- 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 script 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, built from xmlcatalog_man.xml DocBook source with "make xmlcatalog.1" or "make all" xmllint.1 Man page for xmllint program, built from xmllint.xml DocBook source with "make xmllint.1" or "make all" 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 7 are performed with the command "make rebuild"; Steps 3 and 5 through 7 are performed with the command "make all" 1) 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". 2) Generate libxml2-refs.xml: ./parsedecl.py This script 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. 3) Generate the site's main pages: 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 4) Generate the contents and cross-referencing pages: xsltproc --nonet --html api.xsl xml.html 5) Generate the NEWS file in the top directory: xsltproc --nonet --output ../NEWS news.xsl news.html 6) Generate the XML Software Autoupdate file libxml2.xsa: make libxml2.xsa, or, xsltproc --nonet --output libxml2.xsa xsa.xsl news.html 7) Manually generate xmlcatalog.1 and xmllint.1 using manpages/docbook.xsl stylesheet in docbook stylesheets. "make all" also takes care of this. 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: 30 November 2003