Thanks for the review! --Paul Hoffman
On Apr 3, 2014, at 4:05 PM, Ben Campbell <[email protected]> wrote: > I am the assigned Gen-ART reviewer for this draft. For background on > Gen-ART, please see the FAQ at > > <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>. > > Please resolve these comments along with any other comments > you may receive. > > Document: draft-hoffman-xml2rfc-04 > Reviewer: Ben Campbell > Review Date: 2014-04-03 > IETF LC End Date: Not in last call > > Note: This is an early review, rather than the usual Gen-ART review at IETF > last call. The Gen-ART processes do not precisely apply. > > Summary: This draft is on the right track. I have a few comments and > questions that may or may not be worth consideration. > > *** Major Issues: *** > > None Yay! > *** Minor issues: *** > > -- General: > > There are a few "to do" items left in the draft. (Not surprising for an > early review.) Whacking away at them, yes. > -- Section 1, paragraph 2: > > I find it confusing that we have two drafts in parallel, one for V2 that is > obsoleted by this draft, and this draft for V3. With this draft copying much > of V2 forward, which is authoritative? Both. the v2 draft is authoritative for that version of the format (which is still in use); this draft will be definitive for v3 when v3 is implemented. Unlike a regular protocol, this format is not going to be immediately implemented when the draft goes to the RFC Editor. > -- 1.1, entry for <tident> > > THANK YOU!!!! I think faking indented text using the <list> work around was > one of the most annoying things about previous versions. Hrm; I'm not used to seeing that in GenArt reviews. :-) And, to be fair, lots of the new features have been suggested by many people on the RFC Editor's design team and in the bigger community. > --2.2: > > Can I have more than one of any given address sub-element? If so, how should > it render? Yep; unclear. There are a lot of things in this draft (and the in the v2 draft) where the rendering is undefined. We may or may not clarify those in the doc before we are finished; if not, it will be up to the programmers. > -- 2.5.3: > > If "height" ought to be avoided, should it be deprecated? Yes; fixed. > Also, what's the unit for height? Deprecated. :-) > (Same questions apply to "width") Same answer. Also fixed. > -- 2.5.5: > > An example of how to use inlined graphics files might be helpful. Will do, once we have a more stable definition of what SVG will be allowed. (You just added another open "to do" item.) > -- 2.5.6: > > A generic "code" value might be useful. This would fall under "ascii-art". > Otherwise, how do you expect these to be used? Syntax highlighting? Probably not for the non-canonical versions, but some people will want to post-process the canonical XML to add syntax highlight, validation, and so on. The text above it says "A processor might add type-specific formatting to artwork with the preferred values in the non-canonical output formats." > I assume the processor should never actually try to interpret code based on > the "type" attribute. (Are there security considerations there?) Correct, and yes. Added a security consideration about this. > -- 2.7: > > It seems like <b> (and also <i>) is just as much format dependent as things > like <width>. Wouldn't something like <em> be more useful for this purpose, > where you have an abstract concept of emphasis that can be rendered > differently for different formats? In some senses, yes, but given that we know the main expected types of non-canonical output (HTML, PDF, EPUB), they all handle bold and italic and fixed-width fonts just fine. There are plenty of people who would think that "emphasis" means bold, and plenty who would think it means "italic". > This seems like a place where our use cases are different than those for > HTML, where markup is usually rendered by browsers that have similar font > display capabilities. No, our use cases very much align with HTML here: that's a design choice. > In particular, what happens to <b>text<.b> when rendered into ASCII text? Nothing. Just like today, there is a lot of formatting that is lost in the text output. > -- 2.9: > > Why does the "cite" attribute have different requirements than, say, xref? In > particular, why wouldn't I want to cite a reference in the current doc, > rather than a URL? It can do both: the URL can be a fragment that points to a reference in the current doc. > -- 2.9.1: > > How would one reference an auto generated anchor identifier? If it doesn't > exist until processing time...? Correct, so you can't. You can only use "target" attributes to named anchors. > -- 2.15.2 > > What is the format for Month? Must you write it out? Abbreviate? Number?) Whoops, that one was unclear. Fixed. (Will require the English spelling.) > -- 2.26 > > An example might be helpful Good call; fixed. > --2.33.2 > > Is it possible to continue numbering from a previous list? Not directly. > -- 2.43.5 > > The text says that "iprExtract" is used to reference a specific section.... > Can you elaborate on how? E.g. do you reference an anchor? Are you allowed to > have more than one "as-is" section? Good question, and one I don't know the answer to right now. Another to-do listed. > -- 2.44.2: > > Why are numberless subsections disallowed? If it was a sub-section, the heading could easily be mistaken for free text. > It's pretty common to see documents that have non-numbered sub-heads inside > numbered sections. Those are probably "notes" and such, not real sections. Do you see a need for these? It's certainly possible to have them, but they seem more confusing than necessary to me. > -- 2.44.5: > > The default for the TOC attribute is "default"? Does that mean the actual > meaning of "default" is controlled elsewhere? > > Also, is there a way to limit the depth for ToCs? Yes to both: they were added to <rfc> in the -05. > -- 2.45 (and subsections) > > Should the seriesInfo "name" values match the table from 2.40? That's a good question, and is in play right now. > -- 2.54: > > Is it possible to select the symbol to be used for an unordered list? Nope. That's a conscious design choice: the lists will look similar across RFCs. > -- 5, security considerations > > I wonder if the possibility of executable content existing in an RFC or draft > is worth mention here? For an extreme example, see RFC6716, Appendix A. But > more realistically, 2.5.5 mentions the possibility of in-lined binary > content, and 2.5.6 allows the identification of code in a way that a naive > processor implementation might take as an invitation to interpret said code. Yup, and (as above) I added a paragraph about this. > Also, does the need for a processor to potentially render binary content in > general (in-lined or otherwise) expand the attack surface over that for > previous versions of XML2RFC? Not in any way I can think of. > *** Nits/editorial comments: *** > > -- 1, paragraph 3: > > I find the paragraph a little confusing. Saying certain elements will not be > used in text generation may be a bit overstated, in that the generation of > metadata may well become part of the process of generating the final text. It > might be more correct to say "may not affect the rendering of the final > text". (And in the case of the example of index generation, I see that the > text of this draft has an imbedded index--so I assume the related elements > _were_ used in generating the text. Fixed. > -- 1.1: > > Is the section on changes from V2 intended to remain in the final RFC? Often > such sections are removed, but there is info in here (esp 1.1.1) that may be > useful in the long run. Yes, it is intended to stay. It might move to an appendix, but it is important to list. > -- 1.1, bulleted list of changes: > > I find the past tense a bit confusing. I assume that the list represents > incremental differences from V2, but the past tense made me wonder if it was > meant as ways that V2 is different than V3. (I suspect the author thought in > terms of "changes that were made as we wrote this text", but I think the > reader will think in terms of "changes this text makes to V2". Good call. Fixed. > -- List entry for "postalline" > > I had to stare at "postalline" for a while before I realized it meant "postal > line" and not some sort of material, perhaps made from recycled mail (poh- > stah-LEEN ). The point being that I find combined words like this very hard > to read without some sort of separator or mixed case. Please consider that > when creating new elements with compound word names. (e.g. <postal-line> or > <postalLine> are much easier to read, for me at least.) The latter. Fixed. > -- 1.1, 2nd paragraph, "less importantly" > > I suggest dropping the value judgement. (I would personally find the lack of > offline operation more of an issue than a need to change my anchor names, but > that's just me.) Fixed. > -- 2.5.8: > > Please expand CJK on first use. Eeeps. Of course. > -- 2.40, series value table: > > The value for 3GPP is "TBD". Is there an expectation that the RFC will have > something real there? Yes. More research is obviously needed. > -- 2.48, Content Model: > > It might be worth marking deprecated elements. Otherwise a reader may not > follow the xref to discover a legal child element is deprecated. These are automatically generated, and marking the deprecated ones is probably really really hard. We thought of this and punted. > -- 2.58: > > It might be helpful to mention what happens if an <xref> is _not_ empty. Marked as another to-do. Again: thanks! The things above marked as fixed or to-do will appear in the next draft. _______________________________________________ Gen-art mailing list [email protected] https://www.ietf.org/mailman/listinfo/gen-art
