This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: [docbook] Newbie question - what schema should I use?
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
---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org