Robert Sayre wrote:
Andreas Sewe <[EMAIL PROTECTED]> wrote:
But does this sound like an improvement to you, too?
Sort of. I did a deep dive on this, and I think it's really huge.
It's had little community input, it's not at all clear that the
approach is correct, and it's not clear that clients will implement
it, as the space is so new.
I am inclined to agree with your diagnosis that the spec is quite
heavyweight for what looks seemingly like a rather straight-forward
task, namely ordering entries. And the draft has indeed gained some
weight after I joined James as a co-author. :-(
This is mostly due to the fact that we tried to cover one use case,
which seemed to us like the archetypical case of rankings: grades. So we
had a look at the different grading schemes out there at schools and
universities worldwide (thanks to wikipedia) and tried to find a common
pattern. And this is, unfortunately, not easy (as everyone will know who
has spend a term abroad ;-).
However, I do understand you want to ship something, and it's nice
that you want to document it openly. So, Information or Experimental
seems like a good fit here.
That would be fine with me. A don't know about James, though.
Even with the alternative intro you've supplied, it's not clear what
problem this document solves. It seems to claim almost unlimited
powers. :) There are quite a few sections that seem to have a very
low return to me. I think you need to cut, and cut a lot. I think the
value evaporates very quickly outside of the 'ranking' element.
You mean r:rank, right? Well, the purpose of r:scheme (and its child
elements) is to describe the ordered set from which r:rank's values a
picked. Think of it as a datatype definition geared specifically at
describing those sets of numbers commonly encountered in grading schemes.
3. Ranking Domains and Schemes
A "Ranking Domain" is a uniquely identifiable logical set of
entries with associated numeric ranking values.
I can parse the sentence, but I don't understand what this means.
A "Ranking Scheme" identifies specific rules on how to interpret
the numeric ranking values within one or more "Ranking Domains".
Same here. I suggest avoiding the new terminiology. A more
plain-spoken, concrete, operational approach would work better.
James has made a change to that respect. The draft now stars an Overview
section instead of the more formal language above -- and it is still
shorter than the previous one. :-)
3.1. The 'r:scheme' Element
Ranking Schemes are defined using the r:scheme element. A scheme
includes zero or more r:value and r:range elements that define the
set of possible values for the Ranking Scheme.
rankingScheme = element r:scheme { atomCommonAttributes, attribute
name { IRI }?, attribute label { text }?, attribute significance {
'ascending' | 'descending' }?, ( value | range )* }
The "name" attribute provides a universally unique identifier for
the scheme in the form of an absolute IRI.
This conflicts with the atom:author field. Why not @id, @domain, etc.
Well, I am not sure what you mean here, but as for @domain you have to
realize that a single scheme can be used to rank entries within more
than one Ranking Domain (e.g.., within several feeds).
Changing @name to @id might cause confusion, since attributes called
"id" commonly contain NCNames, not IRIs. I suggest to James using an
r:id child element of r:scheme, instead, to mimic atom:id, but somehow
he doesn't like the idea. But maybe you can come up with a better name
for @name (no pun intended).
The "significance" attribute indicates how implementations are to
interpret the significance of a numeric ranking value. A value of
"descending" indicates that the significance of the rank decreases
as the numeric ranking value increases. A value of "ascending"
indicates that the significance of the rank increases as the
numeric ranking value increases. If not specified, the
significance is considered to be "ascending".
@significance is also confusing. Suggest changing to @order or
similar.
I don't think it is the term "significance" that is confusing but the
way the above paragraph is phrased. I could probably be simplified.
(IMHO, "significance" is a more precise term than "order", since the
latter refers to the order of *entries* as presented to the user,
whereas the former refers to the order of *rank values* within the
scheme/set.)
An Atom feed element MAY contain any number of r:scheme elements.
A feed MUST NOT contain more than one r:scheme element with the
same name.
Well, you have all of these child elements that can change the effect
of the element, so why would you want to ban this behavior?
I don't understand the above. :-( Can you please clarify your objection.
Thanks.
The "scale" attribute on both the value and range elements
specifies the total number of decimal digits to the right of the
decimal indicator in the value of the numeric ranking value. The
scale is
I don't understand this.
expressed as a non-negative integer. If not specified, the value
is considered to be zero. Ranking Schemes that are based on
fractional numeric ranking values SHOULD specify a scale. Numeric
ranking values that use a larger scale than defined for the scheme
MUST be rounded to the nearest in-scale value (e.g. with scale=2,
the rank 0.123 is rounded down to 0.12, the rank 0.125 is rounded
up to 0.13.)
I don't see the usefulness of @scale either. I probably need to argue
some more with James about it. ;-)
..
The "step" attribute specifies the minimum significant increment
for
...
The "origin" attribute specifies the base from which steps in a
range
...
Ranges and values defined within a Scheme MUST NOT overlap one
another.
This section is really, really dense. I have a hard time
understanding any of it. Perhaps some Excel-like ASCII table
illustrations would help.
I will try to prepare an alternative section on r:rank and r:value later
today and post it to atom-syntax to see whether it is easier to understand.
rankingValue = element r:rank {
atomCommonAttributes,
attribute domain { IRI }?,
attribute scheme { IRI }?,
attribute label { text }?,
{ decimal }
}
Given this definition, it's not clear to me why the feed-level stuff
is necessary. Is the idea that clients have to know that to edit?
Well, for one thing you do not want specify whether the significance of
a ranking is "ascending" or "descending" on each and every element.
And what r:value and r:range are supposed to provide is some kind of
datatype definition for r:rank's value, so that an application might for
example adjust its "Filter" GUI accordingly.
Ranking Domains group entries with attached numeric ranking values
to logical sets. Ranking Domains are uniquely identified by IRIs.
"Ranking Domains" come back to haunt us. I'm lost here.
:-)
The notion of Ranking Domains is going to be much simplified in the next
draft.
Feeds MAY contain ranked entries that have no specified scheme. In
such cases the Default Ranking Scheme should be applied.
This seems like overkill.
Why? It is just a convenient shorthand that takes almost no time to
implement.
The Default Ranking Scheme assumes ascending significance and a
single range with no minimum or maximum value, no significant step,
unspecified scale, and an origin of 0.
Oh wait, is this the introduction of this term? It doesn't seem
useful to me. I suggest text along the lines of "If there is no
scheme specified, [explain default processing]." No terminology
necessary.
Personally I find it easier to think about default data instead of
default processing; that's a "Show me your flowcharts [...]. Show me
your tables [...]" thing.
The authors gratefully acknowledge the feedback from the Atom
Publishing working group during the development of this
specification.
You should also acknowledge verbatim copies of text from RFC4287.
Done
Best wishes,
Andreas Sewe
