Re: [PATCH sgml-doctools] DocBook/XML: add support for docbook external references
On Wed, Mar 23, 2011 at 6:59 PM, Gaetan Nadon mems...@videotron.ca wrote:
Documents external references
This looks like a nice feature, and I applaud you for powering through
that external link setup. A couple comments below.
-
A new feature with version 1.7 is references to documents in other
packages. For example a protocol specifications may refer to another
one or to a library implementing it.
This feature works with PDF, HTML, PS (and epub?) generated documents
and will generate links to the other versions of the same type, i.e. html
docs will link to other html docs, and pdf docs will link to other pdf
docs.
Due to the modular nature of the X window System and the flexibility
it provides to O/S builders, one should not expect all links to
be resolved all the time. A more recent version of a package may be
installed or an older version may be retained for a long period of time.
Not all packages are installed either.
Build challenges
The X Window System is composed of over 200 packages. The documentation is
included with the package it documents so the information matches the code.
The build is organized to satisfy C code building requirements, but this
paradigm does not fit very well for building documentation.
For a document to build a reference to another document, it needs to have
information about this document which may or may not be there, or may be
at an unexpected version. The document it refers to may also wish to refer
to the former document.
Local X builds
--
When building X as a sandbox on a workstation, using a simple build script
to configure and build all packages in the right order is all you need
to get a working system, including documentation. You will not get all
the links in the documentation resolved correctly due to build order
and/or bi-directional references.
Unless you are updating or testing the documentation, you do not need to
worry about this glitch. A simple workaround is to build each affected
package using make clean install make clean install in any order.
This will give a chance to each package to get information about the other one
through the installed files.
O/S X builds
O/S builders often repackage X code and documentation, however they face the
same challenges as described above. Users can update packages through
the package management system or install additional packages. To use the
earlier example, if a protocol is installed without its implementing
library there will be a broken reference.
Build assumptions
-
Packages provide great flexibility, including the one to install each package
documentation in a separate, totally unrelated directory using the --docdir
configure option. For external references to work, it is assumed that
the each package installs the documentation using the relative
doc/${PACKAGE_TARNAME} location.
The Docbook stylesheet technology will create references with paths relative
to this location. It will navigate up to doc using ../ and then navigate
down to the document it refers to.
Diagnosing a broken reference
-
A document reference is created at build time while the document is being
transformed from Docbook/XML to HTML or another format. If this reference
is missing, the document must be rebuilt.
To build the reference, the docbook stylesheet consults a database stored
in this package which is called masterdb.xml. This database supplies the
relative directory structure of where the documents are located as well
as including target document references in the various *.db files.
These files are generated and installed while the documents are being build.
This is what a Docbook/XML reference from docA to docB looks like (docA.xml):
olink targetdoc='docB' targetptr='docBfragment'Title/olink
This is what an HTML reference from docA to docB looks like (docA.html):
a href=docB.html#docBfragment class=olinkTitle/a
This is what an HTML targetdoc for docB looks like (docB.html.db):
div element=article href=#docBfragment number=
targetptr=docBfragment
This is what an HTML reference from docA to docB looks like (docA.html)
when the reference cannot be resolved:
span class=olinkTitle/span
This can be caused by one or more of the following:
- docB may not longer contain the text (targetptr) docA is referring to.
- docB.html.db file may not have been installed by docB package
- masterdb.html.xml is missing a document/ entry for docB
- masterdb.html.xml cannot be loaded so all refs are broken.
- an XSLT processor which does not support xinclude is being used
- docB.html.db was generated without --xinclude option for the processor
- xsltproc is not at version 1.1.26 or later
- for PDF/PS formats, the fragment is ignored, always points to top of docB
Some pitfalls
-
book id=docA in docA.xml:
[PATCH sgml-doctools] DocBook/XML: add support for docbook external references
Documents external references
-
A new feature with version 1.7 is references to documents in other
packages. For example a protocol specifications may refer to another
one or to a library implementing it.
This feature works with PDF, HTML, PS (and epub?) generated documents
and will generate links to the other versions of the same type, i.e. html
docs will link to other html docs, and pdf docs will link to other pdf
docs.
Due to the modular nature of the X window System and the flexibility
it provides to O/S builders, one should not expect all links to
be resolved all the time. A more recent version of a package may be
installed or an older version may be retained for a long period of time.
Not all packages are installed either.
Build challenges
The X Window System is composed of over 200 packages. The documentation is
included with the package it documents so the information matches the code.
The build is organized to satisfy C code building requirements, but this
paradigm does not fit very well for building documentation.
For a document to build a reference to another document, it needs to have
information about this document which may or may not be there, or may be
at an unexpected version. The document it refers to may also wish to refer
to the former document.
Local X builds
--
When building X as a sandbox on a workstation, using a simple build script
to configure and build all packages in the right order is all you need
to get a working system, including documentation. You will not get all
the links in the documentation resolved correctly due to build order
and/or bi-directional references.
Unless you are updating or testing the documentation, you do not need to
worry about this glitch. A simple workaround is to build each affected
package using make clean install make clean install in any order.
This will give a chance to each package to get information about the other one
through the installed files.
O/S X builds
O/S builders often repackage X code and documentation, however they face the
same challenges as described above. Users can update packages through
the package management system or install additional packages. To use the
earlier example, if a protocol is installed without its implementing
library there will be a broken reference.
Build assumptions
-
Packages provide great flexibility, including the one to install each package
documentation in a separate, totally unrelated directory using the --docdir
configure option. For external references to work, it is assumed that
the each package installs the documentation using the relative
doc/${PACKAGE_TARNAME} location.
The Docbook stylesheet technology will create references with paths relative
to this location. It will navigate up to doc using ../ and then navigate
down to the document it refers to.
Diagnosing a broken reference
-
A document reference is created at build time while the document is being
transformed from Docbook/XML to HTML or another format. If this reference
is missing, the document must be rebuilt.
To build the reference, the docbook stylesheet consults a database stored
in this package which is called masterdb.xml. This database supplies the
relative directory structure of where the documents are located as well
as including target document references in the various *.db files.
These files are generated and installed while the documents are being build.
This is what a Docbook/XML reference from docA to docB looks like (docA.xml):
olink targetdoc='docB' targetptr='docBfragment'Title/olink
This is what an HTML reference from docA to docB looks like (docA.html):
a href=docB.html#docBfragment class=olinkTitle/a
This is what an HTML targetdoc for docB looks like (docB.html.db):
div element=article href=#docBfragment number= targetptr=docBfragment
This is what an HTML reference from docA to docB looks like (docA.html)
when the reference cannot be resolved:
span class=olinkTitle/span
This can be caused by one or more of the following:
- docB may not longer contain the text (targetptr) docA is referring to.
- docB.html.db file may not have been installed by docB package
- masterdb.html.xml is missing a document/ entry for docB
- masterdb.html.xml cannot be loaded so all refs are broken.
- an XSLT processor which does not support xinclude is being used
- docB.html.db was generated without --xinclude option for the processor
- xsltproc is not at version 1.1.26 or later
- for PDF/PS formats, the fragment is ignored, always points to top of docB
Some pitfalls
-
book id=docA in docA.xml: the id must match the file basename.
In xorg-*.xsl, xsl:param name=current.docid select=/*/@id/
supplies docid for *.db. The document id must be unique across
all documents.
The baseuri attribute in masterdb.xml is required for pdf/ps references
to work. It cannot be
