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 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 are labelled as appendices. s2.8: Are we allowing , and <*ref> in 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 " " 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 element. s2.13.2: Month names can be abbreviated also. s2.15: The existing processors have some rather garbled features for turning 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 elements implying today's date at generation of output rendering, it strikes me that 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 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 if 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 , and <*ref> now allowed in and ? 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 and 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.