mirror of
https://gitlab.gnome.org/GNOME/libxml2.git
synced 2024-10-27 21:55:05 +03:00
60f394e96d
* doc/html/*.html: Finally - found the problem with the page generation (XMLPUBFUN not recognized by gtkdoc). Re-created the pages using a temporary version of include/libxml/*.h. * testOOMlib.c,include/libxml/encoding.h, include/libxml/schemasInternals.h,include/libxml/valid.h, include/libxml/xlink.h,include/libxml/xmlwin32version.h, include/libxml/xmlwin32version.h.in, include/libxml/xpathInternals.h: minor edit of comments to help automatic documentation generation * doc/docdescr.doc: small elaboration * doc/examples/test1.c,doc/examples/Makefile.am: re-commit (messed up on last try) * xmlreader.c: minor change to clear warning.
135 lines
5.9 KiB
Plaintext
135 lines
5.9 KiB
Plaintext
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, 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 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:
|
|
make scan, or,
|
|
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":
|
|
make templates, or,
|
|
gtkdoc-mktmpl --module=libxml
|
|
|
|
3) Generate the xml documentation in the subdirectory "xml":
|
|
make xml, or,
|
|
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":
|
|
make html, or,
|
|
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 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
|
|
|
|
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:
|
|
make libxml2.xsa, or,
|
|
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
|
|
|