[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] docbook5 and adding elements (long)
> 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 bobs@sagehill.net ----- Original Message ----- From: "Kells Kearney" <keruzu@gmail.com> To: "Bob Stayton" <bobs@sagehill.net> Cc: <docbook@lists.oasis-open.org> Sent: Friday, March 16, 2007 3:33 PM Subject: Re: [docbook] docbook5 and adding elements (long) > 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> >> > & >> > <xsl:apply-templates select="." /> >> > </xsl:template> >> > >> > </xsl:stylesheet> >> > >> > >> > Invocation with xsltproc >> > ================== >> > xsltproc --nonet --xinclude --output test.fo app.xsl test.xml >> > > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]