*** RENDERING ***

Rendering XML requires the generated config-*.xml files and the files in
directory 'out' and 'pre', but not 'tmp'. Directories 'etc' and 'src' are
also required, but they are constant, i.e. not changed by building examples.

Actually 'make html' does four different things:

1. Go sure ulink.xml and calc.xml are built.
2. Patch etc/ldp.dsl with paths to system style sheets.
   This is a mess. If it fails try

     locate docbook | grep '\.dsl$' | less

   and incorporate the results somehow.
3. etc/mkhtml.sh intro
4. etc/mkhtml.sh platform

Step 1. is superfluous if a plain 'make' succeeded. If you want to render
non-functional examples a 'make html_deps' will do as many calculations
as possible.

Step 2. is required only once. An explicit 'make dsl' should do.

Steps 3. and 4. can be called manually. They set 'config.xml' as a
symbolic link to the actual config-file. By default that is
'config-$(HOST).xml'.

Recommended procedure is to first do a 'make html' on your primary system.

To build the examples from secondary systems you copy the architecture
specific directory, i.e. the tar file generated by 'make dist_out' to
the primary system. Then pass a second argument to etc/mkhtml.sh,
the host name of the other system.

   etc/mkhtml.sh platform host.domain

*** YREF ***

A 'yref' is a link between the two document parts, i.e. general
introduction and platform dependent stuff. The word is my own
invention, a pun on 'xref'. yrefs are implemented as ulink-elements
referenced as system entities. They are used like this:

       and the improvements made in &yref.entry.point;.

This line is from intro/rst.xml and points platform/entry.point.xml.

yref definitions are built using etc/yref.sh, etc/yref-intro.xslt
and etc/yref-platform.xslt. A big problem with XSLT is that it
requires its input to be complete and valid XML. This starts with
a functional system entity in intro/main.xml and platform/main.xml,
and includes all declared system entities. Defining the yrefs in
intro/yref/ requires a complete platform/main.xml, including
platform/yref/, and vice versa.

I found no way to bootstrap the documents without existing
yref-directories. So while those directories are just generated
text they are included with the source archive.

Another unpleasant consequence is that a bug in the XSLT scripts
can ruin your document beyond repair if the bug generates invalid
yref-files. Of course you can fix the bug, but on the second run
platform/main.xml will be rejected because of all those invalid
system entities...

Make backups, not bugs.
