Subject: Re: Source Format of RFCs

From: Gunnar Lindberg <[email-masked]>
Date: Tue, 1 Dec 1998 11:52:42 +0100 (MET)

A simple example: We all know there has to be a <Postmaster> on a
mail host. Why? Which RFC? See below. 110 Mbyte data on your laptop
and you have'm all. Try that with "richer" text...

A S C I I.
End of discussion.

laptoy% cd rfc

laptoy% du -s .
106384

laptoy% grep -i -l Postmaster rfc*.txt
rfc-index.txt
rfc822.txt
rfc876.txt
rfc1020.txt
rfc1062.txt
rfc1081.txt
rfc1117.txt
rfc1123.txt
rfc1138.txt
rfc1148.txt
rfc1166.txt
rfc1168.txt
rfc1173.txt
rfc1183.txt
rfc1211.txt
rfc1225.txt
rfc1327.txt
rfc1328.txt
rfc1386.txt
rfc1392.txt
rfc1465.txt
rfc1480.txt
rfc1506.txt
rfc1580.txt
rfc1617.txt
rfc1648.txt
rfc1649.txt
rfc1699.txt
rfc1709.txt
rfc1712.txt
rfc1713.txt
rfc1720.txt
rfc1780.txt
rfc1800.txt
rfc1846.txt
rfc1855.txt
rfc1880.txt
rfc1891.txt
rfc1894.txt
rfc1911.txt
rfc1912.txt
rfc1920.txt
rfc1983.txt
rfc2000.txt
rfc2076.txt
rfc2142.txt
rfc2156.txt
rfc2200.txt
rfc2249.txt
rfc2300.txt
rfc2319.txt
rfc2369.txt
rfc2400.txt
rfc2421.txt
rfc2442.txt

	Gunnar Lindberg

---

From: Antony Bowesman <[email-masked]>
Date: Tue, 01 Dec 1998 21:30:09 +0900

> and you have'm all. Try that with "richer" text...

Not just yet :)

> laptoy% grep -i -l Postmaster rfc*.txt

Well, how about fgrep -il postmaster rfc*.doc on Word documents
(although you would not want to forget the 'l').  That does the job and
would do the same for html.

ascii is very easy to manipulate but when wading through the likes of
rfc2445 (iCalendar) (8291 lines, 148 pages) some HTML would make life
much more useful.

When actually getting down to implement these things there is actually
no substitute for printing a copy out.  HTML could give a far more
readable document than the current form, with proportional fonts.  A
standard template could be created.  rfc2223 could be updated so authors
stick to the formatting rules.

As has been said before there is actually quite a benefit if diagrams
were able to be used for some of the more complex aspects of the text. 
This may cut out some of the misinterpretations implementors ocasionally
make.

Rgds
-- 
Antony Bowesman
[email-masked]

---

From: Antony Bowesman <[email-masked]>
Date: Tue, 01 Dec 1998 21:30:09 +0900

Not just yet :)

Rgds
-- 
Antony Bowesman
[email-masked]

---

From: "Perry E. Metzger" <[email-masked]>
Date: Tue, 01 Dec 1998 10:57:02 -0500

> rfc2445 (iCalendar) (8291 lines, 148 pages) some HTML would make life

That is a problem with the standard in question, not with the format
in which it is expressed.

Perry

---

From: "Perry E. Metzger" <[email-masked]>
Date: Tue, 01 Dec 1998 10:57:02 -0500

Perry

---

From: [email-masked] (Claus André Färber)
Date: 01 Dec 1998 17:49:00 +0100

> and you have'm all. Try that with "richer" text...

No. Having a mandatory ASCII version is OK. However, having a richer  
format in addition is not bad either.

BTW, grep would equally work with an XML-derieved markup language.
An XML language would also have the advantage that _anyone_ could  
produce fancier formats in their favourite style/format by using an  
approprate stylesheet.

--
Claus Andre Faerber <http://www.faerber.muc.de>
PGP: ID=1024/527CADCD FP=12 20 49 F3 E1 04 9E 9E  25 56 69 A5 C6 A0 C9 DC

---

From: [email-masked] (Claus André Färber)
Date: 01 Dec 1998 17:49:00 +0100

---

From: Keith Moore <[email-masked]>
Date: Tue, 01 Dec 1998 16:01:01 -0500

> produce fancier formats in their favourite style/format by using an  

this is an advantage?

---

From: Keith Moore <[email-masked]>
Date: Tue, 01 Dec 1998 16:01:01 -0500

this is an advantage?

---

From: "Perry E. Metzger" <[email-masked]>
Date: Tue, 01 Dec 1998 16:13:51 -0500

> format in addition is not bad either.

Here are the arguments I've seen in favor of non-ASCII:

1) "Better" diagrams and tables. Frankly, though, the diagrams we have
now are just fine.
2) "Better formatting makes things more readable". I can't see that
the current versions are particularly hard on the eyes. I've very
rarely read RFCs on paper in many years, btw.

So do we really want to spend lots of time and energy debating all
this so that we can have "better" diagrams and tables and "more
readable" text?

If you want, you can easily write an automated tool to turn the
existing RFCs into postscript that uses proportional fonts, and
substitutes "real" diagrams for the ASCII art. I leave doing so as an
exercise to the reader. It would take you an afternoon to do in PERL.

Perry

---

From: "Perry E. Metzger" <[email-masked]>
Date: Tue, 01 Dec 1998 16:13:51 -0500

Perry

---

From: Tripp Lilley <[email-masked]>
Date: Tue, 1 Dec 1998 18:03:32 -0500 (EST)

> rarely read RFCs on paper in many years, btw.

You leave out several others mentioned in this thread:

* better searching and indexing
* better management of inter-document relationships
* better management of versions/revisions of documents
* more uniform support for internationalization (should such be desired)

And in your response to both points above, what may be "just fine" for you
is intolerable, or at least frustrating, for others. Though I've not
written RFCs, I /have/ spent way too much time on damned ASCII diagrams
for other technical specs, when a few minutes in Visio, Corel, or
something GNUish would've served me much better.

Personally, I care more about adding useful metadata to the documents than
any of the formatting issues, but they happen to be a big bonus that comes
along with using a structured document format.

------------------------------------------------------------------------------
Tripp Lilley, Innovative Workflow Engineering, Inc. ([email-masked])
------------------------------------------------------------------------------
         "Given enough eyeballs, all bugs are shallow" -- Linus's Law

---

From: Tripp Lilley <[email-masked]>
Date: Tue, 1 Dec 1998 18:03:32 -0500 (EST)

---

From: "Perry E. Metzger" <[email-masked]>
Date: Tue, 01 Dec 1998 19:42:20 -0500

> * better searching and indexing

fgrep seems to work just fine.

> * better management of inter-document relationships

fgrep rfc-index

> * better management of versions/revisions of documents

There only *is* one version of any given RFC.

> * more uniform support for internationalization (should such be desired)

RFCs are written in English only.

Anyway, I think this has been beaten to death, and as usual, ASCII
still seems to remain the format of choice.

Perry

---

From: "Perry E. Metzger" <[email-masked]>
Date: Tue, 01 Dec 1998 19:42:20 -0500

fgrep rfc-index

Perry

---

From: "Theodore Y. Ts'o" <[email-masked]>
Date: Tue, 1 Dec 1998 20:11:58 -0500

Date: Tue, 1 Dec 1998 18:03:32 -0500 (EST)
   From: Tripp Lilley <[email-masked]>

All of the rich text format's which I've seen have searching and
indexing which is more inconvenient, less useful, and slower than:

	grep <regexp> rfc*.txt

Yes, you can click on a hot-link and go to another document.  Yawn....

One of the *features* of RFC's is that there aren't multiple versions of
an RFC.  Once an RFC is published, it doesn't change.  You can obsolete
an RFC with a new RFC, but it has a new number.  This is useful, because
people understand "This product complies with RFC-1234".

They don't understand: "This product complies with version 1.5.123.54.5
of RFC-1234".

Keep in mind that many of the so-called advantages of WYSIWYG and rich
text systems also have distinct disadvantages.  I think it was Bellcore
which did a study showing that when comparing WYSIWYG systems to the old
fossilized nroff system, the actual quality of the text when *down*, not
up.  (Because of course, people worried about whether or not the text
looked pretty, instead of what it actually *said*.)

I also heard a story (which I would love to get confirmed) that McNealy
banned the use of Powerpoint presentations at Sun, saying that flashy
slides only made it easier to sneak by sloppy thinking, and didn't add
any real value to internal discussions.  Whether or not it's true, the
point is certainly valid, and it's one which Marketing departments the
world over have depended upon.  

Yes, Rich Text Formats and Structured Text Formats have lots of neat
features.  Personally, I've yet to be convinced any of those features
really add enough value to for the specifical requirements of IETF
standards documents to make up for their numerous disadvatnages.

						- Ted

---

From: "Theodore Y. Ts'o" <[email-masked]>
Date: Tue, 1 Dec 1998 20:11:58 -0500

grep <regexp> rfc*.txt

						- Ted

---

From: Fred Baker <[email-masked]>
Date: Tue, 01 Dec 1998 17:41:37 -0800

>There only *is* one version of any given RFC.

Really? To be sure, there is only one *current* version of a specification,
and we identify it with a unique RFC number, but if you ask the question
another way, we have as many versions as anyone else. How many versions of
the OSPF specification have existed, N-1 of which have been obsoleted by a
newer RFC? Or the PPP Specification, or SNMP?

We have a version control issue as much as anyone else does. We identify
versions by saying "RFC xxxx, which obsoleted RFC yyyy" rather than "the
1984 version of X.NN" or "draft 167 of ABC XYZ 1234". The syntax is
different, but the semantic content is about the same.

>still seems to remain the format of choice.

Consensus, or proof that "the other guy is wrong", has been announced a
couple of times today, and with all due respect, I am not sure I agree. I
don't see, in this discussion, a consensus around ASCII. I see one group
that has a consensus around ASCII (one that I'm about 80% a member of), and
a group that would suggest anything but ASCII (with which I have sympathy
any time I want to draw a picture). The second group's only real weakness
is in their form of argument: they didn't start out by deriving a set of
requirements we all agreed with and then showing that ASCII didn't meet
their requirements, and go on to peruse and discard a number of other
formats, to arrive at one or two that they felt did; they started out
saying what they didn't want, and throwing out a lot of alternatives, which
got shot down.

I personally am fine with ASCII, for all the reasons mentioned today. But I
have sympathy for the folks that want a better way to handle drawings.
Maybe one of them could take the discussion a little further, by capturing
the set of requirements that were kicked around today - both sides - and do
an honest evaluation of several alternatives.

I would start with this as a requirement set; go through today's archive
and you will probably find several that I missed.

  - it needs to be readily accessible to college students and others
    of relatively limited funds. That can be through student discounts,
    I think, but "free" is a word that comes quickly to mind.
  - "it", in this context, is both the capability to create the file
    and to read it.
  - "it" has to be readily available on a variety of operating systems,
    including at minimum MacOS, Windows 95/98, Windows NT, Solaris,
    BSD Unix, and Linux - both the create and the read capabilities.
  - it has to have good search capabilities, including both searching 
    individual documents and in searching and comparing sets of them. 
    An example that was recently important was the comparison of two 
    documents to isolate potentially plagiarized text.
  - it has to be readily able to have machine-readable components 
    extracted from it
  - it should be editable - one should be able to take the readable 
    version, edit it directly, and produce another readable version.
  - change bars...
  - it has to deal well with tables and pictures, the former in a 
    non-opaque manner.
  - it needs to have limited storage requirements.
  - it also has to deal well with outline-formatted documents, including
    automatic heading management
  - it needs capabilities to improve readability (even old RFCs have
    bold text, sometimes done by having the line printer back up and 
    overprint)

Having done the analysis, publish an internet draft containing it and make
a recommendation based on it to the IETF. I'm willing to see a 90% solution
(we do a lot of 90% solutions), but I'm not going for hand waving about
things that should maybe show up some day. Let's have a serious discussion
on the subject.

---

From: Fred Baker <[email-masked]>
Date: Tue, 01 Dec 1998 17:41:37 -0800

---

From: "Mitch Denny" <[email-masked]>
Date: Wed, 2 Dec 1998 12:56:17 +1000

Unix type annotation of an email is not debate,
it is just pointing out how we do it _currently_.

We should always explore ways to make recoving
information better.

In a world were we all strive to make systems
better for our end-users, perhaps we should afford
ourselves the luxury of not having to use a one
dimensional listing of our technical resources.

I for one advocate the use of rich formats in
documents.  A picture speaks a thousand words,
and for those authors that can't write a coherent
scrap (many of us are guilty, I am raising my hand),
it is a good way to get our point across.

Attention will just have to be paid to ensuring
that the documents remain readily accessible.

Cheers,

Mitch Denny
[email-masked]

> -----Original Message-----
> From: Perry E. Metzger [mailto:[email-masked]]
> Sent: Wednesday, December 02, 1998 10:42
> To: Tripp Lilley
> Cc: Perry E. Metzger; [email-masked]
> Subject: Re: Source Format of RFCs
>
>
>
> Tripp Lilley writes:

---

From: "Mitch Denny" <[email-masked]>
Date: Wed, 2 Dec 1998 12:56:17 +1000

Cheers,

Mitch Denny
[email-masked]

---

From: "N�rman W�dders" <[email-masked]>
Date: Wed, 2 Dec 1998 13:05:59 +1000 (GMT)

Please leave the RFC's in ascii format... and lets move on :)

$0.02c

--Norman Widders

---

From: "N�rman W�dders" <[email-masked]>
Date: Wed, 2 Dec 1998 13:05:59 +1000 (GMT)

$0.02c

--Norman Widders

---

From: Matt Holdrege <[email-masked]>
Date: Tue, 01 Dec 1998 22:58:14 -0800

>things that should maybe show up some day. Let's have a serious discussion

ASCII is our 90% solution. Why can't we stick with what we have and allow
an additional alternative format for authors who wish to add pictures?

The text is what we are standardizing. ASCII is good enough for that. The
pictures are for elucidation and should be optional. Since it's optional,
leave it up to the author to publish in whatever format they want. If I'm
an author of a draft and I want to include a picture to describe something,
I might include a Word, ps, PDF or XXX format file as I see fit.

This way the IETF doesn't have to deal with the mess of choosing one of
these formats. The author is the one responsible for generating the draft
and the ideas behind the draft. So let the author choose whatever format
they want. If the author chooses some obscure format that only a small
percentage can read, then they hurt the chances of their draft being
adopted. However, everyone can read the text portion of the draft which is
what really counts.

But if the IETF chooses a mandatory format, they hurt everyone who doesn't
like or doesn't have that format readily available. The other problem with
having the IETF choose the format is that popular formats can change. If
the IETF picks say PDF today, what happens if some new PDF++ format comes
out in a year or two? Do we revisit this whole thing again?

I'm not sure if this is right for RFC's which should probably be in a
common format, but I believe it's the best choice for I-D's.

So Fred, after a (not so) lengthy analysis, here is my I-D on the topic:

Internet Engineering Task Force                               Matt Holdrege
INTERNET-DRAFT				             Ascend Communications    
draft-holdrege-rfc-graphics-00.txt                          
1 December 1998			                     Expires: 1 June 1999

                  HOW TO ADD GRAPHICS TO AN INTERNET DRAFT

Abstract: blah
Introduction: blah

What to do: Internet Drafts must be in an ASCII format as defined in RFC
2223. If you wish to add graphics to your draft for whatever reason, you
may add a second (or N) file(s) to your original ASCII draft. You must
include the file type in the file-spec. Examples using this draft filespec
are:

draft-holdrege-rfc-graphics-pdf-00.txt
draft-holdrege-rfc-graphics-msword-00.txt
draft-holdrege-rfc-graphics-ps-00.txt

You may submit a graphics file at any time, but it must follow it's
companion ASCII file in the same format so the IETF can publish them
together like...

draft-holdrege-rfc-graphics-00.txt
draft-holdrege-rfc-graphics-pdf-00.txt

If you update the text portion of your draft, you may or may not desire an
update to the graphics portion. But you should generate a new filespec
anyway to keep the drafts together. Like...

draft-holdrege-rfc-graphics-01.txt
draft-holdrege-rfc-graphics-pdf-01.txt

Author: Me

				THE END

If folks agree, I can flesh this out. :)

---

From: Matt Holdrege <[email-masked]>
Date: Tue, 01 Dec 1998 22:58:14 -0800

Abstract: blah
Introduction: blah

Author: Me

				THE END

---

From: "mark.paton" <[email-masked]>
Date: Wed, 2 Dec 1998 07:58:56 -0000

Good solution

-----Original Message-----
From: Matt Holdrege [mailto:[email-masked]]
Sent: 02 December 1998 06:58
To: Fred Baker
Cc: [email-masked]
Subject: Re: Source Format of RFCs 

Abstract: blah
Introduction: blah

Author: Me

				THE END

-
This message was passed through [email-masked], which
is a sublist of [email-masked]. Not all messages are passed.
Decisions on what to pass are made solely by Harald Alvestrand.

---

From: "mark.paton" <[email-masked]>
Date: Wed, 2 Dec 1998 07:58:56 -0000

Good solution

-----Original Message-----
From: Matt Holdrege [mailto:[email-masked]]
Sent: 02 December 1998 06:58
To: Fred Baker
Cc: [email-masked]
Subject: Re: Source Format of RFCs 

Abstract: blah
Introduction: blah

Author: Me

				THE END

-

---

From: Lloyd Wood <[email-masked]>
Date: Wed, 2 Dec 1998 09:22:12 +0000 (GMT)

> documents.  A picture speaks a thousand words,

... and we can all look forward to seeing digitised author photographs
in informational RFCs, too.

A picture may speak a thousand words, but precision of technical
speech leads to brevity. 

L.

<[email-masked]>PGP<http://www.ee.surrey.ac.uk/Personal/L.Wood/>

---

From: Lloyd Wood <[email-masked]>
Date: Wed, 2 Dec 1998 09:22:12 +0000 (GMT)

L.

---

From: Ted Lemon <[email-masked]>
Date: Wed, 02 Dec 1998 10:51:56 -0500

> I might include a Word, ps, PDF or XXX format file as I see fit.

These are standards, not technical books.  If the picture is genuinely
optional, you should just leave it out - it serves no purpose.  If
your text isn't clear enough to eliminate the need for the picture,
work on the text.  If you really _need_ a picture, then you can't
leave it out - it's part of the standard, and that's the end of it.
But I can't think of any IETF standards for which ASCII art isn't
sufficient.

My suspicion is that if there were a well-defined, well-supported rich
text format that included the ability to describe or include pictures,
and that had Open Source tools that really worked well, and those
tools were in the hands of a lot of RFC authors, and those authors
found the tools usable, then people would start to think it was
sensible to use them.  Unfortunately, that is not the current state of
the art.

IETF is the most open (in the real sense, not the marketing sense)
standards body I know of.  ASCII is the _only_ universally-supported
open standard for the interchange of documentation of which I am
aware.  If you want to change that, stop arguing and change it.
There's no sense arguing about it on this mailing list until after the
situation has changed.   So please stop!

			       _MelloN_

---

From: Ted Lemon <[email-masked]>
Date: Wed, 02 Dec 1998 10:51:56 -0500

_MelloN_

---

From: [email-masked]
Date: Wed, 2 Dec 1998 08:55:12 -0800 (PST)

> But I can't think of any IETF standards for which ASCII art isn't

I believe that the first case where ascii was not considered the
authoritative RFC source was for RFC 1119 and its successors. This was 
because the math representation and had little to do with pictures.

-- 
--bill

---

From: [email-masked]
Date: Wed, 2 Dec 1998 08:55:12 -0800 (PST)

-- 
--bill

---

From: "Michael K. Sanders" <[email-masked]>
Date: Wed, 02 Dec 1998 13:50:02 -0700

>world over have depended upon.  

Quoted from:

  <URL:http://www.mercurycenter.com/business/docs/mcnealy012698.htm>

    McNealy:

    ...

    We had 12.9 gigabytes of (Microsoft) PowerPoint slides on our
    network. And I thought, ''What a huge waste of corporate
    productivity.'' So we banned it. And we've had three unbelievable
    record-breaking fiscal quarters since we banned PowerPoint. Now, I
    would argue that every company in the world, if they would just
    ban PowerPoint, would see their earnings skyrocket. Employees
    would stand around going, ''What do I do? Guess I've got to go to
    work.'' 

The rest of it is quite interesting reading as well.

---

From: "Michael K. Sanders" <[email-masked]>
Date: Wed, 02 Dec 1998 13:50:02 -0700

Quoted from:

    McNealy:

    ...

---

From: "Mitch Denny" <[email-masked]>
Date: Thu, 3 Dec 1998 09:19:13 +1000

Lloyd,

It is a typical statement that you have just made,
the purpose of a technical document is to explain
a concept the best way possible.  It is used
to expand the understanding of the reader.

I for one would appreciate a few graphical
interpretations of documents which are often
not written well.

This brings me to my next point (if I had a first),
documents are generally not well written, they
assume a level of intimacy with the subject which
often is not present.

An graphic of the author may not be a bad idea,
at least when we attend the IETF confrences we
can spot the person and talk to them if you
are interested in their subject matter - its
more natural to look for a face than walk
around a crowded room opening up peoples wallets
looking for their drivers licence or other forms
of identification.

Imagine a video format describing the packet flow
around a Token ring network.

Ofcourse this would be suplimented by good 
technical documentation.  We don't have one to
the exclusion of the other.

Cheers,

Mitch Denny
[email-masked]

> From: Lloyd Wood [mailto:[email-masked]]
> Sent: Wednesday, December 02, 1998 19:22
> To: Mitch Denny
> Cc: IETF-0000
> Subject: RE: Source Format of RFCs 
> 
>

---

From: "Mitch Denny" <[email-masked]>
Date: Thu, 3 Dec 1998 09:19:13 +1000

Lloyd,

Cheers,

Mitch Denny
[email-masked]

---

From: Lloyd Wood <[email-masked]>
Date: Thu, 3 Dec 1998 09:23:20 +0000 (GMT)

> to expand the understanding of the reader.

By this definition, every junior school textbook is a technical
document. Somehow, I don't think so.

There's a difference between explaining a standard clearly and without
ambiguity to provide a definitive reference, and educating the reader. 
A number of informational RFCs blur this distinction, however. 

> assume a level of intimacy with the subject which

No document is complete. If intimacy is lacking you need other
documents from elsewhere.

> looking for their drivers licence or other forms

I believe nametags were invented for this...

Ideally, the number of people attending IETF meetings is a 
small fraction of those reading and using the standards
for implementations.

L.

---

From: Lloyd Wood <[email-masked]>
Date: Thu, 3 Dec 1998 09:23:20 +0000 (GMT)

L.

---

From: "Mitch Denny" <[email-masked]>
Date: Fri, 4 Dec 1998 09:20:29 +1000

Lloyd,

What is the point of a technical doucment
unless it educates?  Does anyone agree
with me here?

If the technical document doesn't educate
and provide _useful_ information to the
reader than it is nothing more than
an ego booster for the author.

Maybe you are right, maybe the term RFC
should be taken literally, Request for
Comments.  Where an author can publish
and incomplete document, get it attacked
or praised, then go an re-draft a new one.

This is pretty much what happens now, can
we not improve it?

> No document is complete. If intimacy is 
> lacking you need other documents from 
> elsewhere.

Excuse me? I thought you said that they
were supposed to be a definitive reference?

As for the point about photo's, it was really
in jest, but seen as we are on the subject,
what size text can you read from 15 metres?

Cheers,

Mitch Denny
[email-masked]

> Sent: Thursday, December 03, 1998 19:23
> To: Mitch Denny
> Cc: IETF-0000

---

From: "Mitch Denny" <[email-masked]>
Date: Fri, 4 Dec 1998 09:20:29 +1000

Lloyd,

Cheers,

Mitch Denny
[email-masked]