Subject: [edu-team] "Tools for Creating I-Ds" tutorial at IETF 87

From: Alice Russo <[email-masked]>
Date: Thu, 11 Jul 2013 13:28:47 -0400

Edu team & Tools team,

Please drop me a line if you have suggestions for improving the "Tools for Creating I-Ds" tutorial for IETF 87. The updated slides are here: 
  http://www.rfc-editor.org/rfc-editor/tools_87.pdf

The focus is on the most commonly used tools for document creation: xml2rfc and NroffEdit. Additions for IETF 87 include listing lyx2rfc and pandoc2rfc among the options. Thanks to the creators of those tools for providing input.

Thanks,
Alice

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 11 Jul 2013 12:25:13 -0700

> The focus is on the most commonly used tools for document creation: xml2rfc and NroffEdit. Additions for IETF 87 include listing lyx2rfc and pandoc2rfc among the options. Thanks to the creators of…

This may seem like a wrench, but: Why is the RFC Editor staff teaching this class at an IETF meeting? While we appreciate that y'all have volunteered to do it (and have done it for years), it still might be giving the wrong signals.

Having this taught by RFC Editor staff feels to me like a policy line being crossed. Someone from the IETF Stream should be teaching it, and it should be taught not in light of "here are the tools that you need to get something to the RFC Editor" but "here's what you need to create I-Ds that might never become RFCs".

Case in point: I doubt that you teach much about "you can just cobble an I-D together with any old text editor as long as it follows these rules", but that is definitely allowed for submission of drafts in the IETF Stream.

Someone more closely affiliated with the IETF Stream would probably be a much more appropriate teacher and organizer of this.

--Paul Hoffman

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 11 Jul 2013 13:01:51 -0700

On Jul 11, 2013, at 12:41 PM, Nico Williams <[email-masked]> wrote:

> On Thu, Jul 11, 2013 at 2:25 PM, Paul Hoffman <[email-masked]> wrote:
> It's an IETF meeting, yes, not an RFC-Editor-and-customers meeting.
> But there's no such thing as the latter, and this is the closest it
> gets.  Ditto IANA.  People who have no IETF business but want to
> physically meet either the RFC-Editor or the IANA basically have to
> attend an IETF meeting (and they probably don't even need to pay
> attendance fees, if they'd not be attending any IETF WG, BoF, plenary,
> or other meetings).

Quite true. If the topic of the tutorial was "how to do final preparation on an Internet Draft that is ready to go to the RFC Editor", that would be just fine. But Alice clearly didn't say that. (And that's good, because such a tutorial is probably not at all needed.)

> Sorry, what policy might that be?  

That Internet Drafts exist in the IETF to foster discussion, not to necessarily become RFCs.

> The RFC-editor held a meeting at
> Atlanta on updating its RFC formatting and such.  If that was OK (and
> I recall you were in the room, and I don't recall you objecting to the
> meeting), why wouldn't a class given by the RFC-Editor be OK?

The purpose of the rfcform BoF was for the RFC Editor to receive input from the community; the purpose of these tutorials is to give information to people new to preparing Internet Drafts. Certainly you can see a difference there, yes?

> The individual submission track (and, really, all the streams) should
> be mentioned, I agree.

Note that the class is not at all about tracks: it's about tools.

> Can you expand as to why that would be so?

See above. 

> I happen to think that the RFC-Editor staff -- who deal on a daily
> basis with both, Internet-Drafts (e.g., as they arrive on their
> queues) and RFC formatting, and who consume a variety of input formats
> and use a variety of tools while doing providing their editing
> function -- should logically be the best first choice for giving such
> a class (individual members of the staff might not be, but logically
> they all should be).  Others outside the RFC-Editor staff might make
> great second and third choices for for giving such a class, and I
> would not object to them doing so.

The RFC Staff are supposed to consume Internet Drafts in any agreed-to format, even if the authors didn't use a tool. The RSE is supposed to be formalizing the input formats to the RFC Editor, but hasn't done that (and earlier RFC Editors were told not to try, but to allow XML).

Clearly, we want the RFC Editor to get Internet Drafts in a format that will make their process the most accurate and, following that, easiest. But the way to do that is by having the input formats stated by the RSE and the Streams, not by having classes about tools that may or may not emit the long term input format.

--Paul Hoffman

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 11 Jul 2013 22:03:51 +0200

On 2013-07-11 21:38 Bob Hinden said the following:
> Paul,
> 
> On Jul 11, 2013, at 12:25 PM, Paul Hoffman <[email-masked]>
> wrote:
> 
>>> Please drop me a line if you have suggestions for improving the
>>> "Tools for Creating I-Ds" tutorial for IETF 87. The updated
>>> slides are here: 
>>> The focus is on the most commonly used tools for document
>>> creation: xml2rfc and NroffEdit. Additions for IETF 87 include
>>> listing lyx2rfc and pandoc2rfc among the options. Thanks to the
>>> creators of those tools for providing input.
>> 
>> This may seem like a wrench, but: Why is the RFC Editor staff
>> teaching this class at an IETF meeting? While we appreciate that
>> y'all have volunteered to do it (and have done it for years), it
>> still might be giving the wrong signals.
> 
> 
> I don't see any issue with someone from the RFC editor staff teaching
> a tutorial on I-Ds.  I think the main criteria for someone teaching
> this tutorial is that they have a good understanding of the material.
> I also note that IDs are used by all of the streams so this isn't
> specific to the IETF stream.  I don't see any policy issue here.

Well said.  I agree.

	Henrik

> Bob
> 
>> 
>> Having this taught by RFC Editor staff feels to me like a policy
>> line being crossed. Someone from the IETF Stream should be teaching
>> it, and it should be taught not in light of "here are the tools
>> that you need to get something to the RFC Editor" but "here's what
>> you need to create I-Ds that might never become RFCs".
>> 
>> Case in point: I doubt that you teach much about "you can just
>> cobble an I-D together with any old text editor as long as it
>> follows these rules", but that is definitely allowed for submission
>> of drafts in the IETF Stream.
>> 
>> Someone more closely affiliated with the IETF Stream would probably
>> be a much more appropriate teacher and organizer of this.
>> 
>> --Paul Hoffman _______________________________________________ 
>> Tools-discuss mailing list [email-masked] 
>> https://www.ietf.org/mailman/listinfo/tools-discuss
> 
> _______________________________________________ Tools-discuss mailing
> list [email-masked] 
> https://www.ietf.org/mailman/listinfo/tools-discuss
>

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 12 Jul 2013 08:45:03 +1200

> On 2013-07-11 21:38 Bob Hinden said the following:

...
>> specific to the IETF stream.  I don't see any policy issue here.

I agree too. It is of course important that people understand the streams
and their purpose, but the tools to produce a throw-away I-D that never
advances are the same ones used for an I-D that becomes, say, an IRTF-stream
RFC, or perhaps RFC1796bis.

   Brian

---

From: Bob Hinden <[email-masked]>
Date: Thu, 11 Jul 2013 12:38:49 -0700

Paul,

> This may seem like a wrench, but: Why is the RFC Editor staff teaching this class at an IETF meeting? While we appreciate that y'all have volunteered to do it (and have done it for years), it still…

I don't see any issue with someone from the RFC editor staff teaching a tutorial on I-Ds.  I think the main criteria for someone teaching this tutorial is that they have a good understanding of the material.  I also note that IDs are used by all of the streams so this isn't specific to the IETF stream.  I don't see any policy issue here.

Bob

> _______________________________________________

---

From: Elwyn Davies <[email-masked]>
Date: Thu, 11 Jul 2013 19:25:25 +0100

Hi, Alice.

As you may remember I am mainly an xml2rfc man... :-)

But I have had to get up to speed with NroffEdit in the last couple of
weeks and have discovered a couple of minor 'gotchas' that might be
worth pointing out as they aren't on the web site (yet):
- It works just fine on Linux BUT ONLY if the jar is started in the
NroffEdit installation directory.  If starting from a Gnome menu you
need to create a script that makes the current directory right before
issuing "java -jar NroffEdit.jar". If not, 
(1) it runs like a superannuated tortoise, and
(2) the spellchecker doesn't work.
- On all platforms you need to periodically download the most recent RFC
bibliography file for use with the 'Managed References' - There's a menu
option at File->Check for Updates that does this (you mention this but
its worth emphasizing that you need to do it as soon as you install and
then periodically if you are using recent RFCs).  I *think* but am not
absolutely sure that you need to restart NroffEdit after downloading.

As regards Bill Fenner's xml2rfc-xxe add-on, there is a problem with
licensing of the current XMLmind editor personal edition - it is no
longer free (and I am not clear if the add-on works with it anyway - I
thought I tried out the most recent version a while back and couldn't
get it to work).  However, I am happily using version 4.6.1 of the
editor which seems to work just fine still and was distributed for free.
If anybody is desperate to use this I have a copy of the installation
zip here...  Personally I'd be lost without it.  It makes doing xml2rfc
really easy, and I couldn't find the old version on the XMLmind website.

A couple of minor points on xml2rfc that might be worth noting as people
get them wrong quite often:
- <list> must be inside <t> - and this applies recursively thus:
   <section>
      <t>
        Text absmasd
        <list>
          <t>
          List item
          </t>
          <t>
          Another list item
             <list>
                <t>
                  Inner list item
                  etc...
                </t>
             </list>
          </t>
        </list>
      </t>
    </section>
- <figure> must be outside <t> thus:
    <section>
      <t>
      </t>
      <figure>
      </figure>
      <t>
      </t>
    </section>
(Note: xml2rfc-xxe has am automated reminder and fix for the list case -
used it yesterday! - hadn't seen it before. Nice!  Thanks Bill.)

Might be worth mentioning 'Magic Incantations:
- <?rfc needLines="23" ?>, and
- the use of <vspace="0"/> and <vspace="1"/> especially in lists 
if there is time.

/Elwyn

---

From: Nico Williams <[email-masked]>
Date: Thu, 11 Jul 2013 14:41:49 -0500

> Having this taught by RFC Editor staff feels to me like a policy line being crossed. Someone from the IETF Stream should be teaching it, and it should be taught not in light of "here are the tools…

Sorry, what policy might that be?  The RFC-editor held a meeting at
Atlanta on updating its RFC formatting and such.  If that was OK (and
I recall you were in the room, and I don't recall you objecting to the
meeting), why wouldn't a class given by the RFC-Editor be OK?

Nico
--

---

From: Nico Williams <[email-masked]>
Date: Thu, 11 Jul 2013 15:31:11 -0500

> Quite true. If the topic of the tutorial was "how to do final preparation on an Internet Draft that is ready to go to the RFC Editor", that would be just fine. But Alice clearly didn't say that. (A…

See below.

> That Internet Drafts exist in the IETF to foster discussion, not to necessarily become RFCs.

Response #1: Er, the same is true of RFCs.  Requests for Comments.  If
Alice were talking only about formatting STDs then you'd have a bit of
a case.

Response #2: That's nice, but we do also produce work that is
submitted to the RFC-Editor queue.  And it just oh-so happens to be
the case that currently we use roughly the same input formats for both
purposes: formatting I-Ds for discussion and and RFCs, and,
critically, the RFC-Editor accepts I-D input formats.  This makes
Alice's tutorial of extreme interest to the IETF community.  If that's
not sufficient to convince you then nothing else can.

> The purpose of the rfcform BoF was for the RFC Editor to receive input from the community; the purpose of these tutorials is to give information to people new to preparing Internet Drafts. Certainl…

We also got input from the RFC-Editor.  That road went both ways.

> Note that the class is not at all about tracks: it's about tools.

Which... we need.  And which we want newbies to know about and, if
those tools are useful to them (they should be), use them.

>> Can you expand as to why that would be so?

I saw nothing convincing.

> Clearly, we want the RFC Editor to get Internet Drafts in a format that will make their process the most accurate and, following that, easiest. But the way to do that is by having the input formats…

<sarc>
Why, they shouldn't even come to our meetings.  Ditto IANA.  Who needs
to hear from them?!  They'll be sucking invaluable time and energy.
Sort of like this thread.
</sarc>

Have the last word please.

Nico
--

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 12 Jul 2013 08:46:28 -0700

> This may seem like a wrench, but: Why is the RFC Editor staff teaching this class at an IETF meeting? While we appreciate that y'all have volunteered to do it (and have done it for years), it still…

Arguably, the RFC Editor has more experience with these tools than most;
we certainly see a wider variety of what mistakes people make with these
tools!  On top of that, we have a great deal of experience in staying
polite and professional and helping people whose skills are in a
different area.  As such, we're probably most qualified to teach this
particular workshop.

> Having this taught by RFC Editor staff feels to me like a policy line being crossed. Someone from the IETF Stream should be teaching it, and it should be taught not in light of "here are the tools…

As others suggested, I don't think this is a policy line at all.  For
what its worth, I know there will be people attending this workshop
purely to learn how to submit I-D to the ISE.  This particular session
is not really just for the IETF, and there is a long history of other
streams meeting as part of the IETF meeting.

> Case in point: I doubt that you teach much about "you can just cobble an I-D together with any old text editor as long as it follows these rules", but that is definitely allowed for submission of d…

Well, we will always accept plain text submissions, but I don't think we
need to teach people how to use vi or emacs at this point.  xml2rfc,
however, is a bit more tricky.

> Someone more closely affiliated with the IETF Stream would probably be a much more appropriate teacher and organizer of this.

I understand the point you are making and I am glad you raised the
question, but I think the current model is working and does not
introduce additional confusion.

-Heather