This is the mail archive of the
docbook-apps@lists.oasis-open.org
mailing list .
Re: [docbook-apps] Generguide 0.2 - Generic Docbook Guide Builder and Software Developers' Guide
- From: Bob Stayton <bobs at sco dot com>
- To: Cameron Shorter <cameron at shorter dot net>
- Cc: docbook-apps at lists dot oasis-open dot org
- Date: Mon, 3 Nov 2003 11:29:33 -0800
- Subject: Re: [docbook-apps] Generguide 0.2 - Generic Docbook Guide Builder and Software Developers' Guide
- References: <200311040652.39184.cameron@shorter.net>
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
To unsubscribe from this list, send a post to docbook-apps-unsubscribe@lists.oasis-open.org, or visit http://www.oasis-open.org/mlmanage/.