Re: [docbook] Forst Attempt at Writing a Manual Not Going Well

[Stephane Bortzmeyer <bortzmeyer@nic.fr>]

On Wed, Apr 16, 2003 at 05:48:18PM -0700,
 Brian Sutin <sutin@ociw.edu> wrote 
 a message of 61 lines which said:

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

Congratulations and good luck for this useful research.

> which requires a convenient system for writing documentation.
> I initially picked DocBook

Reading your message, it seems you do not have (yet) a clear
understanding about what DocBook is and isn't. DocBook is not a
documentation system. It is a format for documentation. For instance,
my documentation system is
DocBook+Emacs/psgml+CVS+xsltproc+NormanWalshStylesheets.

> 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?

If it is only in HTML, the simplest solution is to use ulinks. With
them, you can ask people to <ulink
url="http://www.ociw.edu/doc/tech/">read the Technical Manual</ulink>.

Otherwise, use olinks but they are more complicated (but have the
potential to work even for other formats).

> Then the output (HTML) looks like:
> 
>     ...
>     Glorious Bits of Stuff Bob Bones

It is not the output of DocBook, it is the output of your
documentation system. If you use NormanWalshStylesheets (you are not
forced to do so), you'll may have to write a custom driver to adapt
the output to your liking.

> Something like a line break would be good, but DocBook is not
> supplying one.

DocBook does not have any relationship with the output. It depends on
the stylesheets (for which the proper mailing list is docbook-apps).