Subject: RE: Faux Pas -- web publication in proprietary formats at ietf.org

From: "Hallam-Baker, Phillip" <[email-masked]>
Date: Mon, 7 Nov 2005 09:24:51 -0800

> From: [email-masked] [mailto:[email-masked]] On 
> > HTML may look nothing like the author intended.
> 
> Now if the author is more interested in his layout than 
> readability and accesibility, let alone transport costs, then 
> he's obviously stupid.

More likely the author is simply thoughtless. 

I have a Treo device, plain text email markup works a lot less well than
properly designed HTML.

The problems with HTML are almost entirely the result of people trying
to give the author control over the final format which is none of the
author's beeswax. 

It is somewhat ironic to see 'printability' touted as an advantage of
plaintext. IETF documents are dreadful to print out because they will
only print on -printers with a particular font and a particular size of
paper. If you try to print out RFCs in Europe or on the most popular O/S
on the planet you get the headers creaping forward or back a line or
two.

I also agree about the PDF font problem. I do have problems printing pdf
documents from time to time and every two weeks acrobat asks to upgrade
itself, then if I forget and click yes thinks for a while before
concluding that it can't upgrade my copy which is the paid version, not
the free one.

_______________________________________________
Ietf mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: "Anthony G. Atkielski" <[email-masked]>
Date: Mon, 7 Nov 2005 18:45:27 +0100

> to give the author control over the final format which is none of the

It has been the author's prerogative for thousands of years; I'm not
sure why that must change now.  The author is the creator of the
content, not the reader.

> concluding that it can't upgrade my copy which is the paid version, not

If the fonts are properly embedded, they are not a problem.

---

From: Frank Ellermann <[email-masked]>
Date: Mon, 07 Nov 2005 20:14:16 +0100

> More likely the author is simply thoughtless.

An extreme case of "thoghtless", because the size difference
from plain to PDF is huge, I'd guess about a factor 50, from
plain to HTML it's only a factor 2.

> plain text email markup works a lot less well than properly
> designed HTML.

My stoneage MUA tries to display HTML as HTML if available,
and your experiment here was hard to read, you used a rather
small font.  IMHO it's okay if folks use HTML _iff_ necessary
in mail, sometimes (rarely) I also do it, trimming the MIME
overhead to a minimum manually - so that others with a plain
text UA might still find what I intended to say.

RfC 1855 got it wrong, monospaced fonts like Courier are still
the best choice for mail, and that won't change in my lifetime.

> IETF documents are dreadful to print out

type rfc1234.txt > prn  is pretty simple, they come complete
with formfeeds.  Admittedly the number of RfCs or I-Ds I ever
printed is zero.

> they will only print on -printers with a particular font and
> a particular size of paper.

Don't send them to your "xyz" printer driver, they are already
formatted, send them directly to /dev/lpt1 or similar.  Or use
a "dumb" driver.   Or better don't waste paper to print RfCs,
they are available online whereever you are... -)

> every two weeks acrobat asks to upgrade itself

Works for the as you said "most popular O/S on the planet" and
the reader.  And at least there are upgrades for this O/S and
some others, it's less funny with my less popular OS/2.

But some PDFs generated with open office still work with my
old Acroreader 3, no "colorspace 6 not found" or other issues
like "cannot extract embedded font".  And why should I want
any embedded fonts, my OS/2 has a nice Adobe Courier, a nice
Adobe Hevetica, even some ugly Times New Roman, that should
be good enough for anything I care about (excl. math.)

> it can't upgrade my copy which is the paid version, not the
> free one.

Maybe test this open office beast if you want to create PDFs
"visible with any AcroReader", i.e, 3 or better. <eg>  That's
a new "law", good stuff is always version 3.x, DOS, PDF, HTML,
Warp, what else ?
                           Bye, Frank

---

From: "Anthony G. Atkielski" <[email-masked]>
Date: Tue, 8 Nov 2005 04:04:13 +0100

> be good enough for anything I care about (excl. math.)

I still use Acrobat 4.x to generate PDFs, and it works just fine.
Generally speaking, there's nothing in an ordinary document that
requires anything more recent.  The more recent versions are designed
to maintain revenue for Adobe, not to provide any useful features or
functionality.

---

From: Stephane Bortzmeyer <[email-masked]>
Date: Tue, 8 Nov 2005 10:23:09 +0100

On Mon, Nov 07, 2005 at 09:24:51AM -0800,
 Hallam-Baker, Phillip <[email-masked]> wrote 
 a message of 36 lines which said:

> If you try to print out RFCs in Europe 

I print RFC all the time (I'm an old dino, used to paper), I live in
France which seems to be in Europe and It Works For Me.

---

From: Stephane Bortzmeyer <[email-masked]>
Date: Tue, 8 Nov 2005 10:24:08 +0100

On Mon, Nov 07, 2005 at 06:45:27PM +0100,
 Anthony G. Atkielski <[email-masked]> wrote 
 a message of 24 lines which said:

> It has been the author's prerogative for thousands of years;

Certainly not, unless the author is also the typographer, which is
uncommon.

> The author is the creator of the content, not the reader.

The content, not the presentation.

---

From: Stephane Bortzmeyer <[email-masked]>
Date: Tue, 8 Nov 2005 10:26:58 +0100

On Mon, Nov 07, 2005 at 09:24:51AM -0800,
 Hallam-Baker, Phillip <[email-masked]> wrote 
 a message of 36 lines which said:

> The problems with HTML are almost entirely the result of people
> trying to give the author control over the final format which is
> none of the author's beeswax.

BTW, does anyone who knows IETF and the RFC-editor function better
than I do, can tell why RFC 2629 is not the mandatory official format
for RFC, even now after six years?

---

From: "JFC (Jefsey) Morfin" <[email-masked]>
Date: Tue, 08 Nov 2005 10:41:13 +0100

>The content, not the presentation.

Stephane,
you refer yourself only to a short period of 500 years, mostly in 
Western Europe. The computer assisted writing, restores that right. 
The architext container restores and extend many possibilities in 
that area. Typography is a part of the presentation. Even in the 
French early XXth century poestry this was the case (cf. Apollinaire).
jfc

---

From: Stephane Bortzmeyer <[email-masked]>
Date: Tue, 8 Nov 2005 10:54:43 +0100

On Tue, Nov 08, 2005 at 10:41:13AM +0100,
 JFC (Jefsey) Morfin <[email-masked]> wrote 
 a message of 21 lines which said:

> Typography is a part of the presentation.

Nobody would object here :-)

> Even in the French early XXth century poestry this was the case
> (cf. Apollinaire).

Not everyone is Apollinaire. That's why we need typographs (I fully
agree with Phillip Hallam-Baker here: presentation is important, and
that's why it should be left to professionnals). If everyone were
Voltaire, we would not need smileys to express irony.

---

From: Andrew Newton <[email-masked]>
Date: Tue, 8 Nov 2005 08:36:55 -0500

> for RFC, even now after six years?

My guess is that it is not a trivial matter to convert RFCs submitted  
in other forms into 2629 xml format.  And though I prefer to use  
xml2rfc, there are many people desiring some of the word processor  
features (track changes, etc...) that are just not found in the xml  
authoring tools.

-andy

---

From: Stephane Bortzmeyer <[email-masked]>
Date: Tue, 8 Nov 2005 15:25:59 +0100

On Tue, Nov 08, 2005 at 08:36:55AM -0500,
 Andrew Newton <[email-masked]> wrote 
 a message of 14 lines which said:

> My guess 

You mean there is nowhere an official statement and we have to guess?

> is that it is not a trivial matter to convert RFCs submitted in
> other forms into 2629 xml format.

OK for the existing stuff but why not for the future, such as
"Starting 1 Jan 2007, every RFC submission must be done in 2629"?

> there are many people desiring some of the word processor features
> (track changes, etc...) that are just not found in the xml authoring
> tools.

Well, you certainly know that XML is a format, not a program :-) So,
at least in theory, you could use OpenOffice and still producing 2629
(providing someone wrote a XSL transformation from OpenDocument to
2629). Not obvious, I know, but a possible path.

For the specific feature you mention, I use version control system
with XML, I do not see the problem. Tools like Subversion even allow
you to specify an external diff so you can use a XML-aware diff to see
the changes.

---

From: Andrew Newton <[email-masked]>
Date: Tue, 8 Nov 2005 14:23:29 -0500

> You mean there is nowhere an official statement and we have to guess?

Not that I know of, but I could be wrong.

> 2629). Not obvious, I know, but a possible path.

That is certainly a possibility.  And a good idea.

> you to specify an external diff so you can use a XML-aware diff to see

I too use Subversion and rfcdiff and xml2rfc.  But there are people  
doing work (i.e. writing docs) in the IETF that do not work this  
way.  They may find using a version control system to be time-wise  
expensive or prohibitive, especially compared to emailing track- 
change-docs back and forth.

-andy

---

From: Frank Ellermann <[email-masked]>
Date: Wed, 09 Nov 2005 03:15:13 +0100

Stephane Bortzmeyer wrote:

 [your premise snipped ;-]
> tell why RFC 2629 is not the mandatory official
> format for RFC, even now after six years?

It's an excellent tool to create real drafts and
RfCs.  For "real" read text/plain us-ascii in the
format defined elsewhere (2223bis among others).

It's not the only available tool.  Bruce is the
maintainer of the nroff tools, and somebody else
offers MS word tools.

The tools team apparently adopted RfC 2629 as the
primary format for the automatical handling of
submissions, and one of the "document set" drafts
also builds on this format.

Just let it be, eventually it will be as you want
it.  Numerous tools like rfcmarkup still build on
the "real" format, and nothing's wrong with that.

With xml2rfc you can now also create unpaginated
output, nice for creating / posting a quick diff.
That feature was added this year, it's still a
living project, last DTD updates also this year.

The EULA boilerplates (= 78/79) are also still a
moving target (unfortunately).  This is all not
yet ready to be cast in stone.  Only the general
direction is IMHO more or less clear.  Bye, Frank

---

From: Stewart Bryant <[email-masked]>
Date: Mon, 14 Nov 2005 13:56:46 +0000

> doing work (i.e. writing docs) in the IETF that do not work this  way.  
> They may find using a version control system to be time-wise  expensive 
> or prohibitive, especially compared to emailing track- change-docs back 
> and forth.
> 

I would not mind swapping from to an XML package
provided it supported change-tracking, embedded comments,
highlighting, WYSWYG display, edit time spell and edit time
grammer checking, and was a simple to install and maintain
on XP.

Is there such a package?

If not, I will stick with Word and continue to exchange
change-track text with my co-authors.

- Stewart

BTW - one carrot that would tempt me away would be if the
result allowed the normative text to incorprate proper
diagrams - like ITU and IEEE - two name but two - have
use in their specifications for the last 20 or so years.

---

From: Steve Crocker <[email-masked]>
Date: Mon, 14 Nov 2005 09:37:41 -0500

On Nov 14, 2005, at 8:56 AM, Stewart Bryant wrote:

> <snip>

The issue of diagrams is entangled in the long-standing discussion of  
proprietary formats.  There is a huge benefit in having a format that  
*everyone* can access without difficulty or cost.  I can't begin to  
tell you the impact I felt when I walked into a university half way  
around the world in an underdeveloped country and had a graduate  
student show me some pretty sophisticated stuff he had done based on  
RFCs he had downloaded from the net.  ASCII is an enormous advantage  
from that respect.

At the same time, we have clearly hobbled ourselves in not moving  
forward with more advanced technology.  In a way, we have made  
ourselves a parody of our own success, staying locked into 1960s  
technology while we have created the technology for the twenty-first  
century.  The ITU and IEEE have progressed to PDF and other formats,  
partly because they still view paper as the primary medium.

I don't know whether this issue was covered in the TechSpec BoF  
(http://www3.ietf.org/proceedings/05nov/agenda/techspec.txt) but it  
definitely needs attention.  Perhaps this should be a separate thread  
in the discussions about publications.

Steve

Steve Crocker
[email-masked]

---

From: "Doug Ewell" <[email-masked]>
Date: Tue, 8 Nov 2005 06:34:09 -0800

Stephane Bortzmeyer <bortzmeyer at nic dot fr> wrote:

> If everyone were

That is awesome.  That is going straight into my fortune-cookie file.

--
Doug Ewell
Fullerton, California, USA
http://users.adelphia.net/~dewell/

---

From: Michael Mealling <[email-masked]>
Date: Mon, 14 Nov 2005 09:55:45 -0500

IMHO, standardizing on _validated_ SVG with a library of well understood 
images that represented architectural components with attached semantics 
could be used to even start validating diagrams the same way we validate 
BNFs now. There are even UML to SVG tools for turning SVG drawings 
directly into code. And there are lots of free SVG tools....

-MM

-- 
Michael Mealling                  Masten Space Systems, Inc.
VP Business Development                       473 Sapena Ct.
Office: +1-678-581-9656                            Suite 23
Cell: +1-678-640-6884                 Santa Clara, CA 95054
                 http://masten-space.com/

---

From: Andrew Sullivan <[email-masked]>
Date: Mon, 14 Nov 2005 11:40:44 -0500

> RFCs he had downloaded from the net.  ASCII is an enormous advantage  

What I find strange about this, though, is the reluctance to adopt
PDF.  It's a well-known open standard.  There are plenty of free
software interpreters and writers around, and Ghostscript passed the
threshold for good output 2 or 3 versions ago.  I understand the
difficulty of machine parsing, but wouldn't an XML format with human
oriented output in PDF be nice?  (I suppose I'm asking whether
there's some historical flamewar over this that I managed never to
look at, in which case I'll just keep my mouth shut.)

Of course, even if that was solved, the features of Word that other
like are not really available in most of the XML tools, AFAIK. 

A

-- 
----
Andrew Sullivan                         204-4141 Yonge Street
Afilias Canada                        Toronto, Ontario Canada
<[email-masked]>                              M2P 2A8
                                        +1 416 646 3304 x4110

---

From: Jari Arkko <[email-masked]>
Date: Mon, 14 Nov 2005 18:03:07 +0200

>look at, in which case I'll just keep my mouth shut.)
There is. Lets not reopen the format flame war. However,
just for the record we DO have .pdf as a format that you
can submit Internet Drafts and as something that you
also get from the RFC Editor. It is required that a text
format be also provided, which I think is natural and
useful. Some of the PDF documents that people have
used have contained illustrations such as state machines.
See for instance this RFC
   ftp://ftp.rfc-editor.org/in-notes/rfc4137.pdf
and for some tool support take a look at
   http://www.arkko.com/tools/xml2pdfrfc.html

>like are not really available in most of the XML tools, AFAIK. 
I kind of like the rfcdiff feature in text format more
than the word features.

--Jari

---

From: Andrew Sullivan <[email-masked]>
Date: Mon, 14 Nov 2005 12:14:51 -0500

> can submit Internet Drafts and as something that you

Ok, consider it not re-opened.  (And yes, I knew about the pdfs.  It
just struck me as odd that people were grousing about ASCII's
appearance when PDF is available.  But I'm keeping the worm-can
closed.)

A

---

From: Dave Crocker <[email-masked]>
Date: Mon, 14 Nov 2005 09:27:21 -0800

>>      I understand the
> also get from the RFC Editor. 

Folks might want to take a look at the latest xml2rfc capabilities.  See 
<http://xml.resource.org/>.  Besides making it far easier to include the 
correct boilerplate, it has the option of including pretty graphics for the 
PDF version, while using the ASCII form for the ASCII version.

This seems like a rather good transition mechanism, to see whether we really 
want/need to move away from ASCII.  (After all, the dual-stack model for 
transition is a time-honored methodology...)

d/
-- 

Dave Crocker
Brandenburg InternetWorking
<http://bbiw.net>

---

From: Stewart Bryant <[email-masked]>
Date: Mon, 14 Nov 2005 19:08:30 +0000

>>can submit Internet Drafts and as something that you

However these are not taken as normative, so you have to
produce an ASCII equivalent, which fundamentally limits the
complexity of any normative diagram.

My view is this is a serious restriction in the power
of the "language" that we are allowed to use to describe
our protocols, but then I am a person that finds it
much easier to understand diagrams than text.

- Stewart

- Stewart

---

From: Bill Fenner <[email-masked]>
Date: Mon, 14 Nov 2005 11:14:55 -0800

> grammer checking, and was a simple to install and maintain

My xxe plugin, http://rtg.ietf.org/~fenner/ietf/xml2rfc-xxe/, provides
a few of the features:
- embedded comments (with <cref>)
- WYSIKLWYG (What you see is kinda like what you get) display
- Edit time spell check

It's based on the XMLMind XML Editor, which is an excellent
cross-platform java-based XML editor, which is not open-source but has
a free "Standard Edition" and an excellent "Professional Edition".  My
plugin works fine with both, but certain features such as PDF output
are limited to the Professional Edition.

I've been pondering change tracking, in the context of copy-editing,
but I haven't come up with a complete thought yet.

  Bill

---

From: Jari Arkko <[email-masked]>
Date: Mon, 14 Nov 2005 20:32:46 +0200

Dave Crocker wrote:

> Folks might want to take a look at the latest xml2rfc capabilities.  
> See <http://xml.resource.org/>.  Besides making it far easier to 
> include the correct boilerplate, it has the option of including pretty 
> graphics for the PDF version, while using the ASCII form for the ASCII 
> version.

XML2RFC has improved in this regard, e.g., it allows inclusion
of pictures for the HTML version. But I do not think even the
latest version generates .pdf nor does it appear to produce
very pretty output from xml->html->pdf. Though your favorite
XML editing tool may provide some solution for that. Nevertheless,
I've had good success in running xml->nr->pdf, but that requires
some tuning of the nroff output -- this is what the tool link that
I posted earlier does, without requiring the user to do any
extra steps or having any software beyond what regular unix
systems do by default.

--Jari

---

From: Julian Reschke <[email-masked]>
Date: Mon, 14 Nov 2005 20:46:53 +0100

> very pretty output from xml->html->pdf. Though your favorite

You can get fairly good PDF using rfc2629toFo.xslt (available from 
<http://greenbytes.de/tech/webdav/rfc2629xslt.zip>) and Apache-Fop. See 
for instance <http://greenbytes.de/tech/webdav/rfc3986.pdf>.

> ...

Best regards, Julian

---

From: "Anthony G. Atkielski" <[email-masked]>
Date: Tue, 15 Nov 2005 06:59:56 +0100

> complexity of any normative diagram.

Depends.  If the ASCII document is large enough, in theory you can
represent any monochrome image with an arbitrary degree of accuracy.
If line lengths or number are limited, though, this isn't possible.
Essentially you just make some non-blank ASCII character represent a
dark pixel, and use a blank for a white pixel.  So with 768 lines of
1024 characters each, you can represent a typical video display.

---

From: "Steven M. Bellovin" <[email-masked]>
Date: Tue, 15 Nov 2005 10:53:33 -0500

In message <[email-masked]>, Bill 
>but I haven't come up with a complete thought yet.

CVS?  Should the Secretariat make CVS archives available to WG 
document editors?  I've written a book and many joint papers via CVS; 
it works very well for line-oriented ASCII input, whether XML, LaTeX, 
nroff, or what have you.

		--Steven M. Bellovin, http://www.cs.columbia.edu/~smb

---

From: Simon Josefsson <[email-masked]>
Date: Tue, 15 Nov 2005 17:22:31 +0100

> it works very well for line-oriented ASCII input, whether XML, LaTeX, 

I think CVS would be an excellent idea for this.  The IESG evaluation
record in the I-D tracker attempt to do some history management.  A
changed IESG votes is marked with a '.' for the old vote.  History for
other things are not recorded, e.g., earlier drafts of the approval
e-mail.  Being able to access how these evolve can be useful for
accountability.

Thanks,
Simon

---

From: "Randy Presuhn" <[email-masked]>
Date: Tue, 15 Nov 2005 11:35:37 -0800

Hi -

> From: "Simon Josefsson" <[email-masked]>
> To: "Steven M. Bellovin" <[email-masked]>
> Cc: <[email-masked]>; "Stewart Bryant" <[email-masked]>
> Sent: Tuesday, November 15, 2005 8:22 AM
> Subject: Re: RFCs should be distributed in XML (Was: Faux Pas -- ...
...

webdav / deltav?

Randy

---

From: Ted Faber <[email-masked]>
Date: Wed, 16 Nov 2005 09:45:00 -0800

> it works very well for line-oriented ASCII input, whether XML, LaTeX, 

I think Bill was talking about making his editing plug-in display
changes to the document as change bars or whatnot.  But that's just my
interpretation.

WRT revision control software on I-Ds, I think it's an excellent idea,
but authors should use whatever they agree on.  IMHO, the IETF doesn't
need to provide a system.  CVS vs. RCS vs. subversion vs. $DIETY knows
what is too much of a mess to wade into for the benefit.  If the
Secretariat is going to provide something it may as well be wdiff
(ASCII/HTML) output which is human readable.  IMHO.

-- 
Ted Faber
http://www.isi.edu/~faber           PGP: http://www.isi.edu/~faber/pubkeys.asc
Unexpected attachment on this mail? See http://www.isi.edu/~faber/FAQ.html#SIG
_______________________________________________
Ietf mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: Bill Fenner <[email-masked]>
Date: Wed, 16 Nov 2005 12:29:51 -0800

On 11/16/05, Ted Faber <[email-masked]> wrote:
> changes to the document as change bars or whatnot.

Right, whatnot.  In actual fact, what I have been thinking of was a
change-acceptance function for copy editing (show old, show new, show
both, accept new, reject new, create alternate new) - not particularly
what you want for day to day change control.

Straight revision control systems aren't actually that good for XML
that's been edited in an XML editor, since they tend to pretty-print
the XML when saving, and people using 2 different editors could end up
creating diffs on every line.  (Of course, one could use a front end
to the revision control system that formatted the XML and used rfcdiff
on the result...)

  Bill

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 17 Nov 2005 09:25:03 +0100

On Wed, Nov 16, 2005 at 09:45:00AM -0800, Ted Faber wrote:
 
> what is too much of a mess to wade into for the benefit.

I strongly disagree. I fact, I would love if the IETF could settle on
a system and in the long term, even the RFC editor would just use it.
It will make my life much easier if I do not have to manually track
changes applied by the RFC editor to put them back into my version
controlled repository so that the editorial fixes are not lost when
the ID is up for revision.

It seems that the open source community much better understands what
it means to edit documents and how important it is to even agree on
style guidelines in order to be efficient. The IETF is really in the
stone age as an organization in this respect.

Perhaps the reason is that those who still know how to write and
maintain code have become the minority in the IETF.

/js

-- 
Juergen Schoenwaelder		    International University Bremen
<http://www.eecs.iu-bremen.de/>	    P.O. Box 750 561, 28725 Bremen, Germany

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Thu, 17 Nov 2005 09:28:28 +0100

> to the revision control system that formatted the XML and used rfcdiff

As you said, reasonable version control systems have hooks which can
be used to automatically "normalize" documents while they are being
checked in.

/js

---

From: Ted Faber <[email-masked]>
Date: Thu, 17 Nov 2005 09:22:10 -0800

> the ID is up for revision.

Net me be clear - that's a great goal.  I'd like to see that, too. 
If we could convince everyone to use CVS and XML2RFC that would be a
nice straightforward way to get there.  But people use a wide variety of
authoring tools (I'd like to call them editors, but lumping vi in with
MS Word seems to cover too big a space) and to a lesser extent revision
control tools.  There are people writing RFCs in Word, latex, XML2RFC,
groff (yay!), and plain ASCII.  Asking the RFC editor to make changes in
all those formats and CVS them seems to put a lot of strain on an
already overburdened group.

Getting anyone to change their authoring tool is difficult, so hoping
for standardization on CVS input is pretty unlikely.  In my experience,
IETF contributors are an order of magnitude more stubborn than most
authors, but even if that estimate's wrong, I think there's a lot of
inertia here.

One way forward is to put the CVS/RFC2XML system up and hope people
migrate for the advantages.  I'm not optimistic, though I happily use
both tools.

> stone age as an organization in this respect.

I'm amazed at a comparison between the documentation in the open source
community and the document series produced by the IETF that's anything
but unfavorable to open source.

Again, let me be precise: I love, produce, use and delight in open
source software.  I've even documented some.  But as a whole, saying
that open source documentation is no great model of clarity,
completeness, consistency or even presence is being very polite.
Software is documented in manpages, html, info, ASCII, javadoc,
postscript, individual program help formats, and $DIETY knows what else.
When I install a new piece of open source software I don't know *if*
there will be documentation, let alone what I'll need to read it.
Quality and clarity of the docs is largely based on the implementor's
skill and time, both of which vary wildly.

Before you suggest that some individual Open Source projects are very
standardized in how they document: I agree and appreciate the good ones.
But you should consider the difference in scale between the IETF and
most open source projects.  (IETF: scale 'r' us)

For any IETF standard I know there will be a reasonably edited, ASCII
document (or six) that will lay out the operation for me.  I know where
to go to look for updates to that document and know that the version I
have in front of me is authoritative, even if I haven't checked it out
of CVS recently.  I even have some hope that it will be written in clear
English - probably clear enough to read even if I'm a non-native
speaker.

It's perfectly reasonable to talk about improving the IETF publication
process.  It's even productive - IMHO XML2RFC is a significant
improvement that I hope becomes a de facto standard for producing and
editing RFCs.  But let's neither lose sight of the significant benefits
of the current process nor lose those benefits in a rush to improvement.

The current process didn't just happen.  It is the process of design
decisions.  Those decisions and the goals they're based on must be
subject to constant evaluation and revision, but the RFC publication
process isn't the way it is entirely by happenstance.

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 18 Nov 2005 09:13:33 +0100

> migrate for the advantages.  I'm not optimistic, though I happily use

Clarification #1: I believe the IETF (tools team perhaps) should
provide version control services (again I favour SVN over CVS but that
is an implementation detail) for WGs who _want_ to use it. Much like
xml2rfc is out there for authors/editors who _want_ to use it. I
request that the RFC editor will accept xml2rfc as an input format.
See also Bert Wijnen's early copy editing experiment where they seem
to have used xml2rfc successfully for copy editing. In other words,
the proposal is not to force people who strongly believe in other
tools to use xml2rfc or the repository. However, I believe having
support for xml2rfc plus revision will be a big step for the community
which already uses the xml2rfc format and is kind of happy with it.

BTW, does the RFC editor have a record which typesetting system has
recently been used to produce the documents that end up on his desk?
Getting some hard numbers which formatting toolset people have
actually used for documents that end up in the RFC editor's queue
would help to understand where we are. If we do not have such numbers,
perhaps we should start an experiement to collect this information for
say three month in order to bring substance into the debate.

> completeness, consistency or even presence is being very polite.

Clarification #2: I did not think of open source documentation - I was
referring to the source code itself. I believe there is no fundamental
difference between the production of source code and technical
specification when it comes to the importance of change management,
style guides, bug tracking and long term evolution and maintenance of
revision history. In other words, I believe that an IETF WG needs
almost exactly the same tool chain, namely agreement on common
formats, revision control, bug tracking.

/js

---

From: Ted Faber <[email-masked]>
Date: Fri, 18 Nov 2005 08:43:07 -0800

On Fri, Nov 18, 2005 at 09:13:33AM +0100, Juergen Schoenwaelder wrote:
> xml2rfc is out there for authors/editors who _want_ to use it.

I think we agree on that.  In fact I think we're in general agreement,
but some of the details differ.

>                                                                I

I thought they did take it as a supplement or something, which I hope
indicates that they are considering moving to it.  

> which already uses the xml2rfc format and is kind of happy with it.

I agree that this is a great goal.  But there are certainly going to be
people who are not going to do it.  I dunno why either - the advantages
seem considerable and obvious to me, too.

> recently been used to produce the documents that end up on his desk?

I don't know.  They (the RFC Editor is many people, many of whom aren't
he's :-)) may not get that information at all.  I agree it would be
interesting to know.

> formats, revision control, bug tracking.

Again, in the big picture we agree.  The IETF needs to keep track of
document revisions, bugs (outstanding issues), and produce consistent
documents.

I think that RFC formats and the RFC editor do establish a style guide.
I don't think you like the style that's being enforced, but I think
there is a (fairly consistent) style in force.  xml2rfc on the front end
and the backend idnits checker from the tools team help automate
following that style.  They're collectively indent(1) Or maybe lint(1)
for RFCs.

I think the bug tracking is addressed significantly by the issue
tracker.  Specs and implementations aren't the same and I don't think a
bug tracker with trouble tickets and all that is really what we need,
but I could be convinced.  I'm curious if you think the issue tracker
tool needs extending or scrapping.

I do agree that fine grained source control would be nice and if the
IETF wants to run a community source control system, I think that
would be a valuable resource.  I'm cautious that there might be a morass
here in picking the system, but if someone on the tools team just does
it, that may avoid the rathole simply.

Sorry if I misrepresented your position earlier.

---

From: Bill Sommerfeld <[email-masked]>
Date: Mon, 21 Nov 2005 09:16:07 -0500

> indicates that they are considering moving to it. 

They do.

These days, when a draft moves into the RFC editor queue, the RFC editor
sends a request to the author to send in the xml2rfc input files if they
exist.

Keeping the .xml in some sort of revision control repository during the
internet-draft stages seems like an obvious next step.

					- Bill

---

From: "Doug Ewell" <[email-masked]>
Date: Mon, 21 Nov 2005 20:19:24 -0800

Bill Sommerfeld <sommerfeld at sun dot com> wrote:

> These days, when a draft moves into the RFC editor queue, the RFC
> editor sends a request to the author to send in the xml2rfc input
> files if they exist.

Ironically, the *very next* message in my inbox after Bill's was just 
such a request from the RFC Editor, for draft-ietf-ltru-initial-06.