This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


Hi Jose,

On Thu, 2003-07-17 at 13:12, Jose Gonzalez Gomez wrote:
>     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"? 

By that I mean as stand-alone documents.  From what you say below, it
appears you don't have that requirement.

> 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?

>From your outline above, if I were you, I'd make a single <book>, with
<chapter>s at the level of Business model, Requirements, and Design. 
The contents you show for the Requirements chapter could be handled with
<sect>.  Since you want individual HTML pages of each use case, you
would then set your chunk section depth XSL stylesheet parameter to 3,
for 3 levels deep, like this:

<xsl:param name="chunk.section.depth" select="3"></xsl:param>

(The DocBook term for an individual HTML page is "chunk.")  This assumes
you are using XSL to process your document and that you have set up a
stylesheet customization layer.  For more information, I strongly
recommend Bob Stayton's book:
http://www.sagehill.net/docbookxsl/index.html

If you take this approach, You might need or want to fiddle with the
toc.section.depth and toc.max.depth parameters (see
http://docbook.sourceforge.net/release/xsl/current/doc/html/ ) to
generate links to subsections at the top of each section page.

An alternative would be to collect all of your use cases and make them
<refentry>s in a single <reference> after all the chapters, and then
link to them from wherever you need to.  This has the advantage of not
associating them with any particular subsystem, which may or may not be
useful in your situation.

In any event, you can create links from any section to any other section
using either the <link> or <xref> element.  The <xref> element
automatically generates text (modifiable by stylesheet parameters),
while the <link> element lets you put in any text.

By the way, after reading Mark Boylan's posting, I should probably
mention that we also use cvs for our source code.  Some of our documents
are single files, but many of them are multiple files.  For an overview
about our documents and how we produce them, you are welcome to refer to
our in-house manual:

http://developers.cogentrts.com/cogent/prepdoc/book1.html

We started off in SGML 4 years ago, and are now starting to move to XML
to take advantage of the XSL stylesheets, but you can interchange "SGML"
for "XML" in almost every context.  The HTML output of our documentation
is here:

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

Hope that helps,

Cheerio!

Bob

-- 
---------------------------
Robert McIlvride, Cogent Real-Time Systems, Inc.
robert@cogent.ca  (888) 628-2028  www.cogent.ca


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]