Re: Comments within DTDs (Teapot not tempest)
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@i... Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ To (un)subscribe, mailto:majordomo@i... the following message; (un)subscribe xml-dev To subscribe to the digests, mailto:majordomo@i... the following message; subscribe xml-dev-digest List coordinator, Henry Rzepa (mailto:rzepa@i...)
PURCHASE STYLUS STUDIO ONLINE TODAY!
Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!
Download The World's Best XML IDE!
Accelerate XML development with our award-winning XML IDE - Download a free trial today!
Subscribe in XML format