[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