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] Newbie question - what schema should I use?

Hi Jose,

If you could clarify what your requirements are for a "document" it
might help.  For example, do you mean that each use case is one
document?  Can a "document" contain other "document"s?  

If each "document" is a separate thing, and you want the ability to
publish it either separately or associated with other "document"s, then
each one could be an <article>.  These could be collected into one
<chapter> or <article> within a <book>, which would allow linking. Books
could be collected into a <set>, allowing three levels of hierarchy
above the "document" level, but no hierarchy among "document"s.

On the other hand, if you have each "document" correspond to a <sect>,
then you have much more flexibility regarding hierarchical organization,
as one sect can contain another recursively.  The <sect>s can collected
into <chapter>s of a single book.  You can't publish a <sect> by itself,
but you can always make a wrapper of an <article> that contains one

Just a few ideas...



On Tue, 2003-07-15 at 18:01, Jose Gonzalez Gomez wrote:
>     Hi there,
>     I would like to use docbook as the format for the documentation in 
> several projects I'm working on now. The idea is having a set of related 
> documents, in a tree hierarchy, containing, among other things, the 
> requirements of the application specified as use cases. One of the 
> things I need in this documentation is to be able to link to other 
> documents, so I don't have duplicated and/or bloated specifications, 
> making the documentation more readable. So now the questions:
>     I thought about using the simple docbook schema, as I don't need a 
> lot of the things that appear in the whole schema, but this schema 
> doesn't seem to support linking between documents. So what's the best 
> solution? Should I go for the whole schema? Or is there any way to link 
> between documents using the simple schema? (I forgot to mention... the 
> main output format will be html). Maybe instead of having a lot of small 
> documents I should have just a dockbook document for the whole 
> documentation set and generate from this several html documents with 
> links to each other? How can I achieve any of the above (I mean, what 
> tools should I use)?
>     Any advice would be greatly appreciated.
>     Thanks in advance, regards
>     Jose
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org
Robert McIlvride, Cogent Real-Time Systems, Inc.
robert@cogent.ca  (888) 628-2028  www.cogent.ca

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