OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook-apps] Shared text entities


I had the same problems with XInclude. In addition, I wanted to do
some other pre-processing of the included documents, so it made sense
for me to write a python script which did that, and generated docbook.

So my source files do not have any DTDs, my ant build script just
scans for all .XML files and translates them into docbook, generating
the DTD in the end.

Then I added some custom elements, <include> and <img> so it would be
easier to refer to external files than with the original
docbook/xinclude syntax.

Now I compose in standard XML, I don't need to maintain DTDs, and I
run my script to generate standard docbook.

http://cartan.cas.suffolk.edu/moin/SlackersDocbook


On 10/8/05, Camille Bégnis <camille@neodoc.biz> wrote:
> Thanks Tom for your suggestions!
>
> I was hoping to use a standard mechanism, but your tricks are
> attracting... Hard to make the right choice.
>
> Camille.
>
> Thomas Schraitle wrote:
> > 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
> >
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>
>


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]