Re: [docbook] generating refentries (refentry) from something simpler?

["Michael(tm) Smith" <smith@sideshowbarker.net>]

Troy Cauble <troy@bell-labs.com>, 2007-01-07 11:02 -0500:

> As part of writing a reference manual, I've written a couple of 
> refentries and checked the HTML they generate.  As I'm using
> them, there is a lot of boilerplate markup in the refentry XML.
> 
> I am considering creating a simpler XML alternative to
> refentry and using XSLT to generate the proper refentries
> before DocBook processing.  Is this a reasonable approach?

Yeah, I think it's a very reasonable approach -- and if you have
the time to do the work of making the XSLT stylesheet to convert
your custom markup to standard Refentry markup, it's probably
always a better way to go than just using standard DocBook. It'll
make your source markup more closely fit the actual content you
need to mark up.

This is pretty much the kind of case that DocBook was originally
intended for -- as an interchange format. The problem is that many
users don't have the time and interest or XSLT skills to be able
to construct their own customizations. If you do, I'd highly
recommend taking the time to get set up to use your own custom
markup.

> Should I do this with Customization Layers or something else?

At a minimum, you just need to create an XSLT stylesheet to
convert your custom markup to standard DocBook. That won't be a
customization layer -- it'll just be a standalone stylesheet.

But if you want to be able to validate documents that you write in
your custom vocabulary, than yes, you're going to need to create a
customization layer for that. If you do decide to take that
approach, and you have time to get up to speed on RELAX NG (which
isn't that hard -- it is simple by design), then I'd recommend
that you use the RELAX NG schema for DocBook 5 as your starting
point. You can find the current version of it here:

  http://www.docbook.org/schemas/5x

You'll probably want to work from the *.rnc (compact-syntax)
schema (instead of the *.rng one, which uses more-verbose XML
syntax). I don't know of any good how-to guides to customizing
RELAX NG schemas, but if you decide to try it, I think you can get
help on this list and on the #docbook channel on irc.freenode.net,
and also the rng-users mailing list.

Once you've made your customizations, you can then either convert
your RELAX NG schema to a DTD (if you are using a DTD-aware editor
and/or validator) or just keep it .rnc form and use it with
nxml-mode for Emacs (and with RELAX-aware validators if you want
-- though using nxml-mode pretty much obviates the need to do any
other validation of your source).

Anyway, I'd very much encourage you to try this, and would be
happy to help answer further questions about it here and on
the #docbook IRC channel.

  --Mike