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: RE: [dita] naming convention rollup

An alternative would be to use a two-level convention such as the one discussed for file names.
camelCase would be used to form compounds in which the ingredients being combined are all contributing to a single type of information. Hyphenation would be used when some ingredients make a distinctive contribution.
For example,
Some existing usage might be impossible to change. For example,
A two-level convention would be horrible if it were difficult to remember when hyphenation is appropriate.
However, some distinctive punctuation might be required if we make a set of element names in which the name of the module containing the element is explicitly part of the name. That set could be in addition to the existing names, duplicating them, or instead of the existing names, forcing migration.
Best wishes,
-----Original Message-----
From: Erik Hennum [mailto:ehennum@us.ibm.com]
Sent: Tuesday, August 30, 2005 10:42 AM
To: dita@lists.oasis-open.org
Subject: [dita] 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

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