Forst Attempt at Writing a Manual Not Going Well

[Brian Sutin <sutin@ociw.edu>]

I am part of a team building a large astronomical spectrograph:

    http://www.ociw.edu/instrumentation/imacs/

which requires a convenient system for writing documentation.
I initially picked DocBook as the obvious choice, but I seem
to be unable to make it do (what seems to me to be) the most
obvious tasks.

For example, the structure of the documentation is as follows.
There are two sections, a User Manual and a Technical Manual.
They should print separately as completely separate books,
but they should be able to refer to each other in HTML.  How
do I do that?

Second, each of the two parts above is composed of sections
which have been written by different people.  How do I make
the output give attribution?  If I try:

    ...
    <title>
        Glorious Bits of Stuff
        <author>
             <firstname> Bob </firststuff>
             <firstname> Bones </firststuff>
        </author>
    </title>
    ...

Then the output (HTML) looks like:

    ...
    Glorious Bits of Stuff Bob Bones
    ...

Something like a line break would be good, but DocBook is not
supplying one.  The .pdf output isn't printing the chapter
titles at all.  Is that a bug?

Trying to use the <article> keyword for each section just so
the author prints in some intelligent way does not seem like
the right thing to do.

The source I am playing with and all of the resulting output
are available at:

    http://www.ociw.edu/~sutin/imacs/manual/

Confused,

Brian Sutin


-- 
Brian M. Sutin      Instrument Scientist       Pasadena, CA
The Observatories of the Carnegie Institution of Washington