|Subject:||naming convention last call?|
|From:||Erik Hennum (ehen...@us.ibm.com)|
|Date:||Sep 10, 2005 7:55:11 am|
Esteemed DITA TC:
We need to close on the naming issue and move on.
o In the DITA 1.1 timeframe, because DITA 1.0 has no mixed case names, the naming convention for new names is to separate the words of a compound with a hyphen (as with "related-links"). Thus, the <data> element will have an "about-type" attribute. This convention is not applied to existing DITA 1.0 names.
Creators of new specializations modules may want to adopt the camelCase naming convention now so as to have consistency with the expected long-term DITA naming convention.
Does that work?
Erik Hennum ehen...@us.ibm.com
----- Forwarded by Erik Hennum/Oakland/IBM on 09/10/2005 07:31 AM -----
Erik Hennum/Oakland/IBM To di...@lists.oasis-open.org cc Subject naming convention rollup
Hi, Esteemed Committee:
As required by a To-Do, this note summarizes the pros and cons that have been brought forward on the naming issue:
* Existing DITA has no consistent naming convention for compounds.
ol = initials of compound propdesc = abbreviated compound choicetable = lower-case compound related-links = hyphenated compound
One common naming convention that existing DITA doesn't exhibit is camelCase.
* A consistent naming convention has value because people who know the compound words don't have to look up the name.
* As an extensible vocabulary, DITA has a greater need for more compound names than has fixed vocabularies and has a greater need for self-documenting names.
* Programming languages such as Java have had good success in using camelCase for large vocabularies requiring self-documenting names.
* Many data-oriented vocabularies have adopted a camelCase naming convention (especially CamelCase for elements and camelCase for attributes) as well as at least one extensible document-oriented vocabulary (TEI with camelCase for both).
* Some (such as Wikipedia) claim that camelCase is easier to understand than all lower-case and easier to type than hyphenated compounds.
* Long names are more difficult to type in a text editor and could bulk larger than the textual content within the elements.
* An underscore can be easily confused with a space in a URI presented with an underline and thus shouldn't be a compound convention.
* DITA has already adopted camelCase for filenames.
* We won't modify existing names in DITA 1.1
* We want to minimize migration and maximize clarity and ease of use for new names added by DITA 1.1
* Namespaces could affect the issue if we support namespaces and, in effect, the namespace prefix becomes the first word of the compound.
* Element and attribute name aliasing could affect the issue by allowing us to deprecate existing names or to support both camelCase and some typical abbreviations.
* If DITA assimilates an existing vocabulary as a specialization, we probably can't change the naming conventions of that vocabulary.