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

[Jeff Biss <jeff@marco-inc.com>]

Brian,

First, your example doesn't seem to fit the requirements of the DocBook 
DTD. Try the following:

...
<title>
Spectography
	<author>
		<firstname>Bob</firstname>
	</author>
	<author>
		<firstname> Bones </firststuff>
	</author>
</title>
    ...

Even though this is valid, it does appear that the stylesheet needs to be changed to output the names on separate lines though, if this form is to be used. You could try the following:

<book>
<title>Spectography</title>
<authorgroup>
	<author><firstname>Bob</firstname></author>
	<author><firstname>Bones</firststuff></author>
</authorgroup>
<chapter>
<title>User Manual
	<author><firstname>Bob</firstname></author>
</title>
</chapter>
<chapter>
<title>Technical Manual
	<author><firstname>Bones</firstname></author>
</title>
</chapter>
</book>

Again, the stylesheet needs to be changed to account for the desire to have the author's name on a new line.

As for linking, try this:

<link linkend="target">something</link>

<para><anchor id='target'/>Something Explained</para>

This provides links within a single file. If you create a single book comprised of two sections this will work. The stylesheet would separate the sections: User Manual and Technical Manual.

Sincerely, Jeff Biss




Brian Sutin wrote:

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