Editorial comments on DPF

Hi

this is the first of four related messages:
   - editorial comments
   - substantive comments
   - RDF related comments
   - brief biographical introduction



This message contains comments on

http://www.w3.org/TR/2004/WD-DPF-20041122/

This set of comments are editorial in nature.
(Note that the last might be regarded as substantive by some)
Unhelpfully there is some overlap with my substantive comments.



e1:
section 2
Use of word Properties in list

The word 'Properties' is used in two different ways, in
a confusing manner in the numbered list.
In point 1 it is used to refer to the property as a relationship
between things, an abstraction. In points 3 and 6 what seems to be
being discussed is property values (in particular instances)

Suggest s/Properties/Property values/ in points 3. and 6.


e2:
section 2 point 2
identifiers vs expressions

In the last sentence of this point the word identifier is used to
refer to a name with no punctuation. In the examples in the first
sentence expressions such as "a.b.c[2]" are misreferred to as
identifiers (I see three identifiers in that expression).
Suggest s/ such as/, for example,/


e3:
section 2 and throughout, particularly first para 4.1
'hierarchy' of properties, or tree of property/value pairs

I found the term hierarchy confusing; perhaps being an RDF-head,
I thought you might have been talking about sub-properties etc.
Suggest using a word like tree instead, and at some point
clarifying that we are talking about a tree of property/value
pairs.

e4:
section 2 point 1
names are in namespaces, not anything else

Namespace in XML says:

"An XML namespace is a collection of names"

To suggest that other things are in namespaces is a mistake.
Suggest that the wording of point 1 start something like:

"Properties are named.
The name of a property is in an XML namespace."


e5:
section 4.1
Figure 1 confusing

I got really quite confused by figure 1 and the text above it.
I only really made sense of it when I had read further in the document.
In part this was that I hadn't work out what you meant by hierarchy
by this point.
In part this is that the label "DPF Component" seems to describe
the type of that rectangle, whereas the labels "Property [A-C1-6]"
seem to be being used to name the relationship between the labelled
rectangle and the rectangle above.
The lines are also working quite hard, and looking at the picture
again I think perhaps too hard. (The lines are representing
both the parent/child relationship and the sibling relationships)

I guess I'm really looking for substantive changes here, so
my suggested fix is in a different comment (mainly comment r2)



e6:
section 4.1.4
Wording last para

I found the wording here confusing, I started looking for more
information elsewhere (e.g. in the appendixes) concerning these
examples.

Suggest:
old
[[
Informative examples are given to
explain how this works, for example
]]
new
[[
Some informative examples are:
]]



e7:
section 4.2
Exception text muddle

There seems to have been a number of editorial errors
with the text defining the conditions leading to exceptions.

A glaring copy/paste one is last sentence of 4.2.5 the property
in question has no previous parent, this text seems to have been
miscopied from 4.2.4

A large number of exceptions have no text describing when they
happen in a particular method.

I suggest significant effort to clarify here. I would like to see,
under each method, a table, with one column with the exception,
and a second with a description of the exception condition as it
occurs in this method.

While such text would be boring (both to write and to read) and
would duplicate (to some extent) section 4.8, I think it would
be helpful and clear.

I also have a number of substantive issues (s8, s9, s10, s14, s15)
to do with exceptions, which I believe stem partly from the lack
of clarity of the current text leading to mistakes.

e8:
section 4.2.4
last sentence misses cases

Are there not four cases which can raise a
NO_MODIFICATIONS_ALLOWED_ERR?
   newChild is read only
   oldChild is read only
   this property is read only
   the previous parent of oldChild is read only
the text only identifies two of these.

e9:
section 4.2.7
Figure 2 first box labelled GPS not in namespace

Suggest replacing "GPS" with "EG:GPS"
All property names are in namespaces.


e10:
section 4.3 and 4.8
INDEX_SIZE_ERR or INVALID_ACCESS_ERR

Do these two errors mean the same thing?
(Sorry again overlap with substantive comment, s14 concerning text of 4.3)

e11:
section 7.
Date in ECMASCript ref

Please include the date for this reference.
It would have been helpful. (I know it's only
a click away, but we were looking at a printed
version...)

e12:
Section 4.1.3

This does not specify anything, but reads more as
an apology by the working group for not having provided
a solution for access rights and validation.
As such, it seems inappropriate in a recommendation, and should
simply be deleted (the whole section).



Jeremy Carroll

Received on Monday, 10 January 2005 18:39:22 UTC