DOCBOOK: Réf. : DOCBOOK: Documenting the DTD

[Philippe dot DAIGREMONT at altadis dot com]

I did something like this.
In fact, I wrote an SGML DTD for a Comment Markup Language.
This language is UML semantic inspired and is used to comment my sources
(program's code, DTD, DSSSL, Makefiles, ...)
Once extracted from source code, comments are processed by a DSSSL
style-sheet to produce a docbook <reference> doctype file,
one for each kind of topic manuals (user's manual, programmer's manual,
installation manual, ...)

It's still an experimental trash-coding version but I succedeed to
automaticaly produce a "DocBook: The Definitive Guide"-like refentry
from a light-commented DTD source like that:

<!-- =====================================================================
-->
<!--.<element name=package>   Package UML
-->
<!--.  <note>        Groupe de composants ou de packages
-->
<!-- =====================================================================
-->
<!--.<?src2cml parser="element"
-->
<!ELEMENT package - O
           ( comment+,
            (note|index|keyword|link)*,
            ( (requirement|import|export)*,
           (package+|component+|(class|interface)+|(entity|element)+)
         )
)>
<!ATTLIST package
           name CDATA #REQUIRED
         stereotype (facade|framework|stub|subsystem|system) #IMPLIED
         %cml.att;>
<!--. ?> -->

In this example, even the DTD code is parsed by my comment extracting
program (src2cml) to produce extra documentation directly from source code.
So, result comments from extraction look like this:

<element name=package>   Package UML
<note>        Groupe de composants ou de packages
<minimization tag=start>-<minimization tag=end>O
<content><comment>Grammaire de l'élément package</comment>
( comment+,
            (note|index|keyword|link)*,
            ( (requirement|import|export)*,
           (package+|component+|(class|interface)+|(entity|element)+)
         )
          )
</content>
<attlist>Attributs de l'élément package
<att name='name' type='CDATA' value='#REQUIRED'><comment>.</comment>
<att name='stereotype' type='(facade|framework|stub|subsystem|system)' value='#IMPLIED'><comment>.</comment>
<parament name='cml.att'><comment>.</comment>

 This is the code processed by DSSSL style-sheet to produce DocBook
refentry instance.
Of course, you could include these kind of comments without generate it
from source code, but I am so lazy... :-)

For the moment, nothing is really fixed and each step must be improved
(DTD, DSSSL, source parsers...).
Any suggestion ?

As it was said, "this is stretching off topic for the DocBook list",
so I must stop this toooooo long mail for a whole mailing list.
If somebody is *really* interested, I can try to produce an experimental
package of this and send it.

Hope this can help or give ideas.

Regards,
Philippe Daigremont





Gregory Leblanc <gleblanc@cu-portland.edu> le 05/02/2001 19:09:58

Pour :    docbook@lists.oasis-open.org
cc :

Objet :   DOCBOOK: Documenting the DTD


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?  Thanks,

    Greg





_________________________________________________________________
"This e-mail is intended for the exclusive use of the individual or
entity named above and may constitute information that is priviledged or
confidential or otherwise protected from disclosure . Dissemination ,
distribution , forwarding or copying of this e-mail by anyone other than the
intended recipient is prohibited . If you have received this e-mail in error
, please notify us and completly delete or destroy any and all electronic or
other copies of the original message"
_________________________________________________________________