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 script 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
