Re: [docbook] DTD Customisation

[Yann Dirson <ydirson at altern dot org>]

On Wed, Jul 21, 2004 at 06:04:09AM -0700, Mike Devlin wrote:
> I'm part of a development team who have been assigned the task of
> developing a documentation procedure for our company. We plan to use
> docbook but it looks like we'll need to customise the DTD slightly. I
> understand it's possible to create a customisation layer for the DTD to
> allow this.
> 
> Our documents will have a strict structure as follows:
> 
> <book>
>   |___<preface>
>   |___<chapter>
>   |     |
>   |     |_<section role="topic">
>   |     |  |_<section role="overview">
>   |     |  |_<section role="detail">
>   |     |  |_<section role="wrapup">
>   |     |  
>   |     |_<section role="topic">
>   |     ...
>   |
>   |___<chapter>
>   ...
>   |___<appendix>
>   |___<index>
> 
> ie: Any number of topics inside any number of chapters but each topic
> MUST have the 3 children "overview", "detail" & "wrapup". This is
> because different, related information must go in each of these with the
> possibility of a sub-set being output to PDF when published.
> 
> What mods to the DTD would I need to make to ensure that a Validator
> will only accept documents in this format?

As Camille said, this cannot be expressed with the usual DTD
customisation.  Not only forcing the attribute values would be
problematic, but forcing different content models for <section>
according to the nesting position cannot be done.

However, this could be done using architectural forms.  You could make
a customisation layer as usual, defining new elements <overview>,
<detail>, <wrapup> as copies of <section>, new element <topic> with
the strict (overview,detail,wrapup) content but with <section>'s
attributes.  The rest of the customisation (content restrictions)
would be done as usual.

Then you'd have to declare the DocBook DTD as architectural form, and
define an architectural mapping of your elements to <section>'s,
possibly using the element->attribute remapping feature to get roles
as expected.  Then either ask your (architecture-aware) processing
tools (eg. openjade) to act on the docbook structure, or first
normalize your document to this structure using 'osgmlnorm
--architecture=docbook'.

I think however that the element->atribute architectural mapping is
not implemented in opensp yet.

You'll find documentation at http://xml.coverpages.org/archForms.html
and a tutorial at http://www.isogen.com/papers/archintro.html

Best regards,
-- 
Yann Dirson    <ydirson@altern.org> |
Debian-related: <dirson@debian.org> |   Support Debian GNU/Linux:
                                    |  Freedom, Power, Stability, Gratis
     http://ydirson.free.fr/        | Check <http://www.debian.org/>