Vyššie na [Platon] / scripts / shell / docbook

Introduced release 0.7.0 (12-SEP-2015)

Updated:
- Platon Group name (Platon SDG is no longer used)
- copyright year (2015)
- library homepage URLs
- certain e-mail addresses

DocBook SGML/XML support scripts
--------------------------------

Problem
-------

Imagine following situation. There is some official DocBook documentation
for an application or library. So you are able to generate HTML
documentation. You are also able to generate various output formats such
as PDF, RTF, PS or TXT as well.  But you are not able to generate manpage,
since your DocBook document structure does not contain manpage generation
specific tags and attributes.

You want to use the same SGML/XML DocBook source for classical
documentation generation also manpages creation. You want also to divide
whole library or application documentation into several parts and every
part will have its own manpage. You can than create one index manpage,
which will refer to other ones.  Just like 'perl' or 'libcfg+' have this
done.

Solution
--------

For the described purpose, these few DocBook support scripts are provided.
First one, 'db-html2man' will parse document and search for comments
started with "<!-- MAN:". It will uncomment them, thus you can put manpage
specific generation tags there. Here is a little example:

<!-- MAN: <refsect1><title>SYNOPSIS</title> -->

Your DocBook documentation will surelly contain also lot of <xref ...>
references. They are used for cross-linking final documentation and to get
more intuitive and flexible navigation. References are refering to
particular ID tags of element in DocBook SGML/XML documentation sources
(for example refering to chapter, or refering to example). These IDs are
extracted by second 'db-get-id' script. They are used by first mentioned
script to compile manpage texts on place where <xref> references are used.
Of course, these references will not be clickable in manpage, but anyway
they will have appropriate name/text.

Other info
----------

Both scripts are programmed in 'awk' and licensed under GNU General Public
License. They are successfully used in 'libcfg+' project, see project
homepage at http://opensource.platon.sk/projects/libcfg+/
They are not meant to be released into public, but if you will find them
useful, we will be happy for that. Let us know about it, thanks!

Developed by Lubomir Host <rajo@platon.sk>
Copyright (c) 2002-2015 Platon Group, http://platon.sk/

Comments, suggestions, bug reports and patches are always welcome.
Please e-mail them to <support@platon.org> e-mail address.

This document was written by Ondrej Jombik at 4th Decemeber 2002.