Subject: RE: Diagrams (Was RFCs should be distributed in XML)

From: "Gray, Eric" <[email-masked]>
Date: Mon, 14 Nov 2005 17:32:41 -0200

Stewart,

	I suspect most people prefer reading documents that contain
diagrams, but anything that limits the complexity of a diagram -
especially for documents most often read on a computer screen - is
a feature, rather than a bug.

	If a diagram is included to communicate (rather than obscure) 
an idea, then readers should be able to correlate descriptive text 
to the diagram - either because the diagram is simple enough that
it is not necessary to keep referring to it, or because the entire
description can be viewed while looking at the diagram.

	Sometimes language limitations are a good thing, when they
are tied to specific ways of presenting information.

--
Eric

--> -----Original Message-----
--> From: [email-masked] [mailto:[email-masked]] 
--> On Behalf Of Stewart Bryant
--> Sent: Monday, November 14, 2005 2:09 PM
--> To: Andrew Sullivan
--> Cc: [email-masked]
--> Subject: Re: Diagrams (Was RFCs should be distributed in XML)
--> 
--> 
--> 
--> Andrew Sullivan wrote:
--> 
--> > On Mon, Nov 14, 2005 at 06:03:07PM +0200, Jari Arkko wrote:
--> > 
--> >>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
--> > 
--> 
--> 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
--> 
--> 
--> _______________________________________________
--> Ietf mailing list
--> [email-masked]
--> https://www1.ietf.org/mailman/listinfo/ietf
--> 

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

---

From: "Yaakov Stein" <[email-masked]>
Date: Tue, 15 Nov 2005 10:10:21 +0200

> 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.

So all we have to do to get "screen quality" diagrams in an ID 
is to ask the reader to print out 140 pages covered with Xs, 
set them out on the ground 14 by 10,
and view them from a rather tall tower.

Who said that ASCII characters are constraining?

Y(J)S

---

From: "Hallam-Baker, Phillip" <[email-masked]>
Date: Tue, 15 Nov 2005 09:10:22 -0800

Watching engineers implement specs as code I note that most use
secondary sources such as O'Rielly in preference to the supposedly
authoritative IETF specs. The lack of readability is a major reason.

This is not the case with W3C specs. 

There is very little point spending time perfecting text that is only
ever going to be read by the author of the O'Rielly nutshell book.

The real standard is the bits on the real wire. If those are coded from
O'Rielly then O'Rielly, not the IETF is the standards setter.

I don't recall seeing ASCII art in O'Rielly books.

Leave the ASCII art for recreational use. If you want to be regarded as
a professional organization then make sure that every communication
looks professional. ASCII art screams 'amateur'.

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On 
> Behalf Of Lars-Erik Jonsson (LU/EAB)
> Sent: Tuesday, November 15, 2005 9:19 AM
> To: Gray, Eric; Stewart Bryant
> Cc: [email-masked]
> Subject: RE: Diagrams (Was RFCs should be distributed in XML)
> 
> Very well stated!!!
> 
> The ASCII-requirement is (apart from being a compact, 
> generic, free, non-complex, document format) indirectly 
> forcing people to really make diagrams simple, i.e. not put 
> too much crap (complexity) in one single figure.
> 
> After having had to read documents from other organisations 
> people often cite as "SDO's", I am personally convinced that 
> the good sides of using ASCII completely outweights the 
> potential negative aspects.
> 
> /L-E
> 
>  
> > Stewart,
> > 
> > 	I suspect most people prefer reading documents that 
> contain diagrams, 
> > but anything that limits the complexity of a diagram - 
> especially for 
> > documents most often read on a computer screen - is a 
> feature, rather 
> > than a bug.
> > 
> > 	If a diagram is included to communicate (rather than 
> obscure) an 
> > idea, then readers should be able to correlate descriptive 
> text to the 
> > diagram - either because the diagram is simple enough that 
> it is not 
> > necessary to keep referring to it, or because the entire 
> description 
> > can be viewed while looking at the diagram.
> > 
> > 	Sometimes language limitations are a good thing, when 
> they are tied 
> > to specific ways of presenting information.
> > 
> > --
> > Eric
>

---

From: Bob Braden <[email-masked]>
Date: Tue, 15 Nov 2005 09:20:16 -0800 (PST)

*> 
  *> Watching engineers implement specs as code I note that most use
  *> secondary sources such as O'Rielly in preference to the supposedly
  *> authoritative IETF specs. The lack of readability is a major reason.
  *> 
  *> This is not the case with W3C specs. 
  *> 
  *> There is very little point spending time perfecting text that is only
  *> ever going to be read by the author of the O'Rielly nutshell book.
  *> 
  *> The real standard is the bits on the real wire. If those are coded from
  *> O'Rielly then O'Rielly, not the IETF is the standards setter.
  *> 
  *> I don't recall seeing ASCII art in O'Rielly books.
  *> 

I am certainly not going to claim that ASCII art is God's Gift to
Implementers, but I have a hard time believing that the alleged
superiority of the O'Reilly specs is due to the artistic quality
of their diagrams, as opposed, say, to the quality of their prose.

  *> 
  *> Leave the ASCII art for recreational use. If you want to be regarded as
  *> a professional organization then make sure that every communication
  *> looks professional. ASCII art screams 'amateur'.

I'm sorry, that is nonsense.  Was Jon Postel an amateur?

Fancy pictures CAN be a help for some explanatory purposes, but they
can also distract from a poorly written description.

Bob Braden

---

From: "Gray, Eric" <[email-masked]>
Date: Wed, 16 Nov 2005 15:58:39 -0200

Marshall,

	That may be true, but it has long been the case that a
state-machine may completely and accurately be defined as a
(relatively) simple symbolic expression - requiring no figure
at all.  Assuming that such an expression is included in the
normative text, then reference to an illustrative figure would 
be an appropriate non-normative reference.

--
Eric

--> -----Original Message-----
--> From: [email-masked] [mailto:[email-masked]] 
--> On Behalf Of Marshall Eubanks
--> Sent: Wednesday, November 16, 2005 11:00 AM
--> To: Stewart Bryant
--> Cc: Lars-Erik Jonsson (LU/EAB); [email-masked]
--> Subject: Re: Diagrams (Was RFCs should be distributed in XML)
--> 
--> Hello;
--> 
--> I suspect that there is a lot more reliance of non-ASCII 
--> art out there than is officially admitted.
--> 
--> I do not know how, for example, you can  understand the 
--> PIMv2 state machine without reference to the (non-ASCII) 
--> diagrams provided in the
--> (non-ASCII) version of the draft.
--> 
--> Regards
--> Marshall Eubanks
--> 
--> On Nov 16, 2005, at 7:29 AM, Stewart Bryant wrote:
--> 
--> > It's interesting that when authors turn up at IETF to 
--> explain their 
--> > work/resolve issues etc they use colored diagrams to do 
--> so - not ASCII 
--> > art.
--> >
--> > Some of this is fashionable, but in many cases it is to clearly 
--> > articulate a point in the very little time made available.
--> > I don't see why such powerful techniques shouldn't be 
--> applied to the 
--> > specifications themselves to allow the reader to most 
--> grasp what is 
--> > being said with the minimum effort.
--> >
--> > I am afraid that I don't subscribe to the hair shirt approach to 
--> > drawings. I think that they should be exactly fit for 
--> purpose neither 
--> > too complex, nor too simple, and that the need to work round the 
--> > limits of 72 ASCII characters should not be a constraint 
--> that limits 
--> > the clarity of expression.
--> >
--> > For example look at slides 5 and 6 in
--> > http://www3.ietf.org/proceedings/05nov/slides/pwe3-2.ppt
--> >
--> > and compare to figure1 in
--> > http://www.ietf.org/internet-drafts/draft-balus-bocci-martini-dyn-
--> > ms-pwe3-00.txt
--> >
--> > The latter shows the components of the system, but it is 
--> impossible to 
--> > put the detail shown in the slides into the diagrams in the 
--> > specification itself with our current tools.
--> >
--> > Look at the figures in
--> > http://www.ietf.org/internet-drafts/draft-bocci-bryant-pwe3-ms-pw-
--> > arch-01.txt
--> > particularly figure 8. We are at the limit of what we can 
--> describe in 
--> > these diagrams.
--> >
--> > I can also find examples in the IP Fast Re-route work where we 
--> > struggle to show network snippets in ASCII with the associated 
--> > addressing and subsequent tunneling, and yet the 
--> operation is simple 
--> > to show in ppt, pdf, etc etc, particularly with colour.
--> >
--> > Another example - many of the ideas that we talk about in 
--> the IETF 
--> > start life as a few coloured lines on a large whiteboard 
--> - because 
--> > that is the simplest way to visualise these ideas and to 
--> express them 
--> > for the first time to our peers. That style of expression 
--> therefore 
--> > seems to the specifications themselves and for exactly 
--> the same reason 
--> > - clarity.
--> >
--> > Perhaps it is because the work that I do is mainly on 
--> overlay network 
--> > techniques where it is necessary to describe how the 
--> virtual network 
--> > maps onto the physical network that I find difficulty 
--> producing clear 
--> > ASCII art, but I would be surprised if I were alone in that view.
--> >
--> > If we think that ASCII art is all that is needed, perhaps - as an 
--> > experiment - we should forbid the use of anything other 
--> than ASCII art 
--> > in presentations at the next IETF?
--> >
--> > - Stewart
--> >
--> >
--> >
--> > _______________________________________________
--> > Ietf mailing list
--> > [email-masked]
--> > https://www1.ietf.org/mailman/listinfo/ietf
--> 
--> 
--> _______________________________________________
--> Ietf mailing list
--> [email-masked]
--> https://www1.ietf.org/mailman/listinfo/ietf
-->

---

From: "Gray, Eric" <[email-masked]>
Date: Thu, 17 Nov 2005 14:17:13 -0200

Yaakov,

	Funny. Ha ha.

	The big distinction is that very few people can read 
Morse code.  Can you?

--
Eric 

--> -----Original Message-----
--> From: [email-masked] [mailto:[email-masked]] 
--> On Behalf Of Yaakov Stein
--> Sent: Thursday, November 17, 2005 1:48 AM
--> To: Stewart Bryant; Masataka Ohta; [email-masked]
--> Subject: RE: Diagrams (Was RFCs should be distributed in XML)
--> 
-->  
--> >It's good that protocols needing more than 72 ASCII characters are 
--> >forbidden.
--> 
--> Just imagine what elegantly simple protocols we would have 
--> if we required the descriptions to be in Morse code.
--> 
--> Y(J)S
--> 
--> _______________________________________________
--> Ietf mailing list
--> [email-masked]
--> https://www1.ietf.org/mailman/listinfo/ietf
-->

---

From: "Gray, Eric" <[email-masked]>
Date: Thu, 17 Nov 2005 14:20:26 -0200

--> -----Original Message-----
--> From: Stewart Bryant [mailto:[email-masked]] 
--> Sent: Thursday, November 17, 2005 5:01 AM
--> To: Gray, Eric
--> Cc: [email-masked]; Lars-Erik Jonsson (LU/EAB)
--> Subject: Re: Diagrams (Was RFCs should be distributed in XML)
--> 
         --- [SNIP] ---
--> >
--> I don't much care what technology we use, that is not a key 
--> issue for me. The key issue is to be able to describe a 
--> protocol using the most appropriate mixture of clear 
--> English, clear diagrams and if necessary pseudo-code. We 
--> can do the first and the last but seem reluctant to 
--> recognize the need for the middle.
--> 
--> - Stewart
--> 

Fair enough.

---

From: "Hallam-Baker, Phillip" <[email-masked]>
Date: Thu, 17 Nov 2005 09:20:30 -0800

The description was sufficiently complete to allow running code to be
compiled from the formal specification. 

It certainly does save time when used by someone who has the necessary
experience to work at a very high level of abstraction. The problem is
that it is very hard to persuade others to then maintain the generated
code as this is not a mainstream coding technique. We can get people to
use Lex and Yacc for specific projects but the idea of developing a tool
for the project is something that is not very popular outside MIT and
the like.

If you read Kernighan and Plaugher's book on software tools you will see
that this approach did play an important role in the early development
of Unix. But what has tended to happen since is that people have taken
the specific tools developed rather than adopt the approach.

> From: Steve Crocker [mailto:[email-masked]] 
> Sent: Thursday, November 17, 2005 12:00 PM
> To: Hallam-Baker, Phillip
> Cc: Steve Crocker; Masataka Ohta; Yaakov Stein; 
> [email-masked]; Stewart Bryant
> Subject: Re: Diagrams (Was RFCs should be distributed in XML)
> 
> Well, even if you choose your formalism first and then use 
> that to guide the development and specification of the 
> protocols, the challenge still stands.  The operative word in 
> your description is "portions."  Does the technique cover 
> enough of the protocol to be useful and does it wind up 
> adding or saving time, work, errors, etc?
> 
> Steve
> 
> 
> Steve Crocker
> [email-masked]
> 
> 
> On Nov 17, 2005, at 11:56 AM, Hallam-Baker, Phillip wrote:
> 
> > There is a way, develop a highly targetted formalism for 
> the specific 
> > problem.
> >
> > This is hard to apply to existing specs because they tend to be 
> > inconsistent. If you are required to apply a formalism you 
> have to be 
> > much more consistent in your design approach.
> >
> > I did this for the finite state portions of FTP, NNTP and 
> SMTP in 1993 
> > when I was working on HTTP. With HTTP at the time there was 
> not a lot 
> > of state.
> >
> >> From: Steve Crocker [mailto:[email-masked]]
> >> Sent: Thursday, November 17, 2005 11:28 AM
> >> To: Hallam-Baker, Phillip
> >> Cc: Steve Crocker; Masataka Ohta; Yaakov Stein; [email-masked]; 
> >> Stewart Bryant
> >> Subject: Re: Diagrams (Was RFCs should be distributed in XML)
> >>
> >> Phillip,
> >>
> >> I spent a large fraction of my professional life in 
> pursuit of this 
> >> alluring and seemingly simple goal.  Here's a small
> >> challenge: Take
> >> *any* IETF protocol and write down the formal specification.
> >> Never mind the proof of correctness; that can come later.
> >> (And with it an extended discussion of the underlying 
> logical system, 
> >> the formal system for representing the protocol specification, and 
> >> the proof system you have in mind for carrying out the proof.)  Of 
> >> course, the formal specification will have to be readable and 
> >> understandable to the general population, and there will have to 
> >> ready agreement that it does embody the desired properties.  Pick 
> >> something simple.
> >> Perhaps IP?  Feel free to leave out messy details like performance 
> >> issues if you wish.  Just something simple and instructive to make 
> >> your point.  And in light of the other issues being 
> discussed, don't 
> >> feel constrained to use ASCII.
> >> Use any notation and tools you like.
> >>
> >> Steve
> >>
> >>
> >>
> >> Steve Crocker
> >> [email-masked]
> >>
> >>
> >> On Nov 17, 2005, at 10:09 AM, Hallam-Baker, Phillip wrote:
> >>
> >>> If we want to enforce simpler, more accurate design the
> >> best way to do
> >>> this would be to require a formal proof of correctness before 
> >>> accepting a specification.
> >>>
> >>> Requiring people to use 1960s technology is not a way to achieve 
> >>> simplicity.
> >>>
> >>>> From: [email-masked] [mailto:[email-masked]]
> >> On Behalf
> >>>> Of Masataka Ohta
> >>>> Sent: Thursday, November 17, 2005 8:30 AM
> >>>> To: Yaakov Stein
> >>>> Cc: [email-masked]; Stewart Bryant
> >>>> Subject: Re: Diagrams (Was RFCs should be distributed in XML)
> >>>>
> >>>> Yaakov Stein wrote:
> >>>>
> >>>>>> It's good that protocols needing more than 72 ASCII
> >> characters are
> >>>>>> forbidden.
> >>>>
> >>>>> Just imagine what elegantly simple protocols we would 
> have if we 
> >>>>> required the descriptions to be in Morse code.
> >>>>
> >>>> Good idea.
> >>>>
> >>>> It's a better approach to enforce much simpler protocols.
> >>>>
> >>>> 						Masataka Ohta
> >>>>
> >>>>