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