rebuilt the generated pages (again), manually restored doc/html/index.html
* doc/Makefile.am doc/*.html doc/html/*.html: rebuilt the
generated pages (again), manually restored doc/html/index.html
and manually edited generated file doc/gnome-xml.xml to put
in appropriate headings.
* doc/docdescr.doc: new file to describe details of the
document generation (helps my memory for the next time)
* genChRanges.py,chvalid.c,include/libxml/chvalid.h: minor
enhancement to please the automatic documentation generation.
diff --git a/doc/docdescr.doc b/doc/docdescr.doc
new file mode 100644
index 0000000..c80e4f8
--- /dev/null
+++ b/doc/docdescr.doc
@@ -0,0 +1,127 @@
+ 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 secipt 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
+xmllint.1 Man page for xmllint program
+
+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 5 are performed with the command "make rebuild";
+ Step 6 must be accomplished manually.
+ Steps 7 and 8 are performed with the command "make web"
+
+1) Generate libxml-decl.txt, libxml-decl-list.txt and libxml-sections.txt:
+ gtkdoc-scan --module=libxml --source-dir=../ \
+ --ignore-headers="acconfig.h config.h win32config.h trio.h triostr.h
+ triop.h config-m ac.h XMLTestPrefix2.h XMLTestPrefix.h
+ triodef.h trionan.h xlink.h libxml.h libx ml2-py.h
+ libxml_wrap.h"
+
+ These three files are used by the gdk-doc routines in the following steps.
+
+2) Generate the sgml documentation in the subdirectory "tmpl":
+ gtkdoc-mktmpl --module=libxml
+
+3) Generate the xml documentation in the subdirectory "xml":
+ gtkdoc-mkdb --module=libxml --source-dir=../ --output-format=xml \
+ --main-sgml-file=gnome-xml.xml
+
+ This also generates the file gnome-xml.xml.
+ Note that, in order to produce "readable" documentation, the file
+ gnome-xml.xml should be manually edited in order to put in appropriate
+ titles.
+
+4) Generate the main html documentation in the subdirectory "html":
+ cd html
+ gtkdoc-mkhtml libxml ../gnome-xml.xml
+ cd ../
+
+ Note that the file index.html is really not suitable, so a manual
+ substitution of a generic index is done.
+
+5) 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".
+
+6) Generate libxml2-refs.xml:
+ ./parsedecl.py
+
+ This script uses the *.txt files generated by Step 1, together with the
+ files in the subdirectory xml produced in Step 3, and 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.
+
+7) Generate the site's main page:
+ 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
+
+8) Generate the contents and cross-referencing pages:
+ xsltproc --nonet --html api.xsl xml.html
+
+9) Generate the NEWS file in the top directory:
+ xsltproc --nonet --output ../NEWS news.xsl news.html
+
+10)Generate the XML Software Autoupdate file libxml2.xsa:
+ xsltproc --nonet --output libxml2.xsa xsa.xsl news.html
+
+11)Manually generate xmlcatalog.1 and xmllint.1 using manpages/docbook.xsl
+ stylesheet in docbook stylesheets
+
+ 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: 15 November 2003
+