The DocBook formatter used to generate something like:
<para id="section"><sect2><title>Title</title></sect2>Some Text</para>
Which was completely wrong. In DocBook, a section should look like this:
<sect2 id="section"><title>Title</title><para>Some Text</para></sect2>
Attributes in XML may contain alphanumeric characters, underscores,
colons and dots. When DocBook is chunked, the dot is often used as a
path separator. To generate a valid ID, we take the title of the
section, transform all non-alphanumeric characters to underscores and
then add a prefix separated with dots. We also add the document name as
a prefix, in order to 'xinclude' eg. cmake.docbook and ctest.docbook in
the same document. IDs are written in multiple places, so the code is
factored to a function.
When DocBook is transformed (eg. to PDF, HTML, ...), a TOC is generated
from the document's layout. The TOC-like list that the docbook
formatter used to generate was both redundant and invalid.
This converts the CMake license to a pure 3-clause OSI-approved BSD
License. We drop the previous license clause requiring modified
versions to be plainly marked. We also update the CMake copyright to
cover the full development time range.
Applying patch provided in issue #7797.
Fixes to man-pages:
- Character '-' must be espaced as '\-'
- Surround preformatted text with '.nf' and '.fi' to adjust filling
- Give every page a NAME section for indexing by mandb
- Pass the man page filename without extension to .TH in its header
Also added a title to the HTML header.
- Previously all links started in 'command_' which led to conflicts
and was confusing for non-command items.
- Use a per-section name that is meaningful to humans.
- Fix link id names to be valid HTML.
(http://www.oasis-open.org/docbook/xml/4.2/), which users can then convert
to other formats.
Tested with meinproc from KDE, which generates HTML pages which look good.
Alex
Daniel Pfeifer
Kitware Robot
Brad King
Alexander Neundorf