1 Notes on the libxml2 Documentation 2 Prepared by: William Brack <wbrack (a] 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 101
