Browse code

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).

Jan Janak authored on 24/04/2009 00:13:45
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,48 +0,0 @@
1
-<!-- $Id$ -->
2
-
3
-<!-- Entities often used in the documentation -->
4
-
5
-<!ENTITY fhg "FhG FOKUS">
6
-<!ENTITY iptel "<ulink url='http://iptel.org'>iptel.org</ulink>">
7
-<!ENTITY ser "SER">
8
-<!ENTITY sername "SIP Express Router">
9
-
10
-<!ENTITY serhome "http://iptel.org/ser">
11
-<!ENTITY serbugs "http://iptel.org/ser/bugs">
12
-<!ENTITY serusers "http://mail.iptel.org/mailman/listinfo/serusers">
13
-<!ENTITY serdev "http://mail.iptel.org/mailman/listinfo/serdev">
14
-
15
-<!ENTITY serhomelink "<ulink url='&serhome;'>&serhome</ulink>">
16
-<!ENTITY serbugslink "<ulink url='&serbugs;'>&serbugs</ulink>">
17
-<!ENTITY seruserslink "<ulink url='&serusers;'>&serusers</ulink>">
18
-<!ENTITY serdevlink "<ulink url='&serdev;'>&serdev</ulink>">
19
-
20
-<!ENTITY serusersmail "<email>serusers@iptel.org</email>">
21
-<!ENTITY serdevmail "<email>serdev@iptel.org</email>">
22
-
23
-<!-- Often used acronyms -->
24
-
25
-<!ENTITY sip "<acronym>SIP</acronym>">
26
-<!ENTITY sdp "<acronym>SDP</acronym>">
27
-<!ENTITY rtp "<acronym>RTP</acronym>">
28
-<!ENTITY pstn "<acronym>PSTN</acronym>">
29
-<!ENTITY http "<acronym>HTTP</acronym>">
30
-<!ENTITY uri "<acronym>URI</acronym>">
31
-<!ENTITY url "<acronym>URL</acronym>">
32
-<!ENTITY uac "<acronym>UAC</acronym>">
33
-<!ENTITY uas "<acronym>UAS</acronym>">
34
-<!ENTITY ua "<acronym>UA</acronym>">
35
-<!ENTITY nat "<acronym>NAT</acronym>">
36
-<!ENTITY ip "<acronym>IP</acronym>">
37
-<!ENTITY udp "<acronym>UDP</acronym>">
38
-<!ENTITY ietf "<ulink url='http://www.ietf.org'>IETF</ulink>">
39
-<!ENTITY im "<acronym>IM</acronym>">
40
-<!ENTITY smtp "<acronym>SMTP</acronym>">
41
-<!ENTITY gnu "<ulink url='http://www.gnu.org'>GNU</ulink>">
42
-<!ENTITY gpl "<ulink url='http://www.gnu.org/licenses/licenses.html#GPL'>GPL</ulink>">
43
-
44
-<!-- Often used RFCs -->
45
-
46
-<!ENTITY rfc3261 "<ulink url='http://www.ietf.org/rfc/rfc3261.txt'>RFC3261</ulink>">
47
-<!ENTITY rfc822 "<ulink url='http://www.ietf.org/rfc/rfc822.txt'>RFC822</ulink>">
48
-<!ENTITY rfc2543 "<ulink url='http://www.ietf.org/rfc/rfc2543.txt'>RFC2543</ulink>">
Browse code

- removed reference to serhelp@iptel.org, we will be using serusers@iptel.org instead

Jan Janak authored on 29/11/2006 12:23:59
Showing 1 changed files
... ...
@@ -9,17 +9,14 @@
9 9
 
10 10
 <!ENTITY serhome "http://iptel.org/ser">
11 11
 <!ENTITY serbugs "http://iptel.org/ser/bugs">
12
-<!ENTITY serhelp "http://mail.iptel.org/mailman/listinfo/serhelp">
13 12
 <!ENTITY serusers "http://mail.iptel.org/mailman/listinfo/serusers">
14 13
 <!ENTITY serdev "http://mail.iptel.org/mailman/listinfo/serdev">
15 14
 
16 15
 <!ENTITY serhomelink "<ulink url='&serhome;'>&serhome</ulink>">
17 16
 <!ENTITY serbugslink "<ulink url='&serbugs;'>&serbugs</ulink>">
18
-<!ENTITY serhelplink "<ulink url='&serhelp;'>&serhelp</ulink>">
19 17
 <!ENTITY seruserslink "<ulink url='&serusers;'>&serusers</ulink>">
20 18
 <!ENTITY serdevlink "<ulink url='&serdev;'>&serdev</ulink>">
21 19
 
22
-<!ENTITY serhelpmail "<email>serhelp@iptel.org</email>">
23 20
 <!ENTITY serusersmail "<email>serusers@iptel.org</email>">
24 21
 <!ENTITY serdevmail "<email>serdev@iptel.org</email>">
25 22
 
Browse code

- Customized stylesheet for XHTML generation - Very basic CSS style for documentation - Stylesheet for generating Docbook dependencies in Makefiles

Jan Janak authored on 23/07/2005 23:01:14
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,51 @@
1
+<!-- $Id$ -->
2
+
3
+<!-- Entities often used in the documentation -->
4
+
5
+<!ENTITY fhg "FhG FOKUS">
6
+<!ENTITY iptel "<ulink url='http://iptel.org'>iptel.org</ulink>">
7
+<!ENTITY ser "SER">
8
+<!ENTITY sername "SIP Express Router">
9
+
10
+<!ENTITY serhome "http://iptel.org/ser">
11
+<!ENTITY serbugs "http://iptel.org/ser/bugs">
12
+<!ENTITY serhelp "http://mail.iptel.org/mailman/listinfo/serhelp">
13
+<!ENTITY serusers "http://mail.iptel.org/mailman/listinfo/serusers">
14
+<!ENTITY serdev "http://mail.iptel.org/mailman/listinfo/serdev">
15
+
16
+<!ENTITY serhomelink "<ulink url='&serhome;'>&serhome</ulink>">
17
+<!ENTITY serbugslink "<ulink url='&serbugs;'>&serbugs</ulink>">
18
+<!ENTITY serhelplink "<ulink url='&serhelp;'>&serhelp</ulink>">
19
+<!ENTITY seruserslink "<ulink url='&serusers;'>&serusers</ulink>">
20
+<!ENTITY serdevlink "<ulink url='&serdev;'>&serdev</ulink>">
21
+
22
+<!ENTITY serhelpmail "<email>serhelp@iptel.org</email>">
23
+<!ENTITY serusersmail "<email>serusers@iptel.org</email>">
24
+<!ENTITY serdevmail "<email>serdev@iptel.org</email>">
25
+
26
+<!-- Often used acronyms -->
27
+
28
+<!ENTITY sip "<acronym>SIP</acronym>">
29
+<!ENTITY sdp "<acronym>SDP</acronym>">
30
+<!ENTITY rtp "<acronym>RTP</acronym>">
31
+<!ENTITY pstn "<acronym>PSTN</acronym>">
32
+<!ENTITY http "<acronym>HTTP</acronym>">
33
+<!ENTITY uri "<acronym>URI</acronym>">
34
+<!ENTITY url "<acronym>URL</acronym>">
35
+<!ENTITY uac "<acronym>UAC</acronym>">
36
+<!ENTITY uas "<acronym>UAS</acronym>">
37
+<!ENTITY ua "<acronym>UA</acronym>">
38
+<!ENTITY nat "<acronym>NAT</acronym>">
39
+<!ENTITY ip "<acronym>IP</acronym>">
40
+<!ENTITY udp "<acronym>UDP</acronym>">
41
+<!ENTITY ietf "<ulink url='http://www.ietf.org'>IETF</ulink>">
42
+<!ENTITY im "<acronym>IM</acronym>">
43
+<!ENTITY smtp "<acronym>SMTP</acronym>">
44
+<!ENTITY gnu "<ulink url='http://www.gnu.org'>GNU</ulink>">
45
+<!ENTITY gpl "<ulink url='http://www.gnu.org/licenses/licenses.html#GPL'>GPL</ulink>">
46
+
47
+<!-- Often used RFCs -->
48
+
49
+<!ENTITY rfc3261 "<ulink url='http://www.ietf.org/rfc/rfc3261.txt'>RFC3261</ulink>">
50
+<!ENTITY rfc822 "<ulink url='http://www.ietf.org/rfc/rfc822.txt'>RFC822</ulink>">
51
+<!ENTITY rfc2543 "<ulink url='http://www.ietf.org/rfc/rfc2543.txt'>RFC2543</ulink>">