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

[Jeff Beal <jeff dot beal at ansys dot com>]

It would seem that <set/> is definitely the way to go.  We publish a set of
25 manuals for our software package this way, using <link/> and <xref/>
exclusively to link between books.  We publish the set to HTML all at one
go, and create separate PDF files for each book using the "rootid" parameter
in Norm's XSL stylesheets.

Personally, I think people are over-using <olink/> and under-using <set/>.
There are some tool-related advantages to publishing multiple books
separately and using <olink/> to link between them (processing time, being
able to only one book if only one book changed, etc.), but they are just
that -- tool-related advantages.  IMHO, if two books need to link between
each other extensively, they are part of the same document and should be
marked up as such using the <set/> tag.

Jeff

> -----Original Message-----
> From: Robert McIlvride [mailto:robert at cogent dot ca]
> Sent: Thursday, April 17, 2003 8:31 AM
> To: docbook at lists dot oasis-open dot org
> Subject: Re: [docbook] Forst Attempt at Writing a Manual Not 
> Going Well
> 
> 
> Hi Brian,
> 
> > 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?
> 
> In addition to what has already been suggested, if the two books are
> closely related, you might want to consider using the <set> element to
> put them into a set.  Then you could link the references using the
> <link> element.  
> 
> If you include each book as an entity in the set, you then have the
> possiblity of publishing the books separately or together. 
> This is what
> we do for our 17 books.  Our case is somewhat more involved 
> than yours,
> and we are "still" using SGML, but if you'd like to see how we do it,
> here's an example:
> 
> http://developers.cogentrts.com/cogent/prepdoc/pd-specialorgan
ization.html

The results are here:

http://developers.cogentrts.com/cogent/cogentdocs/cogentdocs.html

Just another way to look at the problem...

Cheerio!

Bob

---------------------------------------
Robert McIlvride (robert at cogent dot ca)
Cogent Real-Time Systems (www.cogent.ca)

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe at lists dot oasis-open dot org
For additional commands, e-mail: docbook-help at lists dot oasis-open dot org



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe at lists dot oasis-open dot org
For additional commands, e-mail: docbook-help at lists dot oasis-open dot org