Things to keep in mind

1. Multiple ways X is built:
   1. Distros have their own way (What does this mean because most build from release tarballs.)
   2. Some people pull straight from git
   3. build.sh xjhbuild
2. No hard coded paths:
   1. Each distro installs X docs in a different place that other distros
   2. xorg.css may not be installed
   3. xorg-sgml-doctools can be required at build time but not at runtime (?)
   4. the use of --docdir or --datadir during install

Linking between documents

A new feature we're putting into the documentation system is the ability to easily link between documents, herein called crosslinking. This uses the docbook olink feature. Please read that link because it does a better job describing the process that I can here. This works in both .html and .pdf but I'll just use .html below for examples.

To create the links, the xslt processor uses two text files; the master database and the target database.

• The master db:

  1. contains references to the targetdatabases and their locations
  2. created by hand (or script)
  3. contains the BASEURI of the link that is used to generate the final link.

• The target db:

  1. contains references to all ids an anchors within the document.
  2. is specific to one document.
  3. is generated by the xslt processor, currently xsltproc.
  4. contains the anchor of the link (the '#' in the url)

xsltproc uses both files to construct the link. The masterdb contains the URL and the targetdb contains the anchor, the place within the document being linked to.

Example: bigreqproto has this line: Please refer to the X11 documentation for further help.

When xsltproc, processes that olink tag, it scans the master database, finds the target database associated with 'libX11'. It then scans the libX11 target database for th 'overview' tag. It then creates this in the bigreqsproto.html.

X11 documentation.

Since the target db is required, for this example to work, libX11 needs to be built before bigreqsproto. What if libX11 also links to bigreqsproto? Whichever is built first will fail to have working crosslinks. The build will not fail or stop if the databases are missing,

We therefore need to build all necessary target databases before building the document of interest. X consists of ~240 modules; how do we do this?

Possible approaches:

1. two-pass building
   • Two passes are required to build. The first pass generates all the target databases. The second pass actually builds the documents.
   • Pros:
   • Links are real, no possibility of stale target databases
   • Cons:
   • Two passes are required to build modules.
   • Significant Makefile work to run only certain targets
   • External scripts to drive the process
   • No longer follows the installation instructions in the INSTALL file of each package
2. two-pass building (variation)
   • Two passes are required to build all links. The first pass generates both the target databases and the docs. Links for which the database is available will be correct. A second build pass make clean install will resolve all links because all databases are now available.
   • Pros:
   • Links are real, no possibility of stale target databases
   • No extra scripts or makefile work required (compared to above)
   • Cons:
   • Two passes are required to build modules.
   • No longer follows the installation instructions in the INSTALL file of each package
3. keep copies of all the targetdbs in xorg-sgml-doctools. When a document is updated, the target databases are copied to and checked in to xorg-sgml-doctools.
   • Pros:
   • No extra build passes are needed.
   • Cons:
   • Need to maintain copies of target databases.
   • Some scripts/makefile work to automate maintenance
4. Both two-pass and check-in dbs in sgml-doctools. A utility to report broken links would be useful. Links can be broken for reasons other than the build process. The installed dbs from proto/libs packages overwrite the installed checked-in dbs from sgml-doctools. That would correct older dbs.
   • Pros:
   • Two-pass build is optional if no broken links
   • Two-pass build is now just a quick way of fixing things rather than an obligation
   • Provides both flexibility and reliability based on your quality needs (distros vs developers)
   • It's virtually fool proof for distros.
   • Cons:
   • Need to maintain copies of target databases. Still, a db is just a document.
   • Some scripts/makefile work to automate maintenance

Profiling (Conditional Text)

• Docbook supports conditional text, known as Profiling. This allows the writer to insert multiple versions of a paragraph and then decide at runtime which version to output. This feature also allows putting in phrases and chunks of text that at runtime is decided to output or not.

Currently there are only 2 documents in the tree known to use profiling. xorg-docs/Release Notes, xorg-docs/README and

• Pros:
  • Easy management of those files, saving effort during release time.
• Cons:
  • requires additions to the xorg.xsl file as well as using
  • currently doesn't work on all systems
  • one-pass builds generates a warning: "WARNING: cannot add @xml:base to node set root element. Relative paths may not work." This requires full paths to images used in docs.