Subject: RFCs In PDF Format?

From: Thomas Dineen <[email-masked]>
Date: Tue, 1 Dec 1998 14:17:13 -0800 (PST)

Gentle People:

   Setting the concept of Mediocrity aside for a moment,
why do we not consider another issue?

   Consider using pdf format for your RFCs. Your application is
exactly what it was designed for.
   
   PDF format allows for the integration of text and graphics into
a single document.

   PDF reader software is available free from Adobe and is
included in Microsoft Office.

   Yes you will have to purchase the write or distiller software.
Some word processing packages do include this.

   Now I know some detest this but other organizations such as the
IEEE 802 use pdf format for electronic distribution of standards and
drafts. By the way as a voting member I can attest that it works
great.

   As for Mediocrity, remember you probably received this e-mail
via an IEEE 802 LAN! It was sent via an IEEE 802.3 LAN!

Thomas Dineen

---

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

Sigh, we've been through this before; PDF is a wonderful portable format
for printing documents.

The Acrobot reader (at least the free one from Adobe), is awful, and
while I will read an ASCII text document on-line using emacs, the only
thing I'll do with a PDF document that I need to carefully read and
digest is to print it out, even if it kills a couple of trees in the
process.

ASCII files are easily searchable, are more compact, and with a little
discipline on the part of the original author, there is little advantage
for putting in whiz-bang graphics into the standards document.  This are
after all technical protocol specifications, not marketing white papers!

With very few exceptions (the NTP RFC being the only one that comes to
mind), if you can't express it clearly in English prose, and instead
have to rely on a graphic, you probably are thinking fuzzily about the
subject, and should think harder about it before publishing the
standard, since otherwise the standard itself may be ambiguous.  After
all, C compilers aren't impressed by GIF or JPEG images.  :-)

						- Ted

---

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

- Ted

---

From: Fred Baker <[email-masked]>
Date: Wed, 02 Dec 1998 22:55:03 -0800

At 07:47 PM 12/1/98 -0500, Theodore Y. Ts'o wrote:
>subject...

I'm not sure I agree with that. Consider how many RFCs contain pictures
like the ones I sent to the end2end-interest list the other day:

>Following that, I have zero or more - I'm not sure what to call them, but
>maybe they are requests and responses. They are in essence
>Type-Length-Value constructs that have some semantic content. I'll list
>them, and identify specific issues that they address. They each have this
>format:
>
>	0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
>	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>	|   enumerator  |///////////////|    Length of TLV (>= 4)       | 
>	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>	|	data content						|
>
>So here they are:
>
>OPEN REQUEST/RESPONSE
>
>	0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
>	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>	|   OPEN R/RQ   |///////////////|    8                          | 
>	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>	|	MSS in octets  						|
>	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Yes, those could be expressed in a number of other ways, such as:

	object enumerator: 8 bit unsigned integer
	unused space, must be zero: 8 bits
	length of object: 16 bit unsigned integer
	mss of connection: 32 bit unsigned integer

In fact, one often finds both together. Now I ask: why do we do the
picture? Answer: because it makes the concept clearer for the human reader.
I would be a little offended if you accused me of fuzzy thinking because I
used a graphic way to describe the object instead of or in addition to the
equivalent English prose. There are other things in the proposed
specification (which is all prose) that may well result from fuzzy
thinking, but this seems pretty objective.

Another place where we extensively use pictures is in tables. A classic
example is in RFC 911, in which the EGP state machine is summarized in a
table. Like the above, the significant difference between a table set forth
in ASCII and a table set forth in a Framemaker, MS Word, or HTML table is
the ease of creating, maintaining, and reading the text (I think HTML calls
them "frames"). Having built such tables, I think we'll all agree that the
word processor's form is a lot easier to deal with, and is often easier for
the implementor to read. The big objection in this case relates to tables
that are stored as opaque objects - the tables want to be searchable like
any other text. Tables are, generally speaking, the thing you do to
definitively avoid fuzzy thinking.

The third place is in examples. Here, I would agree that dependence on the
example to specify the protocol is poor form, for a set of reasons.
However, anyone who has read the OSPF specification will tell you that the
examples materially aid in understanding the details of the protocol, even
though the text description adequately specifies them without the examples.
While we don't want to depend on examples as a specification, I can think
of a number of RFCs that are materially easier to understand because of the
presence of pictures. They don't imply fuzzy thinking at all.

The fourth, mentioned a couple of times in this thread, is equations. It is
possible to do equations in ASCII, but the summation and integral signs, if
comprehensible at all, are true works of ASCII art.

---

From: Fred Baker <[email-masked]>
Date: Wed, 02 Dec 1998 22:55:03 -0800

---

From: "Martin J. Duerst" <[email-masked]>
Date: Sat, 19 Dec 1998 09:32:38 +0900

At 22:55 98/12/02 -0800, Fred Baker wrote:

> them "frames").

HTML tables and HTML frames are different things. HTML tables are tables as
you describe them. HTML frames are a way to put more than one HTML page into
the same browser window, splitting the browser window. Tables are part of
HTML 4.0 strict; frames are defined in HTML, but only in the "Frameset" DTD
(http://www.w3.org/TR/html40/sgml/framesetdtd.html).

Frames have various problems, such as accessibility, the fact that it's
impossible to capture a frame state in an URI, and the fact that many
frame constructs, once in the browser, don't go away even if you load
something completely different.

For RFCs, I would definitely suggest to allow tables, but not frames.

Regards,   Martin.

#-#-#  Martin J. Du"rst, World Wide Web Consortium
#-#-#  mailto:[email-masked]   http://www.w3.org

---

From: "Martin J. Duerst" <[email-masked]>
Date: Sat, 19 Dec 1998 09:32:38 +0900

Regards,   Martin.

---

From: "Mitch Denny" <[email-masked]>
Date: Mon, 21 Dec 1998 09:19:15 +1000

Ye All,

I aggree, HTML frames being used my inexperienced/bad
HTML authors leads to very complex/ugly documents.

When/If we move to HTML I would recommend that the IETF
distributes a template for formatting using very
well constucted formatting in the actual code of the table.

There should be a recommended format.

If I get a chance this week I will convert an existing
RFC to a HTML formatted document that I believe would
be a tight and suitable structure.

Can anyone recommend a document with SOME, but not
heaps of graphics as I don't want to have to
create too many of them.

Cheers,

Mitch Denny
[email-masked]

> -----Original Message-----
> From: Martin J. Duerst [mailto:[email-masked]]
> Sent: Saturday, December 19, 1998 10:33
> To: Fred Baker
> Cc: Theodore Y. Ts'o; [email-masked]
> Subject: Re: RFCs In PDF Format?
>
>

---

From: "Mitch Denny" <[email-masked]>
Date: Mon, 21 Dec 1998 09:19:15 +1000

Ye All,

Cheers,

Mitch Denny
[email-masked]