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.
_______________________________________________
Gen-art mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/gen-art
