OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: DOCBOOK: Documenting the DTD


Gregory Leblanc <gleblanc@cu-portland.edu> writes:

> I'm sorry that this is stretching off topic for the DocBook list, but I
> know that I've seen possible answers and suggestions here. I remember
> Norm saying something about making the DocBook DTD "self documenting".
> I'm assuming this is done by putting things into the DTD that can be
> extracted using some too, generating something akin to the reference
> section of DocBook: The Definitive Guide.  Does anybody have some more
> details on this?

There's Norm's DTDParse:

  http://nwalsh.com/perl/dtdparse/ 

Check out Earl Hood's perlSGML:

  http://www.oac.uci.edu/indiv/ehood/perlSGML.html

and Ian Graham's modified distribution of it:

  http://www.java.utoronto.ca/DTDs/

Graham's modifications are intended mostly to just produce
better-looking, more compact output. I think most people will probably
prefer the output they produce over the stock perlSGML output.

Take a look specifically at the dtd2html utility (in Graham's version,
dtd2html-table) that's part of that package, in particular the
-descfile flag and description file syntax:

  http://www.oac.uci.edu/indiv/ehood/perlSGML/doc/html/dtd2html.html#elemdescfile

I think the approach it uses, of maintaining the "natural language"
documentation into a separate file, is preferable to trying to embed
lengthy human-readable documentation in the DTD itself.

It seems to me appropriate for the DTD itself to contain short
documentation, but trying to embed natural-language information like
that found in the Description, Attributes, and Examples found in
reference part of DocBook: The Definitive Guide. It would just
decrease the readability of the DTD itself.

It would be nice if, off the shelf, the perlSGML description-file
provided more of a structure, i.e. with a heirarchy of sections
something like what's in TDG (e.g. Description, Attributes, Examples,
etc.). I while back, I was working on putting together a simple patch
to it to add some structure like that, but moved the project to the
back burner. If I ever get it done, I'll post it to the list.

Unfortunately, one thing that's lacking in all these tools is a
mechanism for producing detailed documentation about parameter
entities. For example, it would be very useful to be able to generate
documentation for the *.class and *.mix parameter entities, including
natural-language descriptions.

  --Mike Smith





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC