Re: [docbook] docbook5 and adding elements (long)

["Kells Kearney" <keruzu@gmail.com>]

On 3/15/07, Bob Stayton <bobs@sagehill.net> 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
> bobs@sagehill.net
>
>
> ----- Original Message -----
> From: "Kells Kearney" <keruzu@gmail.com>
> To: <docbook@lists.oasis-open.org>
> 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>
> >        &amp;
> > <xsl:apply-templates select="." />
> > </xsl:template>
> >
> > </xsl:stylesheet>
> >
> >
> > Invocation with xsltproc
> > ==================
> > xsltproc --nonet --xinclude --output test.fo app.xsl test.xml
> >