[rfc-i] comments on draft-iab-rfcv3-preptool-01

Joe Hildebrand (jhildebr) jhildebr at cisco.com
Wed Apr 27 15:23:55 PDT 2016


On 4/27/16, 1:52 PM, "rfc-interest on behalf of Howard, Lee" <rfc-interest-bounces at rfc-editor.org on behalf of lee.howard at twcable.com> wrote:



>Instead of “blessed” can we use the language from the framework draft: "the authorized, recognized, accepted, and  archived version of the document"

That seems like a reasonable request.

>Internet-draft submission takes XML and runs equivalent of xml2i-d.  
>I'm sure this is controversial, but I think this is insufficient: we need an authoring tool, or at least some way to generate a draft that has a lower barrier to entry than "learn
> our XML." If I've missed earlier conversations on this and there's a plan, I'd like to see it in the document (or in a different document, since this one is about the preptool, but I would welcome a pointer here).

There may be lots of authoring tools.  All of which will need to generate xml2rfcv3, rather than text, if you want to use them to submit v3 docs.  For example, Carsten's markdown tool at http://rfc.space/ is a nice starting point.  Carsten is working on a v3 output from his tooling, I believe.  Miek Gieben is working on a formatter written in Go (https://github.com/miekg/mmark).  Richard Barnes has a web editor for markdown that's pretty sweet (https://draftr-js.github.io/).

Several of us have written different build environments for Makefile (https://github.com/martinthomson/i-d-template), Gulp (https://github.com/hildjj/generator-rfc), etc, to deal with the parts of the problem that are not just file format.


Some people might want to spruce up the Henning's LaTeX formatter (http://www.cs.columbia.edu/irt/software/l2x/) to output v3 instead of nroff.

The reason there's no pointer to a single tool is that there are likely to be lots of them, and that's ok.

>< “When the    document is done with AUTH48 review”> “When the document has passed AUTH48 review”Otherwise, it’s unclear and could mean “When the document is created/prepare/processed with AUTH48”Did you "do it with AUTH48"?

I don't object to this change.  However, I don't want to be too proscriptive on the RPC at this point.  They're going to figure out a process that works for them after the first several RFCs have been published like this.  We'll write down the as-built process in the -bis version.

>“It is probably a good idea for the RPC    to keep a copy of the input XML file from the various steps of the    RFC production process.”If it’s a good idea, let’s tell them to do it. However, the only reason to do so is to research previous iterations to find changes that should have occurred, which might mean that the canonical XML version can be undermined. It’s up to us to decide whether it’s a good idea.

An example of an approach that would meet this suggestion would be setting up a git repo for each draft they work on.  That would likely be really useful, for the same reason using version control tools are good for programmers.

However, we don't really like to tell the RPC precisely what to do, because then we're on the hook for a *lot* of detail.  I would be ok with removing this sentence if it is helpful.

>“if that attribute    or element already exists, the prep tool will check that the    attribute or element is correct” How does it know whether it’s correct?

For example, if processing xref/@derivedContent, the derivedContent attribute that the tool generates may be different from the derivedContent attribute in the input file.  This condition is currently specified to overwrite the incorrect derivedContent in the output, issuing a warning.

This entire section could use a little bit of editorial help.

>5, #1 I feel like “entityrefs” and “includes” need to be in italics or have some punctuation around them. 

Heh.  Too bad we don't have v3 yet. :)

"entityrefs" should be spelled out as "entity references", and then it won't look so bad.

>Do we need to expand or reference “DTD”?

OK.

>#2 Do we have to make <x:include> both a verb and a noun in the same sentence? That sounds hard for even a native English speaker to parse. “<x:include>d XML may include more <x:include>s”

Yes, this could be clearer.


>#3 < idnits> the “idnits” tool“stops if there was an error.” 

OK.

>This could be clearer: don’t stop upon encountering the first error, but if there are any errors, do not go on to the next step. So: “The prep tool displays all warnings and errors; it does not then proceed if there are any errors.”

We have actually removed this step.  It didn't make sense to render to text mode at this point in order to run idnits.  The as-built tooling will likely need to check more of the things that idnits currently checks.

>#4-6 I think each of these is referring to our specific XML schema, and should include a link to draft-iab-xml2rfc.#8 I had to look up “prepTime” in xml2rfc, which refers to rfc3339 to define format. 

We don't have <relref> in v2, which is what we're using for this document.  I wonder if we could add a terminology section that says that all of the XML referred to in this doc is from v3?

>Four-digit years, UTC, okay, but with UTC offset? 

>Punctuation? 24 hour or 12 hour? Etc.

We decided on 3339 date-time (which is always 24h), always 0 offset, represented as "Z".  That will be in the next version of the v3 draft.


>18. And again, is it proper to use XML tags as nouns?

Those can be de-crufted.

>42. The note pointing at a github tool is true, but will we publish this as an RFC with a URL reference?

Yeah, it's time to remove that.  We *don't* want to specify the pretty-printing rules in this doc.  It was useful in the early stages to prove that a finite amount of code could produce adequate results, which is why I wrote dentin.

>6. “Would be useful” and “might be useful” are good observations, but not publishable. 

I would be ok with removing section 6 at this point, and potentially moving that text to the RFP that we'll let out for building the preptool.

Thanks for the great review!

-- 
Joe Hildebrand


More information about the rfc-interest mailing list