OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


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@cogent.ca]
> Sent: Thursday, April 17, 2003 8:31 AM
> To: docbook@lists.oasis-open.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@cogent.ca)
Cogent Real-Time Systems (www.cogent.ca)

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




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]