Subject: [bmwg] Internet Draft Review and Preparation in BMWG

From: Al Morton <[email-masked]>
Date: Mon, 19 Sep 2011 09:47:56 -0400

BMWG,

While looking for something else, I stumbled on
http://tools.ietf.org/tools/idcomments/
a comment extraction tool.

Unfortunately, I found that this is not an operational tool
at the moment.  It requires the rfcdiff tool, and
rfcdiff is no longer available as a stand-alone tool.
It is still available as a web-service, of course:
http://tools.ietf.org/rfcdiff

I was planning to ask that bmwg'ers try this when preparing comments
for a couple of months, then consider whether it would become a
recommended practice in bmwg, but we'll put that thought on the shelf.
I'll pursue the current status of idcomments tool in my copious
spare time...

As we finish-up a few WG documents, I suspect that many of
our remaining drafts are based on XML formatting.
I have toyed with the possibility to make XML drafts
a recommended practice in our group, too, and have helped
people install XXE (XMLMind XML Editor) with Bill Fenner's plug-in.
Then I saw this, a new nroff WYSIWYG editing tool:
http://aaa-sec.com/nroffedit/
It converts txt to nroff, too.  Nice if you know nroff.

My informal attempts to move us in an improved direction continue,
in any case. It's just a matter of time till the boiler-plate
changes again.

Comments on these topics are welcome,
Al
bmwg chair

---

From: Benoit Claise <[email-masked]>
Date: Tue, 20 Sep 2011 23:24:32 +0200

Dear all,
> It converts txt to nroff, too.  Nice if you know nroff.
I recently used http://aaa-sec.com/nroffedit/ for the first recently.
I wanted to create a new draft out of an existing RFC, to progress it 
along the standards track. The RFC-editor didn't save my word version 
years ago, so they gave me an nroff version. Even without experience 
with nroff, this tool makes nroff very easy.

Regards, Benoit.
> _______________________________________________
> bmwg mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/bmwg

---

From: Al Morton <[email-masked]>
Date: Tue, 20 Sep 2011 17:34:42 -0400

At 05:24 PM 9/20/2011, Benoit Claise wrote:
>I wanted to create a new draft out of an existing RFC, to progress 
>it along the standards track. The RFC-editor didn't save my word 
>version years ago, so they gave me an nroff version. Even without 
>experience with nroff, this tool makes nroff very easy.

Thanks for sharing your experiences, Benoit.

I suppose that since the RFC Editor org does not use MSword files,
they don't store it, either. It's a *word* to the wise.

Al

---

From: Kenneth Green <[email-masked]>
Date: Tue, 20 Sep 2011 17:39:06 -0700

Interesting tools that certainly make the editing of IDs a lot easier than trying the native text format.

Nroffedit
+ small to download, easy to install, easy to use
+ text_to_nroff feature is very useful indeed
+ learning nroff by example seems simply enough (at least enough to get the job done)
- does not generate alternate output formats such as html or pdf
? The online version of xml2rfc already supports an nroff output format so conversion xml->nroff is readily available. I wonder if a feature or tool could be added to Nroffedit to generate XML output and so allow maximum flexibility across source formats and output formats (since xml2rtf supports output as html and pdf which are very useful and much more readable and navigable alternatives to the native RFC text format)?

XMLmind XML Editor
- bigger download, easy to install.
+ Found " Bill Fenner plug-in" here: http://code.google.com/p/xml2rfc-xxe/
+ XML tag format is easy to learn by example and supports tables (didn't see that in the nroff examples)
- tool is much harder to learn/get started than with nroffedit
- Need to download and figure out where to install 'xml2rfc' if you don't want to use the online version
+ Can generate various useful additional output formats including html and pdf

My understanding is that the IETF only ever holds the text files so it is up to the author to hold/archive the primary source file. If that is correct then I guess we can each choose our favourite format/tool combination. Certainly with just a little comparative experimentation the Nroffedit solution appears much simpler and easier to use and its bidirectional feature is a valuable asset.

Regards,
Kenneth

Kenneth Green
Solution Architect
Ixia

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Al Morton
Sent: Monday, 19 September 2011 11:48 PM
To: [email-masked]
Subject: [bmwg] Internet Draft Review and Preparation in BMWG

BMWG,

While looking for something else, I stumbled on http://tools.ietf.org/tools/idcomments/
a comment extraction tool.

Unfortunately, I found that this is not an operational tool at the moment.  It requires the rfcdiff tool, and rfcdiff is no longer available as a stand-alone tool.
It is still available as a web-service, of course:
http://tools.ietf.org/rfcdiff

I was planning to ask that bmwg'ers try this when preparing comments for a couple of months, then consider whether it would become a recommended practice in bmwg, but we'll put that thought on the shelf.
I'll pursue the current status of idcomments tool in my copious spare time...

As we finish-up a few WG documents, I suspect that many of our remaining drafts are based on XML formatting.
I have toyed with the possibility to make XML drafts a recommended practice in our group, too, and have helped people install XXE (XMLMind XML Editor) with Bill Fenner's plug-in.
Then I saw this, a new nroff WYSIWYG editing tool:
http://aaa-sec.com/nroffedit/
It converts txt to nroff, too.  Nice if you know nroff.

My informal attempts to move us in an improved direction continue, in any case. It's just a matter of time till the boiler-plate changes again.

---

From: Al Morton <[email-masked]>
Date: Wed, 21 Sep 2011 09:00:10 -0400

Thanks for your summary, Kenneth.
A few replies and comments, below.
Al

At 08:39 PM 9/20/2011, Kenneth Green wrote:
>...
>Nroffedit
>...
>- does not generate alternate output formats such as html or pdf?

When you submit a draft, the IETF systems now generate
both of these from your text file. See one here:
http://tools.ietf.org/html/draft-ietf-bmwg-2544-as-00

>The online version of xml2rfc already supports an nroff output 
>format so conversion xml->nroff is readily available. I wonder if a 
>feature or tool could be added to Nroffedit to generate XML output 
>and so allow maximum flexibility across source formats and output 
>formats (since xml2rtf supports output as html and pdf which are 
>very useful and much more readable and navigable alternatives to the 
>native RFC text format)?

We can ask that on tools-discuss list...

>- tool is much harder to learn/get started than with nroffedit

I agree, it's more like a development environment than a word processor.
But the difference seems to be that you **edit the WYSIWYG version**
in XMLMind

(it seems that you edit the nroff in Nroffedit, is that accurate?
  I haven't tried Nroffedit...)

>don't want to use the online version

I always use the web-based xml2rfc service, the references available there
maximally up-to-date. No fussing with that aspect, and I see auto-reference
text generation as a key feature.

>My understanding is that the IETF only ever holds the text files so 
>it is up to the author to hold/archive the primary source file. If 
>that is correct then I guess we can each choose our favourite 
>format/tool combination.

In the web-based submission service, you can upload
.txt, .xml, .pdf and .ps versions.  I don't see why
they would not also allow nroff, if requested.

>Certainly with just a little comparative experimentation the 
>Nroffedit solution appears much simpler and easier to use and its 
>bidirectional feature is a valuable asset.

I tend to agree, and will probably give Nroffedit a try in the future.
I used nroff for about 12 years before bowing to corporate pressure
and the simplicity of WYSIWYG.

One difference in our experience is that the free version of
XMLmind XML Editor I use is old - 3.0, but that's an advantage
because XMLMind decided to remove many function buttons from the
free version *after 3.0*. I found this out while trying to
tutor a bmwg'er years ago, and it resulted in much confusion.
We ended-up installing 3.0, and that's still an option...

---

From: Kenneth Green <[email-masked]>
Date: Wed, 21 Sep 2011 16:14:49 -0700

Thanks Al.

Yes, in Nroffedit you edit the nroff source but it instantly updates the formatted output in the adjacent pane so you effectively still have the WYSIWYG experience (see attached screenshot sample.png). In my brief experiment I found it much simpler and easier to use and to understand how to achieve the desired outcome than XMLmind . I also found Nroffedit has a simple popup help page with a list of the modest set of nroff commands so that even a complete novice has easy access to the information they need to get the job done (see sample2.png). Nroffedit also includes an automatic ToC and automatic reference generator which save a lot of otherwise fiddly effort.

XMLmind is not truly WYSIWYG, at least it did not appear so to me, but perhaps I was not driving it correctly. It does have more integrated support for boilerplate which is useful when first creating a new document, but you can achieve a similar goal in other ways.

Different strokes for different folks but as a novice RFC author Nroffedit comes out ahead on ease-of-learning and ease-of-use.

Regards,
Kenneth

Kenneth Green
Solution Architect
Ixia

-----Original Message-----
From: Al Morton [mailto:[email-masked]] 
Sent: Wednesday, 21 September 2011 11:00 PM
To: Kenneth Green; [email-masked]
Subject: Re: [bmwg] Internet Draft Review and Preparation in BMWG

>- does not generate alternate output formats such as html or pdf?

When you submit a draft, the IETF systems now generate both of these from your text file. See one here:
http://tools.ietf.org/html/draft-ietf-bmwg-2544-as-00

>The online version of xml2rfc already supports an nroff output format 
>so conversion xml->nroff is readily available. I wonder if a feature or 
>tool could be added to Nroffedit to generate XML output and so allow 
>maximum flexibility across source formats and output formats (since 
>xml2rtf supports output as html and pdf which are very useful and much 
>more readable and navigable alternatives to the native RFC text 
>format)?

>+ Found " Bill Fenner plug-in" here: 
>+ http://code.google.com/p/xml2rfc-xxe/

I agree, it's more like a development environment than a word processor.
But the difference seems to be that you **edit the WYSIWYG version** in XMLMind

>don't want to use the online version

I always use the web-based xml2rfc service, the references available there maximally up-to-date. No fussing with that aspect, and I see auto-reference text generation as a key feature.

>+ Can generate various useful additional output formats including html 
>+ and pdf
>
>My understanding is that the IETF only ever holds the text files so it 
>is up to the author to hold/archive the primary source file. If that is 
>correct then I guess we can each choose our favourite format/tool 
>combination.

In the web-based submission service, you can upload .txt, .xml, .pdf and .ps versions.  I don't see why they would not also allow nroff, if requested.

>Certainly with just a little comparative experimentation the Nroffedit 
>solution appears much simpler and easier to use and its bidirectional 
>feature is a valuable asset.

I tend to agree, and will probably give Nroffedit a try in the future.
I used nroff for about 12 years before bowing to corporate pressure and the simplicity of WYSIWYG.

One difference in our experience is that the free version of XMLmind XML Editor I use is old - 3.0, but that's an advantage because XMLMind decided to remove many function buttons from the free version *after 3.0*. I found this out while trying to tutor a bmwg'er years ago, and it resulted in much confusion.
We ended-up installing 3.0, and that's still an option...

---

From: Carlos Pignataro <[email-masked]>
Date: Thu, 22 Sep 2011 08:19:38 +0530

Hi Al,

> http://tools.ietf.org/rfcdiff

Actually, rfcdiff is maintained as a stand-alone tool as well, available
at <http://tools.ietf.org/tools/rfcdiff/>.

Thanks,

-- Carlos.

---

From: Al Morton <[email-masked]>
Date: Thu, 22 Sep 2011 00:39:34 -0400

At 07:14 PM 9/21/2011, Kenneth Green wrote:
>...Different strokes for different folks but as a novice RFC author 
>Nroffedit comes out ahead on ease-of-learning and ease-of-use.

Good, thanks for trying them out. With so many choices now,
I hope we don't have anyone editing flat text files...

---

From: Al Morton <[email-masked]>
Date: Thu, 22 Sep 2011 00:54:12 -0400

>at <http://tools.ietf.org/tools/rfcdiff/>.
Thanks, the link to this page was removed, meaning...?
Now I can try to get idcomments running,
Al

---

From: "Carlos Pignataro (cpignata)" <[email-masked]>
Date: Thu, 22 Sep 2011 14:43:56 -0500

Al,

This is a good comparison
http://wiki.tools.ietf.org/group/edu/raw-attachment/wiki/IETF80/80tools-
Hagens.pdf, check slides 3, 5, and 14.

Thanks,

-- Carlos.

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of
Al Morton
Sent: Thursday, September 22, 2011 10:10 AM
To: Kenneth Green; [email-masked]
Subject: Re: [bmwg] Internet Draft Review and Preparation in BMWG

---

From: Benoit Claise <[email-masked]>
Date: Fri, 30 Sep 2011 11:16:28 +0200

Hi Kenneth,

Based on your feedback, I wanted to install the "Bill Fenner plug-in" on 
the latest version of XMLmind 5.0.0,.
I followed http://code.google.com/p/xml2rfc-xxe/wiki/Installation, but 
could not get the add on to be recognized...

Regards, Benoit.

---

From: "Rajiv Asati (rajiva)" <[email-masked]>
Date: Fri, 30 Sep 2011 06:06:25 -0400

Fwiw, I just use MSword template (by Joe Touch) for drafting, editing, reviewing And commenting.

The 'track changes' comes handy when there are multiple co-authors and one is co-ordinating. 

No new learning.

Cheers,
Rajiv

Sent from Phone....

On Sep 30, 2011, at 5:16 AM, "Benoit Claise" <[email-masked]> wrote:

> Hi Kenneth,
> 
> Based on your feedback, I wanted to install the "Bill Fenner plug-in" on the latest version of XMLmind 5.0.0,.
> I followed http://code.google.com/p/xml2rfc-xxe/wiki/Installation, but could not get the add on to be recognized...
> 
> Regards, Benoit.

---

From: Al Morton <[email-masked]>
Date: Fri, 30 Sep 2011 07:01:38 -0400

Thanks for sharing your perspective, Rajiv.

>editing, reviewing And commenting.

I used MSWord for a while, too, and my older template required a
post-processing script as Joe's does, not a show-stopper but an
extra step every time...

>and one is co-ordinating.

Here, the various tools-team diff tools illustrate changes nicely with
any editing-tool choice, but the ability to accept/reject changes
immediately in MSWord is hard to beat.

>No new learning.

You give-up auto-reference text-fill (right?),
but I get where you're coming from.
In the end, it's a flavor issue.
Al

---

From: Carlos Pignataro <[email-masked]>
Date: Fri, 30 Sep 2011 09:03:52 -0400

I hope it's useful to extend this tools discussion here, please see inline.

>> and one is co-ordinating.

This assumes those multiple co-authors are capable and willing to use MS
Word. Personally, I've no particular editing tool religion, and I have
edited RFCs in pretty much everything. But I do have a preference list,
here in decreasing preference order {xml; nroff; etherpad; MS Word}.

> any editing-tool choice,

I think this is a great point, that effectively make editing from
diffing independent.

> but the ability to accept/reject changes

No new learning as a feature or a bug? I know we have a big fat hammer,
but are these nails?

> In the end, it's a flavor issue.

It is indeed a flavor issue in the end. But I think you give up a lot
more than auto-reference (and citation) text. You are giving up
semantics (and what-you-see-is-what-you-mean) for looks. Having a source
with structure and meaning means you can have output targets in many
formats, you can create bibliography indexes without doing heuristics,
add metadata, etc.

The more tactical feature you'd give up is an almost-guaranteed
idnits-free output.

Thanks,

-- Carlos.

---

From: "Rajiv Asati (rajiva)" <[email-masked]>
Date: Fri, 30 Sep 2011 15:44:58 -0500

It is hard to find anyone who doesn't know about MS-Word independent of
individual preference. That's what I meant. :-) I never had to explain
anyone how would the word doc work out.

I agree that MSWord doesn't have lot of bells & whistles as the
alternatives do.

Cheers,
Rajiv

> From: [email-masked] [mailto:[email-masked]] On Behalf
Of Carlos
> Pignataro (cpignata)
> Sent: Friday, September 30, 2011 9:04 AM
> To: [email-masked]