Early Review of draft-reschke-xml2rfc-08
review-reschke-xml2rfc-08-genart-early-davies-2014-07-25-00

This is an early review of draft-reschke-xml2rfc-09.txt by Elwyn Davies as 
a gen-art reviewer as requested by Heather Flanagan (RFC Series Editor).  
Apologies for the tardy delivery.

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.

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.
   
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? 

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

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

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

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

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). 

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.

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.

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

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

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

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

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

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

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!)

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]. 

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 
verbatim.  Personally I think this would be much cleaner if the vague text was 
the content of the <date> element. 

s2.13.2: Month names can be abbreviated also.

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).

s2.18.3: OK, we know the parent element is deprecated, but should be recommend 
using MIME types here?
  
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. 

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")?

s2.22, para 2: s/workaround/a workaround/

s2.22.1:  Are there lexical constraints on the counter value?  I would suggest 
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. 

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

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

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

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

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.

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

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

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

s2.41.2: What happens if width is omitted?  Is there any requirement to 
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.

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.