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