OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Thoughts about naming conventions


We were supposed to have been discussing this issue the past week.

Here are some thoughts about naming convention that were behind the
HyTime-inspired names in IBMIDDoc, and which I've annotated to fit what
seems to be the current spirit of discussion about the topic.
Historically, some of the conventions (like #2) are broken by others (the
HTML borrowing issue implied by #6, or the tag-stuffing full name that was
shortened to choptionhd). I think the issue is whether we can revise theswe
into rules that will guide the future of pre-2.0 element/attribute
additions.

Naming Conventions


During the course of defining the architectural forms language, we must
generate many names for elements, attributes, attribute values, notations
and other items. This section contains the conventions that we will use to
create these names.
1.    All names are valid English words or the concatenation of multiple
English words.
2.    Names will not be truncated or abbreviated. There is no practical
restriction (that we would care to exceed, anyway) in XML.  There is no
practical requirement to restrict names to eight characters.
3.    If multiple words are used, they will be typed whereever used with
the initial letter of each word capitalized. If the name is a single
English word, its initial letter will be capitalized. (Note--this is the
CamelCase rule, which DITA explicitly eschewed originally--all DITA element
names are lowercase, even compound names.)
4.    All names will be nouns with multiple word names consisting of a noun
and one or more adjectives. Multiple word names will be presented in the
order normally used in spoken English. Where this is ambiguous, the order
adjective - noun will be used.
5.    There are some abbreviations that are so universal that it would be
more confusing to not use them than to follow the above convention, ID is
one that comes to mind. These will be presented using all uppercase
letters. (Note--regarding ID, this is not the case for DITA. Only in
discourse have we used ID to signify the attribute "id", which
unfortunately will always conjure Freudian connections, no matter how we
capitalize it.)
6.    Where appropriate, names used within standards like HyTime, Davenport
and important public applications will be used to avoid excessive remapping
and to emphasize their synergy with the standard or application. One
example of this is HyTime's use of the name LINKEND rather than REFID.
(Note--to some extent, this was the reasoning applied to the import of
certain HTML and IBMIDDoc names into DITA.)

In addition, we need to account for the two cases of hyphen usage
(draft-comment and required-cleanup, both "hidden" elements relative to the
discourse in which they appear).  I think it is enough to eschew the
practice from now on and declare that rule 7 for new element names is "no
hyphenation, no underscores."

So, rules 3 and 5 appear to be not representative of DITA today.  What else
have I overlooked?


Regards,
--
Don Day
Chair, OASIS DITA Technical Committee
IBM Lead DITA Architect
Email: dond@us.ibm.com
11501 Burnet Rd. MS9033E015, Austin TX 78758
Phone: +1 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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]