OASIS Darwin Information Typing Architecture (DITA) TC

Thoughts about naming conventions

  • 1.  Thoughts about naming conventions

    Posted 09-06-2005 05:45
     MHonArc v2.5.0b2 -->
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    

    dita message

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


    Subject: Thoughts about naming conventions


    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.
    
    Naming Conventions
    
    
    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?
    
    
    Regards,
    --
    Don Day
    Chair, OASIS DITA Technical Committee
    IBM Lead DITA Architect
    Email: dond@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
    
    


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