Re: [docbook] Newbie question - what schema should I use?

[Jose Gonzalez Gomez <jgonzalez@opentechnet.com>]

    Bob,

    My idea is having a lot of small related documents (maybe HTML) that 
are easily browsable using links between those documents. In this sense, 
each use case would be a document (html page), and a requirements 
specification would contain a set of use cases (with contain I mean they 
would be accesible following a link).

    What do you mean with "publish them separately"? I would like to 
generate something like this:

Business model
|- .......

Requirements
|- Actors specification
|- Software Requirements Specification
    |- SRS for subsystem 1
    |    |- Use case 1
    |    |- Use case 2
    |- SRS for subsystem 2
         |- Use case 3
         |- Use case 4

Design
|- ............

    Every node in the tree would be an html page. You could browse from 
father to child, and between nodes (for example, from an use case to the 
actors specification, whenever an actor is mentioned).

    Your answer seems to imply that the best approach would be to use 
sects, as this would allow unlimited nesting. But what do you mean when 
you say that a sect cannot be published? I wouldn't be able to generate 
an html page corresponding to a sect?

    Thank you very much, regards
    Jose

Bob McIlvride wrote:

>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
>sect.
>
>Just a few ideas...
>
>Cheerio
>
>Bob
>
>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
>>    
>>