> Do you know of a good step-by-step example of customizing Docbook5
with RelaxNG?
Have you seen the DocBook 5.0 Transition Guide? It has examples:
http://www.docbook.org/docs/howto/
Bob Stayton
Sagehill Enterprises
DocBook Consulting
----- Original Message -----
From: "Kells Kearney" <>
To: "Bob Stayton" <>
Cc: <>
Sent: Friday, March 16, 2007 3:33 PM
Subject: Re: [docbook] docbook5 and adding elements (long)
> On 3/15/07, Bob Stayton <> wrote:
>> Hi Kells,
>> The DTD version of DocBook 5 does not have the %local.* parameter
>> entities.
>> All of the customization features are in the RelaxNG version, from which
>> the DTD version is generated.
>
> Oh? Ooops! I didn't notice that in this variation. Thanks!
>
>> If you don't want to customize the RelaxNG and generate a DTD from it,
>> you
>
> Sigh. I'd love to "customize the RelaxNG and generate a DTD from
> it", but unfortunately I really don't have the knowledge about how to
> do that, so I would really appreciate one good example to show me how.
> I'd like to do things the "right" way if I could.
>
> Do you know of a good step-by-step example of customizing Docbook5
> with RelaxNG? ie no hand-waving and "the rest is left as an exercise
> for the reader" or "implementation is trivial", just a simple example
> from which I can download the example files, execute commands and have
> a 90% chance of having the example work out of the box
>
>> can just edit a copy of the DocBook 5 DTD. Because it is a flat
>> structure with no parameter entities, editing it is straightforward, if
>> sometimes tedious.
>>
>> You need to add your new element as you have, and you also need to edit
>> any
>> content models
>> of elements that are to contain your new element. If you don't do that,
>> then although the
>> element name is valid, there is no place in the document where its
>> position
>> is valid.
>
> If I'm understanding you correctly, you mean that I need to put the
> new element into an appropriate place in the grammar so that there's
> enough context for the element to be properly processed. Is that
> right? If so, that makes sense but that generality isn't clear enough
> to help me at this stage of my understanding.
>
>>
>> I don't think you want to use ENTITY as the attribute type for "server".
>> Such an attribute
>> would contain the name of an unparsed entity declared elsewhere, and I
>> don't see that
>> for server1, server2, etc. I think you want CDATA there.
>
> Okay.
>
>> In your test.xml sample, the elements are not actually in the DocBook
>> namespace.
>> You declare the namespace with a "db" prefix, but you don't use the
>> prefix.
>> If you declare the namespace without a prefix, then your elements will
>> be
>> in
>> that default namespace.
>>
>> Your app.xsl needs to import the stock docbook stylesheet (perhaps it
>> does
>> and you
>> aren't showing that). Then the template that matches on Docbook
>> elements
>> must have
>> the namespace prefix match="db:app".
>>
>> Then the call-template uses a name of "db:prompt", but you don't define
>> a
>> template with that name.
>> Also, it is unusual to define a template name using a namespace prefix.
>> It looks a bit like you are trying to invoke the template that handles
>> the
>> prompt
>> element to handle your app element, but XSLT doesn't work that way.
>
> Okay. Wow, this is really frustrating. :(
>
> The impression I'm getting is that I need to use XSL-FO to get what
> I want. Is that right?
>
>> You might consider dropping back to DocBook4 so you don't have to
>> deal with namespaces at the same time you are figuring other things out.
>> Do you really need DocBook5?
>
> Errrr.... No, I guess not, but isn't Docbook5 supposed to save the
> universe? :)
>
> Quite honestly, LaTeX would be a much faster path for me to getting
> publication-quality print output (after all, it was generating good
> stuff for me 15 years ago! :), but there a number of compelling
> advantages (IMO) to using Docbook. (I think! :)
>
>>
>> Bob Stayton
>> Sagehill Enterprises
>> DocBook Consulting
>>
>>
>>
>> ----- Original Message -----
>> From: "Kells Kearney" <>
>> To: <>
>> Sent: Tuesday, March 13, 2007 4:13 PM
>> Subject: [docbook] docbook5 and adding elements (long)
>>
>>
>> > I've taken a look through the e-mail archives, and I've tried
>> > googling, but I'm unable to find an answer to why I can't do something
>> > that should be quite simple. :( I've found documentation for how to
>> > do it using Docbook 4.x (and had no luck using it with Docbook 5), but
>> > it *seems* like a good thing to do it in Docbook 5. (Right?)
>> >
>> > I'm hoping that some kind soul can help me understand what it is
>> > that I'm doing wrong. I think that all I need is one good example.
>> > Thanks in advance!
>> >
>> >
>> > kells
>> >
>> >
>> > What I'm trying to do:
>> > ================
>> > I would like to be able to create an application-specific prompt to
>> > create documentation for the application. The prompt looks like:
>> >
>> > app: server_name>
>> >
>> > where I'd like to define server_name in an entity as an attribute
>> > with a reasonable default. To illustrate, I'd like to be able to
>> > write:
>> >
>> > <app> <command> bleh </command>
>> > <variable>colour</variable>=<replaceable>blue</replaceable>
>> > </app>
>> >
>> > <app server="server2" > <command> bleh </command>
>> > <variable>colour</variable>=<replaceable>green</replaceable>
>> > </app>
>> >
>> > and have the output look something like:
>> >
>> > app: server1> bleh colour=blue
>> > app: server2> bleh colour=green
>> >
>> > Where I am so far
>> > ==============
>> > Input file: test.xml
>> > ----------------------------
>> > <?xml version="1.0" encoding="UTF-8"?>
>> > <!DOCTYPE book SYSTEM "app.dtd" >
>> >
>> > <book version="5.0"
>> > xmlns:xlink="http://www.w3.org/1999/xlink"
>> > xmlns:xi="http://www.w3.org/2001/XInclude"
>> > xmlns:svg="http://www.w3.org/2000/svg"
>> > xmlns:mml="http://www.w3.org/1998/Math/MathML"
>> > xmlns:html="http://www.w3.org/1999/xhtml"
>> > xmlns:db="http://docbook.org/ns/docbook"
>> >>
>> >
>> > <chapter>
>> > <title>Hello world!</title>
>> > <para>Sample explanatory text here</para>
>> >
>> > <app server="server2" > <command> bleh </command>
>> > <variable>colour</variable>=<replaceable>green</replaceable>
>> > </app>
>> >
>> > </chapter>
>> > </book>
>> >
>> >
>> >
>> > My DTD app.dtd:
>> > ------------------------
>> > <?xml version="1.0" encoding="UTF-8"?>
>> >
>> > <!-- Add the "app" element to something hopefully similar to what I
>> > want. :)
>> > If I understand things correctly, this inserts the element
>> > definition into
>> > the right spots in the DocBook grammar (aka DTD).
>> > -->
>> > <!ENTITY % local.tech.char.class "|app" >
>> >
>> > <!-- Other documentation I've seen suggests taking the
>> > docbook dtd, making a parameter entity and invoking it here.
>> > It goes badly for me if I do
>> >
>> > <!ENTITY % DOCBOOK SYSTEM
>> > "file://c:/docbook/lib/docbook-50b5/dtd/docbook.dtd">
>> > %DOCBOOK;
>> >
>> > So I can't use the above. Right?
>> >
>> > -->
>> >
>> > <!-- Create the "app" element -->
>> > <!ELEMENT app (#PCDATA|filename|replaceable|constant|parameter)* >
>> >
>> > <!-- Set a default server name -->
>> > <!ATTLIST app server ENTITY "server1" >
>> >
>> >
>> >
>> > My app.xsl
>> > ------------------
>> > <?xml version="1.0" encoding="UTF-8"?>
>> >
>> > <xsl:stylesheet version="1.0"
>> > xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
>> >
>> > xmlns:fo="http://www.w3.org/1999/XSL/Format"
>> > xmlns:db="http://docbook.org/ns/docbook"
>> >>
>> >
>> > <!-- Here's where it starts to get really scary for me. :)
>> > This is also wrong, but I *think* shows what I want to do.
>> > -->
>> > <xsl:template match="app">
>> > <xsl:call-template name="db:prompt">
>> > <xsl:value-of select="@server" />
>> > </xsl:call-template>
>> > &
>> > <xsl:apply-templates select="." />
>> > </xsl:template>
>> >
>> > </xsl:stylesheet>
>> >
>> >
>> > Invocation with xsltproc
>> > ==================
>> > xsltproc --nonet --xinclude --output test.fo app.xsl test.xml
>> >
>
>
