[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: [ubl-ndrsc] Comments on Markup Naming positions
Following are my comments on the Markup Naming positions proposed in Mark's
12 November NDR document draft.
Eve
----------------------------------------------------------------------
----------------------------------------------------------------------
General organizational comments:
Even if we use line numbering, having the lists be numbered as well would
be helpful for referencing.
It would be nice to have Markup Naming be its own top-level section, to
avoid the heavy nesting and because it's a nice clear dividing line, with
few hard decisions about what goes here vs. elsewhere. Also, some of the
names that I use below for the various markup-naming topics might make good
subsection titles, or at least "handles" for list items.
This is how the TOC could look if they're made into subsections:
n Markup Naming
n.1 Name Structure
n.1.1 English in names
n.1.2 Naming patterns
n.1.3 Abbreviations
n.1.4 Element name length
n.2 Name Content
n.2.1 Parts of speech
n.2.2 Singular and plural names
n.2.3 Naming strategy
n.2.4 Redundancy in names
n.2.5 Document type naming
----------------------------------------------------------------------
*All UBL type, element, and attribute names must Oxford English:
(Section 5.1, list item #3)
I think this should be moved into 5.2.1, Markup Structure.
I suppose I'm fine with this recommendation, if this is what everybody else
chooses. Does OED mean British-style spellings for things like colo[u]r?
----------------------------------------------------------------------
*The name of the UBL message set must be consistent with its definition:
(Section 5.1, list item #6)
This should probably be moved into 5.2.1.2, Markup Content. The reason is
that a "UBL message set" is a UBL "document type" (right?), and I think the
root element should be the same as the name we give the document type.
That said, I'm not sure what this means. It does sound like a generally
good prescription, but perhaps too vague to help, unless some examples and
non-examples are supplied. It is reminiscent of the item in 5.2.2 that
talks about "meaningful aggregate names", and it seems to address the Ed.
Note in the intro to Section 5.2.1 that talks about "naming convention for
root element...".
----------------------------------------------------------------------
*Group naming:
(Section 5.2.1 intro)
When you say "Groups" here, are you referring to model group and attribute
groups? At first blush, I wonder if we can simply use the same rules as
for types.
----------------------------------------------------------------------
UCC and LCC:
(Section 5.2.1.1 items #1, 2, and 3)
(BTW, can the lists be numbered for easy reference? This will be helpful
even if we use line-numbering.)
I imagine that any other choice here would be sacrilege. :-) If we cover
model and attribute groups, they should be listed in item #1.
----------------------------------------------------------------------
Naming patterns:
(would go in Section 5.2.1.1 somewhere)
Some schemas use suffixes to indicate the sort of thing being named, such
as AssertionType and IDSimpleType; this is something to consider. Also, we
should guide the naming of elements/types where there is a 1:1 relationship
(that is, where an anonymous type would theoretically serve just as
well). Do we want to say that the element and type names match? That they
match except the type name has "Type" on the end?
My recommendation: I'm not thrilled about the verbosity that "Type" adds,
but it can be marginally useful when you're reading a schema, just because
you can't get confused about what sort of thing (or what sort of
thing-reference) you're looking at. I say we use it. We don't really need
a "SimpleType" variant, but for consistency, we should probably use "Group"
as a suffix (if we have any groups) too.
----------------------------------------------------------------------
Acronyms and abbreviations:
(Section 5.2.1.1 items #4 and 5)
Item #4 seems fine, other than the fact that XML is an initialism, not an
acronym. :-) Item #5 seems to contract #4, and I think it should be removed.
----------------------------------------------------------------------
Punctuation:
(Section 5.2.1.1 item #6)
Could this simply be combined with items #1, 2, and 3? The prohibition
seems to go hand in hand with the camel case.
----------------------------------------------------------------------
Element name length:
(Section 5.2.1.1 item #7)
I have a feeling that a limit of 30 characters may be hard to achieve, if
we use the "build up the name" technique in Section 5.2.1.2. Is 30 a hard
limit? What happens if a name goes over -- does a human make a judgment
call about designing a shorter name? Will customizers still suffer if they
have to add "My-" to a name for some reason? Do attribute names not
present any of the same problems as element names? I would prefer it if we
could avoid dealing with hard limits.
Finally, the hard-limit information (if there is any) belongs here, but the
reference to limiting verbosity in general is wholly a matter for the
Markup Semantics section and the reference should be removed here.
----------------------------------------------------------------------
----------------------------------------------------------------------
Uniqueness:
(Section 5.2.1.2 item #1)
This would seem to prohibit local elements, which can have the same name
but be qualified by being defined in different complex types. And if the
entire set of element, atribute, type, group, etc. names is unique, then we
definitely *will* need suffixes or some other scheme to disambiguate them,
since without a guideline, many type names will mirror their associated
element names.
----------------------------------------------------------------------
Naming strategy:
(Section 5.2.1.2 items #2, 3, 4, 6, 7, 8, 9, 10 and table)
This got some debate on the last call: dictionary names or intuitive
"common usage" names? I would love to see a bunch of examples using both
styles. I'm inclined towards intuitive names, though, because I can barely
wend my way through the description provided here (even with the
definitions for Object Class, Property Term, etc. provided). Also, Arofan
brought up the benefits of using "non-hierarchical" short names: they can
be reused in more places. (Though I suppose this gets into the local vs.
global issue again...)
----------------------------------------------------------------------
Redundancy in names:
(Section 5.2.1.2 item #5)
The mention of conciseness isn't too helpful, it seems to me, given the
rigid way several terms have to be sewn together in the EDR
methodology. More helpful is the rule about removing redundancy of
consecutive words. I also wonder if this is related to item #8, about
syntactic and/or semantic redundancy in Representation Terms and Property
Terms; should it be subsumed there?
----------------------------------------------------------------------
Singular vs. plural:
(Section 5.2.1.2 item #11)
Makes sense to me. If elements that contain repeated items are always
given a suffix of "Detail" (or whatever), it might be nice to mention or
refer to that here.
----------------------------------------------------------------------
Non-letter characters:
(Section 5.2.1.2 item #12)
Does this mean that if you're using a language other than English for your
tags, it's okay to use funky things like combining accents and numbers
because that's what's used in that language? If so, this conflicts with
the OED rule. If not, this seems more like it should go with the "don't
use periods and hyphens" rule. Somehow it doesn't seem to belong in the
Markup Content section no matter what.
----------------------------------------------------------------------
Parts of speech:
(Section 5.2.1.2 item #13)
This rule seems fine.
----------------------------------------------------------------------
----------------------------------------------------------------------
--
Eve Maler +1 781 442 3190
Sun Microsystems XML Technology Center eve.maler @ sun.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC