Browse code

docbook: folder moved from root to doc

Daniel-Constantin Mierla authored on 07/12/2016 13:55:42
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,37 +0,0 @@
1
-<?xml version="1.0"?>
2
-<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
3
-         "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
4
-<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
5
-	<!-- Uncomment the following entry if you have docbook DTDs in unusual
6
-	     location or if you would like to validate the documentation against
7
-	     newer docbook version -->
8
-	<!--
9
-	<public publicId="-//OASIS//DTD DocBook XML V4.3//EN"
10
-            uri="file:///home/janakj/docbook/dtd/docbookx.dtd"/>
11
-      -->
12
-
13
-    <!-- Uncomment the following entry if you have docbook XSL stylesheets in
14
-         unusual location, the value of rewritePrefix parameter should point
15
-         to the top level directory of your XSL stylesheets -->
16
-    <!--
17
-    <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
18
-                rewritePrefix="file:///home/janakj/docbook/xsl/"/>
19
-      -->
20
-
21
-    <!-- Try the system wide catalogs as the last step before reverting to
22
-         using the value of system identifiers and URI references from the
23
-         documents being processed (they usualy contain HTTP URIs). -->
24
-    <delegatePublic publicIdStartString="" catalog="file:///etc/xml/catalog"/>
25
-    <delegateURI    uriStartString=""      catalog="file:///etc/xml/catalog"/>
26
-
27
-    <!-- If xsltproc gets here while searching the catalog then no entry was
28
-         found in the catalog files for the requested resource and in this
29
-         case xsltproc will attempt to download the resource from the internet
30
-         using the HTTP protocol. It will use the HTTP URIs from system
31
-         identifiers and URI references (therefore the XSL customization
32
-         stylesheets in SR refer to the original XSL stylesheets using HTTP
33
-         URIs). Note: Downloading DTDs and XSL stylesheets can be very slow,
34
-         because each file will be downloaded several times, xsltproc does not
35
-         cache downloaded files.
36
-      -->
37
-</catalog>
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
new file mode 100644
... ...
@@ -0,0 +1,37 @@
1
+<?xml version="1.0"?>
2
+<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
3
+         "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
4
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
5
+	<!-- Uncomment the following entry if you have docbook DTDs in unusual
6
+	     location or if you would like to validate the documentation against
7
+	     newer docbook version -->
8
+	<!--
9
+	<public publicId="-//OASIS//DTD DocBook XML V4.3//EN"
10
+            uri="file:///home/janakj/docbook/dtd/docbookx.dtd"/>
11
+      -->
12
+
13
+    <!-- Uncomment the following entry if you have docbook XSL stylesheets in
14
+         unusual location, the value of rewritePrefix parameter should point
15
+         to the top level directory of your XSL stylesheets -->
16
+    <!--
17
+    <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
18
+                rewritePrefix="file:///home/janakj/docbook/xsl/"/>
19
+      -->
20
+
21
+    <!-- Try the system wide catalogs as the last step before reverting to
22
+         using the value of system identifiers and URI references from the
23
+         documents being processed (they usualy contain HTTP URIs). -->
24
+    <delegatePublic publicIdStartString="" catalog="file:///etc/xml/catalog"/>
25
+    <delegateURI    uriStartString=""      catalog="file:///etc/xml/catalog"/>
26
+
27
+    <!-- If xsltproc gets here while searching the catalog then no entry was
28
+         found in the catalog files for the requested resource and in this
29
+         case xsltproc will attempt to download the resource from the internet
30
+         using the HTTP protocol. It will use the HTTP URIs from system
31
+         identifiers and URI references (therefore the XSL customization
32
+         stylesheets in SR refer to the original XSL stylesheets using HTTP
33
+         URIs). Note: Downloading DTDs and XSL stylesheets can be very slow,
34
+         because each file will be downloaded several times, xsltproc does not
35
+         cache downloaded files.
36
+      -->
37
+</catalog>