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: naming convention last call?


Esteemed DITA TC:

We need to close on the naming issue and move on.

I'd propose:


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


To

dita@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.


Hoping that's useful,


Erik Hennum
ehennum@us.ibm.com


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