|Subject:||Thoughts about naming conventions|
|From:||Don Day (do...@us.ibm.com)|
|Date:||Sep 5, 2005 10:44:49 pm|
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.
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?
-- Don Day Chair, OASIS DITA Technical Committee IBM Lead DITA Architect Email: do...@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