Subject: I-D examples wanted

From: James Carlson <[email-masked]>
Date: Tue, 14 Mar 2006 08:35:49 -0500

One of the newer pppext participants had an idea to help I-D authors
(and wg chairs as well), and I figured this would be a reasonable
place to solicit comments and perhaps some help.

It seems that getting all of the newly-picky boilerplate and layout
bits right is becoming a bit of a barrier, to the point where only a
handful of people seem to get it right in the first shot, and most are
sent back through hours of drudge work.

The idea was to have a set of example correctly-formed I-D sources (in
various useful formats, say nroff and XML) on one of the I-D web pages
(such as http://www.ietf.org/ietf/1id-guidelines.html or perhaps
http://www.rfc-editor.org/formatting.html), so that authors could crib
from something known to be right.  Better still if these could be kept
up-to-date with each change to the process.  (It seems virtually
certain to me that there'll be more changes in the future.)

The only referenced examples I could dig up directly were these:

  ftp://ftp.rfc-editor.org/in-notes/rfc-editor/2-nroff.template
  ftp://ftp.rfc-editor.org/in-notes/rfc-editor/2-Word.template.rtf

which are both stale enough to be useless for this purpose.  Am I
looking in the wrong place, or do we expect I-D authors to be
illuminated manuscript writers as well?  ;-}

-- 
James Carlson, KISS Network                    <[email-masked]>
Sun Microsystems / 1 Network Drive         71.232W   Vox +1 781 442 2084
MS UBUR02-212 / Burlington MA 01803-2757   42.496N   Fax +1 781 442 1677

---

From: <[email-masked]>
Date: Tue, 14 Mar 2006 15:39:54 +0200

James,

XML2RFC is your friend.  Its not the most fun tool to use for editing
drafts, but it seems to have solved most of nit-picky boilerplate errors
I have had in the past.

A great resource is:
http://tools.ietf.org/inventory/author-tools 

John

>-----Original Message-----
>From: ext James Carlson [mailto:[email-masked]] 
>Sent: 14 March, 2006 15:36
>To: [email-masked]
>Subject: I-D examples wanted
>
>One of the newer pppext participants had an idea to help I-D 
>authors (and wg chairs as well), and I figured this would be a 
>reasonable place to solicit comments and perhaps some help.
>
>It seems that getting all of the newly-picky boilerplate and 
>layout bits right is becoming a bit of a barrier, to the point 
>where only a handful of people seem to get it right in the 
>first shot, and most are sent back through hours of drudge work.
>
>The idea was to have a set of example correctly-formed I-D 
>sources (in various useful formats, say nroff and XML) on one 
>of the I-D web pages (such as 
>http://www.ietf.org/ietf/1id-guidelines.html or perhaps 
>http://www.rfc-editor.org/formatting.html), so that authors 
>could crib from something known to be right.  Better still if 
>these could be kept up-to-date with each change to the 
>process.  (It seems virtually certain to me that there'll be 
>more changes in the future.)
>
>which are both stale enough to be useless for this purpose.  
>Am I looking in the wrong place, or do we expect I-D authors 
>to be illuminated manuscript writers as well?  ;-}
>
>--

---

From: David Meyer <[email-masked]>
Date: Tue, 14 Mar 2006 07:28:14 -0800

James,

> illuminated manuscript writers as well?  ;-}

	For mechanics of xml2rfc, I've been using the attached to
	help folks get up to speed (has examples of a few things
	folks generally would like to know). For nroff stuff, see 
	http://www.1-4-5.net/~dmm/generic_draft.tar.gz (I can
	almost guarantee that the boilerplate is not up to date; I
	haven't been watching it since I switched to xml2rfc).

	Dave

---

From: "Tom-PT Taylor" <[email-masked]>
Date: Tue, 14 Mar 2006 11:05:27 -0500

As an XML editor, I've been using Notetab Lite. I customized a general 
XML clip library to contain the specific tags and attributes XML2RFC uses.

---

From: David Meyer <[email-masked]>
Date: Tue, 14 Mar 2006 08:08:53 -0800

> XML clip library to contain the specific tags and attributes XML2RFC uses.

	Maybe someday I'll get into the current decade (century,
	millennium), but I just use xemacs in text-mode (I don't
	even like xml-mode). Primitive, I know, but...

	Dave

---

From: Elwyn Davies <[email-masked]>
Date: Tue, 14 Mar 2006 14:05:40 +0000

xml2rfc: Absolutely!

FYI There will be an edu session on xml2rfc at the Dallas IETF (Sunday 
afternoon) and the slides will be available in a couple of days.

xml2rfc can be found at http://xml.resource.org/

One trick that non-xml2rfc users can do is to run the sample file (on 
the web page) through the on-line tool on the same page.
This produces what is usually an up to date view of the boilerplate.  Of 
course it just has to happen that we haven't caught up with the ISOC -> 
IASA change in the RFC Editor funding bit at this instant :-(

BTW Bill Fenner's XMLmind plugin is a way to make xml2rfc much better 
fun to use.

Regards,
Elwyn

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 17 Mar 2006 11:46:14 +0100

>   ftp://ftp.rfc-editor.org/in-notes/rfc-editor/2-Word.template.rtf

To be frank I don't see how nroff or Word users are going to get
away from the problem of having the latest boilerplate other than
by manual cut and paste when it changes. I used nroff when
it was the only way, tried Word with great pain for a couple
of drafts, and have been worry-free since switching to xml2rfc.

Make sure all your authors know about the checker at
http://tools.ietf.org/tools/idnits/idnits.pyht

A clean run through that is a really good idea before submitting
a draft.

    Brian

---

From: "Randy Presuhn" <[email-masked]>
Date: Fri, 17 Mar 2006 11:51:53 -0800

Hi -

> From: "Brian E Carpenter" <[email-masked]>
> To: "James Carlson" <[email-masked]>
> Cc: <[email-masked]>
> Sent: Friday, March 17, 2006 2:46 AM
> Subject: Re: I-D examples wanted
...
> by manual cut and paste when it changes. I used nroff when
...

Using the *roff .so directive for boilerplate makes the problem much
less bad, especially if one is working on multiple documents.   For
large or complex documents, it can also make the editing easier.
However, (g)soelim might be advisable before handing the source to
the secretariat.

It's all a tradeoff.  If most of the time would go to dealing with boilerplate
or getting references right, and the bulk of the document is straight text,
xml2rfc is a clear winner.  If  a document has more complex formatting
needs *roff would still be my choice.

Randy