[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, 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]