Merge commit '6c75f0dc676d73c4cbcdca5a9cf05c6797a2ac0b' as 'libxml2'

1 files changed, 100 insertions, 0 deletions

diff --git a/libxml2/doc/docdescr.doc b/libxml2/doc/docdescr.doc
new file mode 100644
index 0000000..3fec94a
--- /dev/null
+++ b/libxml2/doc/docdescr.doc
@@ -0,0 +1,100 @@
+                   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 script 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 7 are performed with the command "make rebuild";
+       Steps 3 and 5 through 7 are performed with the command "make all"
+
+
+1) 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".
+
+2) Generate libxml2-refs.xml:
+       ./parsedecl.py
+
+    This script 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.
+
+3) 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
+
+4) Generate the contents and cross-referencing pages:
+       xsltproc --nonet --html api.xsl xml.html
+
+5) Generate the NEWS file in the top directory:
+       xsltproc --nonet --output ../NEWS news.xsl news.html
+
+6) Generate the XML Software Autoupdate file libxml2.xsa:
+       make libxml2.xsa, or,
+       xsltproc --nonet --output libxml2.xsa xsa.xsl news.html
+
+7) Manually generate xmlcatalog.1 and xmllint.1 using manpages/docbook.xsl
+   stylesheet in docbook stylesheets. "make all" also takes care of this.
+
+  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:  30 November 2003
+