Re: [dita] DTD Formatting: Attribute list Alignment

[Don Day <dond@us.ibm.com>]

If it weren't for incidentals and adornments, what would we ever talk about, Debbie? "...and we note our place with bookmarkers that measure what we've lost."

I happen to like the examples below, if only because the current DITA DTDs are already coded more or less to this standard, so its a shorter path to completion. A worthy goal, perhaps even an overriding one if I get volunteered for the job.

One issue I've had in a few places is how to handle the enumerated values that push the default values past the right alignment rule. Not a big problem in most places, but DITA's @importance is one good example.

The specialization design pattern for DTDs allows splitting attribute declarations, so you can define the element-specific attributes locally to the element declarations, and congregate the common and class definitions separately -- see the divided attlists in /dtd/task.mod, for example. In a fully resolved view of a DTD, such organizational artifacts would be lost, therefore I think it is also a goal to try to use the organization of the content to emphasize these otherwise subtle design characteristics where possible.

Some DTD parsers don't like the split (accumulative) attlists allowed by XML... WordPerfect in particular still emits an SGML message about the construct. But IMO this is not worth backing down from the learning opportunity (and easier maintenance) that the design pattern approach affords.

Regards,
--
Don Day <dond@us.ibm.com>
Chair, OASIS DITA Technical Committee
IBM Lead DITA Architect
11501 Burnet Rd., MS 9037D018, Austin TX 78758
Ph. 512-838-8550 (T/L 678-8550)

"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
Deborah Aleyne Lapeyre <dalapeyre@mulberrytech.com>

Deborah Aleyne Lapeyre <dalapeyre@mulberrytech.com>

08/24/2004 02:37 PM

To	<dita@lists.oasis-open.org>
cc
Subject	[dita] DTD Formatting: Attribute list Alignment

1) Aren't style discussion wonderful? Sometimes substance is easier!

2) I think the most important thing in formatting an attribute
list, especially for a beginner, is to make the three parts very clear:

Every attribute needs a name, a Declared Value, and a Default Value.
The style should make it obvious which is which and what they are,
that's why I like a 3 column format, separated from the beginning
of the ATTLIST:

<!ELEMENT foo (#PCDATA)
>
<!ATTLIST  foo
              att1    CDATA            #REQUIRED
              att2    (a | b | c)       #IMPLIED
              att3    IDREFS           #REQUIRED
              att4    CDATA         #FIXED "A12"


 - first tell me whose attributes
 - then one item  per line with all three parts showing,
   and clearly differentiated

Or maybe

<!ATTLIST  foo
              att1    CDATA          #REQUIRED
              att2    (a | b | c)    #IMPLIED
              att3    IDREFS         #REQUIRED
              att4    CDATA          #FIXED "A12"

3) If anyone wants to see samples of real, large element models
and ATTLISTs, go to:

   http://dtd.nlm.nih.gov/tag-library/1.1/index.html

And click on any of the DTD modules. Get a feel for a one particular
style of a real Tag Library and see if you like it or hate it.

--dal
--
======================================================================
Deborah Aleyne Lapeyre               mailto:dalapeyre@mulberrytech.com
Mulberry Technologies, Inc.                http://www.mulberrytech.com
17 West Jefferson Street                    Direct Phone: 301/315-9633
Suite 207                                          Phone: 301/315-9631
Rockville, MD  20850                                 Fax: 301/315-8285
----------------------------------------------------------------------
  Mulberry Technologies: A Consultancy Specializing in XML and SGML
======================================================================