Comments within DTDs (Teapot not tempest)

[len bullard]

Deborah Aleyne Lapeyre wrote:
> 
 
> 1)  We do the same.  Element name comment just before
> element. Attribute value comment between the element
> declaration and the ATTLIST.  It's fine:
> 
> <!--                     NAME OF ELEMENT                -->
> <!ELEMENT thiselement    (contentmodel)                   >
> <!--         id:         Unique identifier for the element
>              role:       One of
>                           good:  looks like Toshiro Mifune
>                           bad:   looks like Clint Eastwood
>                           ugly:  looks like Paula Jones
>              whatever    I don't care; put something
>                          here                           -->
> <!ATTLIST thiselement
>              id          ID                  #IMPLIED
>              role        (good|bad|ugly)     "good"
>              whatever    CDATA               #REQUIRED    >
> 
> Like good typesetting, we try for a small number of
> verticals.  This also lets you scan quickly for full
> element name, tag name, or attribute name.

Yes.  Hard on long DTDs though.  IMHO, it easier 
to maintain markup with the comments in a separate 
file and link them.  Helps the reuse across the 
system.

> 2) But I confess that I miss the old SGML days, where
> our house style looked more like this:
> 
> <!--                     NAME OF ELEMENT                -->
> <!ELEMENT thiselement    (contentmodel)                   >
> <!ATTLIST thiselement
> 
>           -- id          Unique identifier for element  --
>              id          ID                #IMPLIED
> 
>           -- role        One of:
>                          good  looks like Toshiro Mifune
>                          bad   looks like Clint Eastwood
>                          ugly  looks like Paula Jones  --
>              role        (good|bad|ugly)   "good"
> 
>           -- whatever    I don't care; put something
>                          here                           --
>              whatever    CDATA             #REQUIRED      >
> 
> Which was:
>    1)  Easier to scan for elements (at least to my eye)

Yes, if you want to read the attribute name and 
comment at the same time eg, learning the DTD.  
Still, this style always confuses me 
because I am looking for the productions 
and they are scattered in a lot of text. I agree 
your layout is the most scannable.

>    2)  Put the attribute comment directly with its
>        attribute, very nice if there are more than 10
>        attributes.

Yes.  Particularly when cutting and pasting in the DTD 
documentation.  In the production DTD, the fact that 
there are that many attributes means the file gets very 
big.  So, sure in the archival/authoritative DTD, but 
in production code, it's a lot of stuff.  Having it 
in a separate file makes it easier to manage for reuse.

>    3)  Easier (for me the weak programmer) to write a
>        hack that would pull the attrbute and its
>        comment together.

Yes.

> We lost this battle in the "ease of parsing" wars.
> No biggie, the new way works fine.

Yes.

Hope all is well with you!

len

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/
To (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)