generating refentries (refentry) from something simpler?

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?
Should I do this with Customization Layers or something
else?

Thanks,
-troy


refentry2 ::=
(title, purpose, contentmodel, attr?, desc, processing?,
parents, kids?, seealso?, examples?)

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org

Troy Cauble <troybell-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

------------------------------------------------------------
---------
To unsubscribe, e-mail: docbook-unsubscribelists.oasis-open.org
For additional commands, e-mail: docbook-helplists.oasis-open.org