[rfc-i] Gen-art early review of draft-reschke-xml2rfc-09

[julian.reschke at gmx.de (Julian Reschke)]

Elwyn,

thanks for the feedback. See 
<http://greenbytes.de/tech/webdav/draft-reschke-xml2rfc-latest-from-previous.diff.html> 
for my current changes.

More comments inline:


On 2014-07-09 17:56, Elwyn Davies wrote:
> ...
> Front matter:
> I suggest that the material in Appendix D and the last sentence in para 2 of
> s1 is not appropriate for the final version of this document as it may not
> match exactly what is stated in the introduction of the v3 draft and in any
> case introduces a double maintenance problem.  I suggest that it would be
> appropriate to put a note in the front matter pointing out the status of
> this document and the likelihood of its being superseded by version 3.
> The note to be removed on final publication of the RFC.

I added a note to Appendix D that it should be removed before 
publication as RFC. I didn't get what else you think needs to be changed.

> s1, para 2:
> OLD
>     It obsoletes the original version ("v1") [RFC2629], which contained
>     the original language definition, and which was subsequently extended
>     ("v2", [V1rev]).  Furthermore, it discusses potential extensions in a
>     future revision ("v3").
> NEW:
>     It obsoletes the initial version ("v1") [RFC2629], which contained
>     the original language definition, and which was subsequently extended
>     ("v1rev", [V1rev]), which has been the vocabulary understood by
>     version 1 of the xml2rfc processor (written in TCL).  The v2 vocabulary
>     is a superset of the v1 vocabulary with relatively minor improvements
>     and is understood by version 2 of the xml2rfc processor (written in
>     Python) which superseded the version 1 processor in 2014.

I changed the text to say:

"It obsoletes the original version ("v1") [RFC2629], which contained the 
original language definition, and which was subsequently extended. Many 
of the changes leading to version 2 have been described in "Writing I-Ds 
and RFCs using XML (revised)" ([V1rev]), but that document has not been 
updated since 2008."

> s1/s8.1:
> Quoting from s3 of RFC 3023:
>     An XML document labeled as text/xml or application/xml might contain
>     namespace declarations, stylesheet-linking processing instructions
>     (PIs), schema information, or other declarations that might be used
>     to suggest how the document is to be processed.  For example, a
>     document might have the XHTML namespace and a reference to a CSS
>     stylesheet.  Such a document might be handled by applications that
>     would use this information to dispatch the document for appropriate
>     processing.
> Should there be a similar statement for application/xml+rfc to make it
> crystal clear that such things must be accepted by a processor that
> deals with this MIME type?

I don't think so. Have you ever seen a statement like that in another 
"+xml" media type registration?

(which reminds me that 3023 just got obsoleted)


> s2.4, para 2: s/fullname/full name/

Yes.

> s2.5: It would be worth adding in "message flow diagrams" to the list.

Yes.

> s2.5: 'URI' is one of the 'almost well-known abbreviations' (marked
> with * in list) and the abbreviations page recommends expanding it.

Done, but I really think it should be on the white list.

> s2.5.1, para 1: s/left/left justified/, s/right/right justified/

Yes.

> s2.5.1/s2.5.7: Ought to explain that width of artwork if using inline
> ASCII art (or anything else that is just ASCII text) is length of longest
> line including leading white space but not including trailing whitespace
> (not sure this is what the answer ought to be - it is could be useful to
> use trailing white space but clearly this is difficult to keep intact
> across edits).

I'm note even sure that this is true; this requires some testing.

> s2.5.5: It occurred to me while considering the discussion of handling artwork
> graphics items as separate creations (rather than inlining them, which is frankly
> unpleasant with most tools) that provided the src URIs are allowed to be
> relative URIs with no scheme part (which they ought to be, c.f., the path-noscheme
> production in Section 4.2 of RFC 3986) and tools can handle referencing relative
> to either the filesystem file path or the URI of the main document then this
> would make local and over the web access from a single source relatively [sic]
> straightforward.  So (a) is it worth mentioning that path-noscheme URIs are an
> option and (b) does the current processor do anything like this... I haven't
> checked yet

a) yes; I changed this to say "URI reference" (with a ref to the actual 
spec)

b) yes, these work.

> s2.5/s2.5.6: Need to know what the well-known abbreviations are.  Either put
> them in the list at s2.5 or give a web ref.

There is no common list.

> s2.6: Is the use of just an organization allowed for document authors as well
> as references?  I thought it wasn't.

I think it is. I recall seeing RSE and/or IAB documents using this.

> s2.6.2: 'should be provided'?  Is it reproduced verbatim or reformatted?

You can't count on reformatting.

> s2.6.2/s2.6.4:  For the limited set of people that only have one name, can
> <initials> be omitted?

Yes. It's optional.

> s2.6.4: Should add same note as s2.6.2: '(used on the front page and in references).'

Yes.

> s2.7: Worth saying the <sections> are labelled as appendices.

"In <back>, <section> elements indicate appendices."

> s2.8: Are we allowing <vspace>, <spanx> and <*ref> in <c> after the discussions?

This specification describes what v2 is.

> s2.11: Probably useful to be explicit that this now MAY be the ISO 3166
> country code but can be usual ASCII representation of the country name since
> this is explicitly altered from v1rev and v1 where it is 'SHOULD'.  (OK, it's
> in the changes but people may not check that - I know I have been slavishly
> following RFC 2629 and successor!)

Hmm.

> s2.12.1: anchor description missing.

?

> s2.13, para 4: s/Note that in this case/Also in the boilerplate case/ [not
> clear what 'this' refers to].

I think it's pretty clear.

> s2.13: [Aside: The text on vague names needs to be copied into the v3
> specification.]  Should also state that in the vague names case the processor is
> expected to produce "<day value> <month value> <year value>" with the spaces
> omitted if adjacent value is empty (or some such) and the supplied values used

I'd rather not go into the details of formatting.

> verbatim.  Personally I think this would be much cleaner if the vague text was
> the content of the <date> element.

Maybe.

> s2.13.2: Month names can be abbreviated also.

Only in some processors as side effect of what date parsing library they 
happen to use.

> s2.15: The existing processors have some rather garbled features for turning
> <erefs> into extra refs and adding an extra References section.  I think this
> was quite a good idea and ought to be properly specified/implemented (it is
> broken at the moment).

That's specific to certain formatters.

That being said, numbering the references instead of inlining them seems 
to be a bad idea to me (it's a totally unneeded indirection).

> s2.18.3: OK, we know the parent element is deprecated, but should be recommend
> using MIME types here?

Why would we?

> s2.19: Given that we are happy to have empty <date> elements implying today's
> date at generation of output rendering, it strikes me that <date> could be made
> optional.

Yes. In v3.

> s2.21: The use of "single keyword" may be slightly confusing.  Is it allowed to
> contain white space (i.e., is it really a "keyphrase")?

Good catch, but I'm not sure about the term - after all, it's not 
supposed to be phrase either.

> s2.22, para 2: s/workaround/a workaround/
>
> s2.22.1:  Are there lexical constraints on the counter value?  I would suggest

I'm not aware of any.

> no whitespace, letters and numbers only (maybe even is this does not matter!)
> Clarify that lists using the same counter name will provide the continuation
> and it is not possible to reset the counter value.  Incremented at each <t>
> in the enclosed list.

Added.

> s2.22.2: Needs to say that 'hangIndent' must be a positive decimal number (or,
> equivalently, only consist of numeric characters).

changed "characters" to "number of characters".

> s2.25: Should mention the use of organization as an alternative in
> <reference> if <name> is empty/missing.

That would just repeat prose present on the parent element.

> s2.27: Possibly mention that processors are expected to maintain the supplied
> order of the content to cater for vagaries of country specific addressing.

No, they are not supposed to do that. That might have been the original 
intent, but it was never implemented.

> ss2.28/2.29: Are <vspace>, <spanx> and <*ref> now allowed in <postamble> and
> <preamble>?

What do you mean by "now"? An no, <vspace> is not.

> s2.30.1: Should also note that the anchor may also be used to provide a sort
> order for the references if the appropriate PI is used.

Done.

> s2.34.1/s.2.38.1/s2.39.2: Need the additional restriction to USASCII caveat.

That caveat only applies to anchors that might be copied into the text.

> s2.38.2: Should specify either ignored and/or causes error if used outside
> relevant list types.

Not sure. If we want to be that pedantic, there are probably many other 
attributes where that kind of discussion is needed.

> s2.41: Are <vspace> and <spanx> allowed now?

This specification describes what v2 is.

> s2.41.2: What happens if width is omitted?  Is there any requirement to

Then the formatter picks the width.

> use no more than 100% of the space. Seems a bit silly to allow 0% but no big
> deal. I guess 100% is fine for a single column table (handy way to get a
> centred list such as you might get with a 'procedure' specification).
>
> Appendix B:  Whilst this is AFAICS an accurate view of the changes from v1,
> this is frankly not of much practical use since the vast majority of
> documents have been written to the v1rev vocabulary.   It would be more
> practically helpful to flag up what has changed since v1rev either instead or
> as well.

We are obsoleting RFC 2629, so we should say what changed.

And yes, there may be changes from the abandoned 2008 draft, but I don't 
think we need to explain that here.

> Appendix D:  Please delete this.  It has to be kept in step with the changes
> listed in draft-hoffman-xml2rfc and describing future potential upgrades is
> not very useful when the actual upgrades are already in a draft.  If this
> document becomes an RFC before the v3 document is finalized then there is
> a significant chance that it will be inaccurate and of little value.

Marked as "to be deleted before publication as RFC".

Best regards, Julian