MHonArc v2.5.0b2 -->
dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: naming convention last call?
Esteemed DITA TC:
We need to close on the naming issue and move on.
I'd propose:
- 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.
- In the DITA 2.0 timeframe, the expected naming convention for compounds is to follow TEI and use camelCase (lower case initial). (Upper case initial seems more suited to data formats because the markup isn't part of a discourse flow but rather a structure delimiter.) This convention is applied to both existing and future compound names (including "choiceTable" and "relatedLinks").
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
ehennum@us.ibm.com
----- Forwarded by Erik Hennum/Oakland/IBM on 09/10/2005 07:31 AM -----
Erik Hennum/Oakland/IBM
08/30/2005 07:42 AM
|
|
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.
Hoping that's useful,
Erik Hennum
ehennum@us.ibm.com
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]