Re: [docbook-apps] Generguide 0.2 - Generic Docbook Guide Builder and Software Developers' Guide

[Bob Stayton <bobs@sco.com>]

Hi Cameron,
I haven't had a chance to try it out, but I can offer
some design help.

On Tue, Nov 04, 2003 at 06:52:39AM +1100, Cameron Shorter wrote:
> We are excited to announce that we have our first public release of 
> http://generguide.sourceforge.net .

[ stuff deleted ]

> Are you a docbook or XSL guru?
> ========================
> We want design advice on the following issues:
> 1. How should we implement variables within our documentation?  Currently we 
> use ENTITIES like &project_name; however entity files are not XML and hence 
> hard to process.  We are considering extending the Docbook schema to add a 
> <variable> tag.

I think it depends on what you are doing with the variables.
It looks like you want them for text strings, in which case
entities are a good fit.  Entities are resolved when the file
is loaded and parsed, so your stylesheet doesn't need to
do anything about them.  They also avoid extending Docbook,
which I think is a good thing when you are trying to merge
docbook from a variety of sources, including web resources over
which you have no control.  Finally, you can put all the
entities in one file and use an XML catalog to locate them.

 
> 2. Generguide uses modular docbook, which means a docbook file can include 
> another docbook node using <xinclude href="another_section.xml">.  However, 
> we have run into problems when linking from one module to another because it 
> causes invalid xml.  Ie, when the main doc contains <link 
> linkend="an_id_from_another_section">.  What should we do to avoid getting 
> invalid XML?

I solved this problem by using olinks.
Have you seen the chapter in my book about modular doc?
It has a section on modular cross references with olinks.

http://www.sagehill.net/docbookxsl/ModularDoc.html

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com