[SR-Dev] git:master: New Docbook processing system.
Jan Janak
jan at iptel.org
Fri Apr 24 03:35:09 CEST 2009
Module: sip-router
Branch: master
Commit: 5bc53be47a8c33a5b135154e3a6da8834df1914f
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5bc53be47a8c33a5b135154e3a6da8834df1914f
Author: Jan Janak <jan at iptel.org>
Committer: Jan Janak <jan at 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=5bc53be47a8c33a5b135154e3a6da8834df1914f
More information about the sr-dev
mailing list