Re: draft-fielding-uri-rfc2396bis-03 (section 5)

These are my comments about section 5:

Title: I was expecting to find the keyword 'relative' somewhere
        in the section title.

5.1 "(Section 4.4" -> "(Section 4.4)" (I think Ian already mentioned this)

5.1 "The base URI of a document can be established in one of four ways,
     listed below in order of precedence." ->
     "The base URI of a document can be established in one of four ways,
      discussed in order of precedence in Subsections 5.1.1 to 5.1.4."
     [main point is to refer to subsections; 'listed' gives the impression
      of a bulletted list or so]

5.1, ascii art: "(5.1.4) Default Base URI is application-dependent" ->
      "(5.1.4) Default Base URI (application-dependent)"
      [grammatically align the descriptions to have them all be noun phrases.
       Also, removed the period after "none)".]

5.1.1 Give an example or two here: HTML <base>, XML xml:base.

5.1.1 "It is assumed that user
    agents manipulating such media types will be able to obtain the
    appropriate syntax from that media type's specification."
    'obtain syntax' sounds strange. I would write 'obtain (or extract)
    the base URI from the syntax' or 'analyse the syntax' or 'understand
    the syntax' or so.

5.1.1 The last paragraph in my understanding seems to belong into
    5.1.2., because it's about base in the encapsulation, not in the
    entity itself.

5.1.2 Again, an example would be helpful.

5.1.3 "If no base URI is embedded and the document is not encapsulated
    within some other entity (e.g., the top level of a composite entity),"
    -> "If no base URI is embedded and the document is not encapsulated
    within some other entity (e.g., it is the top level of a composite entity),
    [otherwise referent is unclear]

5.1.4 "in above" -> "above"

5.2 Obtaining the Referenced URI: Again, I expected this title to contain
    the word 'relative'.

5.2, first paragraph: This first 'describes an example' and 'is intended to
    provide', but then ends with 'must match'. Please be less fuzzy at
    the start, e.g.:

       This section describes an algorithm for resolving URI
    references relative to a given base URI.  The algorithm
    provides a definitive result that can be used to test
    the output of other implementations.  Implementation of the algorithm
    itself is not required, but the result given by an implementation
    must match the result that would be given by this algorithm.

5.2, second and third paragraph, including part with '--':
    the second paragraph splits the base, the third paragraph splits
    the reference. Exactly (or almost?) the same thing is done in each case,
    but the descriptions are completely different. Please align/
    extract commonalities.

5.2, 'non-strict parser' get mentioned first in a comment.
    please say somewhere at the start of 5. or 5.2 that there
    are strict and non-strict implementanions/parsers/what not.

5.2, main algorithm: please move up
          T.query = R.query;
          T.authority = Base.authority;
          T.scheme = Base.scheme;
          T.fragment = R.fragment;
      to come before the if/else rather than after. This will make
      it much easier to read the algorithm, because it is easy to
      see that there is nothing anymore after an else, but it is
      more difficult to find which endif; is the corresponding one.

5.2 "The pseudocode above refers to a merge routine":
     please quote 'merge' or otherwise clarify that 'merge' is the
     name of the routine.

5.2 "merging a relative-path reference with the path of the base URI":
     The sequence of parameters in 'merge' is the other way round.

5.2 unnumbered bullet list just after the above paragraph:
     it seems that most of this can be expressed in the same
     pseudocode language (except the last bullet). I think this
     would be better.

5.2 "Return a string consisting of the reference's path component
       appended to all but the last segment of the base URI's path (i.e.,
       any characters after the right-most "/" in the base URI path are
       excluded)."
     Move the 'are excluded' to just after i.e., changing to 'exclude'
     or 'excluding'. This makes it much clearer that the referent of
     the 'i.e.' is the returned string, and not the last segment.

5.2, remove_dot_segments, point 5. and 6.
     There seem to be so many different cases, and I was thinking
     how to describe this more easily. An alternative I have come
     up with is:
     a) If the buffer ends with "..", where ".." is a complete path segment,
        append a "/".
     b) If the buffer does not start with a "/", prefix a "/", and
        remember that you have done so.
     c) Remove all occurrences of "<segment>/../", doing
        the leftmost possible replacement first, where <segment> is
        a complete path segment [no need to say so for
        the ".." part, that's fixed between two "/" anyway].
        Note that <segment> may be empty, or may be "..".
     d) Remove any initial "/.."
     e) Remove the initial slash if you added one in step b).

     Here is why this may be better:
     - mostly simpler steps
     - not doing almost the same thing two (or four) times
     - a) and b) establish invariant to have slashes on both sides
     - 'in order from left to right' may be misunderstood to not
       back up. i.e. in /a/b/../../, the leftmost is /b/../, so
       we get /a/../. Then /a/../ matches /<segment>/../, but
       it's difficult to say that this is to the right of /b/../.
     - says explicitly that <segment> can be .. (hope I got this
       right).
     Just a try, judge for yourself.


5.3 I expected this to be part of 5.2. 5.2 says that we obtain the
     referenced URI. So it should at least point to 5.3 as part of
     the algorithm.

5.4 Is an empty reference abnormal? I thought rdf:about=""
     was a pretty common idiom.


Rest (section 2, appendices) to follow.


Regards,   Martin.

At 19:07 03/06/06 -0700, Roy T. Fielding wrote:

>I have just submitted draft 03, which can also be obtained via
>the issues list at
>
>    http://www.apache.org/~fielding/uri/rev-2002/issues.html
>
>Please note that all issues have been fixed or closed.  If you'd
>like to raise a new issue or reopen an old one, please do so
>within the next two weeks.
>
>
>Cheers,
>
>Roy T. Fielding, Chief Scientist, Day Software
>                  2 Corporate Plaza, Suite 150
>                  Newport Beach, CA 92660-7929   fax:+1.949.644.5064
>                  (roy.fielding@day.com) <http://www.day.com/>
>
>                  Co-founder, The Apache Software Foundation
>                  (fielding@apache.org)  <http://www.apache.org/>

Received on Friday, 20 June 2003 17:38:26 UTC