DOCBOOK-APPS: Customization layer question for DocBook XML

[Dennis Grace <dgrace at us dot ibm dot com>]

Allow me to preface this question by admitting that , although I've written
several driver files, I've not previously tried to write a customization
DTD layer.

I'm trying to produce a man page that is more complex than the standard.
Because the resultant man page will describe nested commands (command xxx,
subcommands xxx yyy, xxx zzz, xxx aaa, etc., where each subcommand has a
fairly complex series of options), I intend to produce a man page that
includes several tiers. To that end I wanted to modify the refentry.element
portion of dbhier.dtd (I've been using DTD 4.2CR) from

<!ENTITY % refentry.element "INCLUDE">
 <![%refentry.element;[
 <!ELEMENT refentry %ho; (beginpage?,
                     (%ndxterm.class;)*,
                     refentryinfo?, refmeta?, (remark|%link.char.class;)*,
                     refnamediv, refsynopsisdiv?, (refsect1+|refsection+))
            %ubiq.inclusion;>
 <!--end of refentry.element-->]]>


 to allow multiple instances of (refsynopsisdiv?, (refsect1+|refsection+)).

 I tried the following customization layer:

 <!ENTITY % refentry.element "INCLUDE">

 <!--load DocBook-->
 <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook XML V4.2CR1//EN"

 "http://www.oasis-open.org/docbook/xml/4.2CR1/docbookx.dtd";>
 %DocBookDTD;

 <![%refentry.element;[
 <!ELEMENT refentry %ho; (beginpage?,
                     (%ndxterm.class;)*,
                     refentryinfo?, refmeta?, (remark|%link.char.class;)*,
                     refnamediv, (refsynopsisdiv?, (refsect1+|refsection+))
 +)
            %ubiq.inclusion;>
 <!--end of refentry.element-->]]>

 I got an error that said "validity error: Redefinition of element
 refentry" with a pointer to %ubiq.inclusion.

 I tried removing the inclusion. I even tried stripping the entire element
 definition back to the 4.1.2 version, but I still keep getting inclusion
 errors.

 I know the change I'm shooting for is possible, because I tried a SYSTEM
 identifier with a temporary change to dbhierx.dtd, which worked.

 Is something seriously broke in my customization format? What am I
 missing?

 Thanks.


 Dennis Grace

 Information Developer
 IBM Linux Technology Center
 (512) 838-3937  T/L 678-3937  cell: (512)-296-7830
 dgrace@us.ibm.com

 This sentence no verb.