Subject: Graphic I-Ds and RFCs (Was: RE: RFCs In PDF Format?)

From: "Flanigan, Bill" <[email-masked]>
Date: Wed, 2 Dec 1998 12:19:39 -0500

Hello Ted,

	Closely reading and sending off detailed comments concerning a large
number of I-Ds over the past month or so, has led me to conclude (again)
that MOST IF NOT ALL authors can not meet your standard of "express(ing) it
clearly in English prose"!  Unless we hire a herd of English majors to
translate these complex and complicated technical documents into readable
English, Dick-and-Jane illustrations and graphics are about the only
recourse I can think of.  Let's face it:  our primary sense is vision, and
few of us technologists can really write well (and avoid an over abundance
of geekSpeak).  (I'm ignoring, for now, deliberate obfuscation which is also
part of the problem.)   
	If anything, illustrations might cause authors to revise their text,
since they may often find that they are unable to illustrate what they have
written.  Then there are the endless list threads that may be the result of
readers not being able TO SEE what authors are trying to get across.
Finally (but not leastly) we might to able to get implementations right the
second time because vendors and integrators would be able TO ENVISION what
the spec says (and doesn't say).

Best regards,
Bill

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
William F. Flanigan, Jr., Ph.D.       Voice:           (703) 681-2318
Defense Information Systems Agency      Fax:           (703) 681-2814 
Information Assurance Office (JED)      DSN:                      761      
5600 Columbia Pike, Room 632     Voice Mail:           (703) 681-2318   
Falls Church, VA 22041-2717        Internet:  <[email-masked]>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
> -----Original Message-----
> From:	Theodore Y. Ts'o [SMTP:[email-masked]]
> Sent:	Tuesday, December 01, 1998 7:48 PM
> To:	Thomas Dineen
> Cc:	[email-masked]; [email-masked]; [email-masked];
> [email-masked]; [email-masked]; [email-masked];
> [email-masked]
> Subject:	Re: RFCs In PDF Format?
> 
	[snip]

> 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.  
> 
	[snip]

> 						- Ted

---

From: Bob Stewart <[email-masked]>
Date: Wed, 02 Dec 1998 12:53:55 -0500

At 12:19 PM 12/2/98 -0500, Flanigan, Bill wrote:
>MOST IF NOT ALL authors can not meet your standard of "express(ing) it
>clearly in English prose"!

If you can't express a thought clearly in words and very simple pictures
(ASCII art) you don't understand what you mean well enough to put it in a
technical specification and expect anyone else to understand.

Writing clear English prose may be a rare skill but it is a required one.

Pictures do not necessarily clarify.  How often do you have to look at
words to know what an icon means?  Pictures may be worth a thousand words,
but they're often a different thousand words to different people.

	Bob

---

From: Bob Stewart <[email-masked]>
Date: Wed, 02 Dec 1998 12:53:55 -0500

Bob

---

From: Brant Knudson <[email-masked]>
Date: Thu, 03 Dec 1998 01:13:08 +0000

To my Esteemed Colleagues:

A simple way to add a figure to an I-D is to add the description of the figure
to the end of the document.

Here's the last page of an I-D where I cat'ed a file generated using the
"bitmap" program to the end of the file after adding a page break:

-----------Example

example-draft.txt                                              [Page 20]
^L
INTERNET-DRAFT             Hello, Bitmap I-D!              December 1998

This is the last line of text in this I-D.

^L
#define figure1_width 16
#define figure1_height 16
static unsigned char figure1_bits[] = {
   0x00, 0x00, 0x80, 0x03, 0x92, 0x02, 0xed, 0x7e, 0x01, 0xc0, 0x01, 0x80,
   0x49, 0xf7, 0x59, 0xa3, 0x6b, 0xa1, 0x49, 0xa7, 0x01, 0xc0, 0x06, 0x70,
   0x88, 0x21, 0x70, 0x1f, 0x00, 0x00, 0x00, 0x00};

-----------End of example (form feeds lost in translation)

"bitmap" is handy because it produces ASCII output.  If you were to save the
example text above and use "bitmap" on it you should see the sloppily-drawn
image appear. ("bitmap" is also used for X-Windows icons)

I don't think that "bitmap" is the best format, as compression would be
desirable.  Some type of run-length encoded bitmap format would work pretty
well.

Brant Knudson
[email-masked]

Paul Hoffman / IMC wrote:
>
> At 12:43 PM 12/2/98 -0500, Keith Moore wrote:
> >Part of the problem is that once you move away from ASCII text, you
> >split the "market" - none of the other formats, with the possible
> >exception of HTML, are widely used enough by the diverse interests
> >within IETF to be good candidates.
>
> I wanted to avoid this discussion, but I keep seeing "HTML" and "XML"
> suggested.
>
> Neither HTML or XML is a graphics format. They will give us better
> formatting for printing, but not pictures. I believe that all we *need* (if
> we need anything additional) is pictures, not nicer formatting.
>
> --Paul Hoffman, Director
> --Internet Mail Consortium

---

From: Brant Knudson <[email-masked]>
Date: Thu, 03 Dec 1998 01:13:08 +0000

-----------Example

^L
#define figure1_width 16

Brant Knudson
[email-masked]