Re: [docbook-apps] Shared text entities

[Thomas Schraitle <tom_schr@web.de>]

Hi Camille,

On Saturday 08 October 2005 13:40, Camille BĂ©gnis wrote:
> [...]
> So I thought of using the xinclude plus xpointer mechanism in order to
> pick the "entities" in a real XML file instead. The problem is that the
> xinclude syntax is quite verbose, so replacing &docbook; with
> <xi:include href="entities.xml xpointer="docbook"
> xmlns:xi="http://www.w3.org/2001/XInclude"; /> makes the XML code
> significantly harder to read.
>
> So I am interested in any experience in this area.
> If you have another idea than xinclude, I'll be happy to hear it as
> well.

If you look for another solution you should consider some parameters:

 * How much control by DTD/schema?
 * Flexibility
 * Verbosity
 * Extensibility

There are a number of different methods to use, each have advantages and 
disadvantages, of course:

1. Processing instructions (PIs)
You can use something like

 <para>Use <?dbentity entity="foo"?> to ...</para>

Advantages:
  - A bit less verbose than XIncludes
  - Writer have freedom to choose from different "sets"
  - Very extensible and flexible
  - It doesn't require to change the DTD/Schema

Disadvantages
  - Freedom is sometimes not always useful. Think of writers who
    should use restricted values only (XML editors). 
  - There is no validation for PIs, e.g. you can not restrict
    values. You can check the correct values only in the XSLT
    step, for example
  - "Entity replacement" must be resolved by another step
  - PIs shouldn't be use for content only


2. (Ab)use of an exisiting element
You could use an element with a "special" attribut. In case of DocBook you 
could use the element phrase. For example:

 <para>Use <phrase role="entity:foo"/> to ... </para>

Advantages:
  - Less verbose than XInclude
  - DTD can restrict the possible values
  - phrase can occur on allowed content only
  - XML editors can offer writers the set of possible values

Disadvantages:
  - You have to change the DTD/Schema to add all possible 
    attribute values
  - The semantic of phrase doesn't really fit
  - It might conflict with other content for phrase (processing
    might be a bit complicated)
  - It must be resolved by another step


3. Introduce new element
It is a variation of point 2: Insert a new element just for this purpose. 
For example:

 <para>Use <e:entity name="foo"/> to ... </para>

Advantages:
  - Less verbose than XInclude
  - DTD/Schema can restrict possible values
  - XML editors can offer writers the set of possible values

Disadvantages:
  - You have to change the DTD/Schema
  - Complicates the content modell in case of DTD
  - It must be resolved by another step

What is the best solution? I don't know. It is up to you. :-)


Tom

-- 
Thomas Schraitle