Module: sip-router Branch: master Commit: 5bc53be47a8c33a5b135154e3a6da8834df1914f URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5bc53be4...

Author: Jan Janak jan@iptel.org Committer: Jan Janak jan@iptel.org Date: Fri Apr 24 02:13:45 2009 +0200

New Docbook processing system.

This is the new and improved version of the docbook build system that was present in ser and kamailio. It consists of Makefiles, xslt stylesheets, css stylesheets, and other auxiliary files that are needed to convert documentation stored in docbook xml format to various output formats. We currently support the following outputs: HTML, plain-text, and module README. Other formats (man pages, chunked HTML and possibly PDF) will be added later.

First of all, we are moving all files that are part of the docbook processing system into one directory "docbook". Those files were previously scaterred across multiple directories in the repository and having them all at one place make the system less error-prone.

We have merged files containing SGML entity definitions from both projects into a single file. The file is stored in docbook/entities.xml and this is the file that should be included by all docbook documents (we will need to update all such files in all modules).

The Kamailio CSS style sheet for module documentation is now becoming the main CSS stylesheet for HTML documentation generated from docbook sources. The new stylesheet is stored in docbook/sr-doc.css. The contents of the file was slighlty updated to make sure that the styles in the file match HTML elements in XHTML output. With the new system the default output HTML flavor is XHTML.

The toplevel Makefile.doc is gone. It is being replaced by file docbook/Makefile. The new makefile has been extensively polished and improved. This also requires new Makefiles in modules. All the targets and references that were used to generate the PDF output in SER are gone, we were using proprietary FOP processor which is not generally available. All configuration options that can be overriden from module/doc Makefiles are extensively commented. The new Makefile can save the output being generated into a directory specified on the command line: $ output_dir=/html make html The default target of the Makefile is HTML. There is a new target that can be used generate module README: $ make readme

The file that should be included from module Makefiles is docbook/Makefile.modules. At present the file only includes the main Makefile, but in the future some of the targets that are particular to module documentation will be moved to this file.

The XML catalog received a small facelift, too. By default the catalog references /etc/xml/catalog. References to dbschema DTD and XSL files (dbschema is the scripting system used to generate SQL files in SER) are gone. They do not belong into this file.

All references to Drupal and drupal related xsl stylesheets are gone. Those files were used to generate HTML files suitable for inclusion into Drupal pages at iptel.org.

File doc/kam_module_faq.xml has also been removed, this file was empty, it was probably added because it was included by far too many docbook documents in modules. Since I wrote a script to do some compatibility changes in module docbook files, I taught it to remove the reference to the file from all docbook files and then deleted the file.

All files in directory "docbook" are briefly described in docbook/README.

The new system adopted Kamailio costumizations of the docbook stylesheet that is used to generate READMEs. There is a new stylesheet called readme.xsl that contains all options that should only be applied when READMEs are being generated.

The stylesheet that generates man pages from docbook has been moved from doc/stylesheets to docbook/man.xsl. We do not have yet support for man pages in the docbook Makefile, this feature will be added later.

New features: * Automatic dependency calculation. We have a XSL stylesheet which traverses the source docbook document and produces a list of files included in the document. This list is then included in the main Makefile to calculate dependencies. That means you can split your document into multiple files and the system will always correctly rebuild the file.

* Support for document inclusion with xi:include. All source docbook files are processed with the support for xi:include enabled which makes it possible to include other documents without the need to use SGML entities to include external files.

* Improved top level make file, among other things the makefile is now much more flexible, the module can specify different source document for each type of produced output. The makefile can generate module READMEs. The output directory is configurable, which is useful if you need to build a collection of html pages to be uploaded to a server.

* Separate stylesheet to customize the format of module README files.

* Supported output formats: README XHTML (single file) XHTML (multiple files) Plain-text

* Normalized screens: There is no longer the need to pay attention to the leading and trailing white space in data of <screen> (and similar) elements. Stylesheet common.xsl contains a template that does that automatically (this isn't really a new feature, is was present in the original ser docbook processing system).

---

Makefile.doc | 188 ------------------- doc/catalog.xml | 53 ------ doc/ser_entities.xml | 48 ----- doc/stylesheets/README | 53 ------ doc/stylesheets/dep.xsl | 44 ----- doc/stylesheets/drupal.xsl | 163 ----------------- doc/stylesheets/fo.xsl | 16 -- doc/stylesheets/html.chunked.xsl | 40 ---- doc/stylesheets/ser.css | 192 ------------------- docbook/Makefile | 193 ++++++++++++++++++++ docbook/Makefile.module | 4 + docbook/README | 66 +++++++ docbook/TODO | 10 + docbook/catalog.xml | 37 ++++ {doc/stylesheets => docbook}/common.xsl | 0 docbook/dep.xsl | 48 +++++ doc/kam_entities.xml => docbook/entities.xml | 16 ++- .../xhtml.chunked.xsl => docbook/html.chunked.xsl | 2 +- .../xhtml.common.xsl => docbook/html.common.xsl | 14 ++- doc/stylesheets/xhtml.xsl => docbook/html.xsl | 3 +- doc/stylesheets/serdoc2man.xsl => docbook/man.xsl | 0 docbook/readme.xsl | 14 ++ doc/kam-module-docbook.css => docbook/sr-doc.css | 77 ++++---- {doc/stylesheets => docbook}/txt.xsl | 2 +- 24 files changed, 441 insertions(+), 842 deletions(-)

Diff: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commitdiff;h=5bc5...