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

[paul.hoffman at vpnc.org (Paul Hoffman)]

On 27 Apr 2016, at 15:23, Joe Hildebrand (jhildebr) wrote:

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

Fixed.

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

It would be grand if someone wrote a "how to create new documents using 
the different tools available" document. Of course, that should probably 
not be an RFC, but a living web page.

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

Agree on "has passed".

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

Agree on removing the sentence. There are lots of "good ideas for the 
RPC" that we don't list, and I'm not sure why this one is so important.

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

I have changed "is correct" to "has valid values". Am happy to take more 
suggestions on this section.

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

Done.

>> Do we need to expand or reference ?DTD??
>
> OK.

Expanded.

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

Done.

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

Using XML tags as nouns makes the document more readable in some places.

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

Fixed.

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

+1

--Paul Hoffman