Subject: RE: html formatted drafts

From: "Lars-Erik Jonsson (LU/EAB)" <[email-masked]>
Date: Fri, 18 Feb 2005 14:17:01 +0100

> I don't much care how we do the text, but being a picture person
> rather than a language person, I really do wish we could agree on
> something better than ASCII art for the normative diagrams.

Can you give an example of something in an IETF standard that could
not be easily captured in ASCII art? There is one important advantage
with the limitations of ASCII art, it forces you to aim at simplicity.

I see your point, but personally I have more often appreciated the
simplicity of ASCII than I have depreciated the limitations of it.

/L-E

---

From: Mark Handley <[email-masked]>
Date: Fri, 18 Feb 2005 14:06:34 +0000

>with the limitations of ASCII art, it forces you to aim at simplicity.

Well, things should be as simple as possible, but no simpler.
Sometimes the problem is just not simple.  

To properly represent a non-trivial state-transition diagram in ASCII
art is just pointless.  Usually the normative version ends up using a
tabular form, which holds the same data, but doesn't aid understanding
in quite the same way as a diagram.

As a case in point, compare RFC 2362 to the latest PIM-SM draft -
draft-ietf-pim-sm-v2-new-11.ps.  While PIM-SM is ugly and bloated and
isn't a good example of a protocol, both versions of the spec describe
essentially the same protocol.  But the latest draft is much more
formal, so it's actually possible to build interoperable code from it.
However, understanding what happens from the ASCII version of the
draft without seeing the postscript versions of the state-transition
diagrams is pretty hard.

Sometimes I suspect the use of ASCII discourages more formal
representations in favour of a more ambiguous english representation.
I'm all for good english explanations of what is going on, but often
we use english exclusively when it's ill-suited to the task.

 - Mark

---

From: Stewart Bryant <[email-masked]>
Date: Fri, 18 Feb 2005 14:11:24 +0000

> with the limitations of ASCII art, it forces you to aim at simplicity.

Here is are some random examples taken from drafts that discuss
IP fast reroute. This work requires us to understand the
dynamic behavior of a network that has partial inconsistency,
and to understand its behavior during the convergence process.

                              +-----+-------------
                     ---------| N_1 |            | 5
                  |  |        +-----+---------   |    +-----+
                  |  | 10         |     15   |   |----| R_3 |
                  V  |         |  |          |        +-----+
                  +-----+      |  | 10    |  |       15 |
                  |  S  |      V  |       |  |          |  |
                  +-----+         |       V  |          |  |
                    |           +-----+      |          |  V
                 10 |  |     ---| R_1 |      |          |
                    |  |     |  +-----+      |          |
                    |  V   | |         +-----+          |
                    |      | | 20      | R_2 |          |
                +-----+    V |         +-----+      +-----+
                |  E  |      |            |         |  X  |
                +-----+      |        15  | |       +-----+
                  |          |  |---------| |          |
               |  | 10       |  |           V          |
               |  |        +-----+             <---    |
               V  |--------|  D  |---------------------| 15
                           +-----+

                       ...............  +--+--+    15
                 ......+----------------| ABRt|----------------+
              ...      |  15            +-----+                |
            ..         |                    ...                |
          ..    5  +-----+   15    +--+--+     ..              |
         .  +------| A2  +---------| R1  |-----+ .             |
       ..   |      +-----+         +-----+ 20  | .             |
       .    |                                +-----+  10       |
      .     |                 +--------------| ABR2|---------+ |
      .     |                 |      15      +-----+         | |
     .  +-----+     5     +---+-+                .           | |
     .  |  S  |-----------|  P  |------------+   .         +-----+
      . +-----+           +-----+    5       |   .         |  D  |
      .     |                                |   .         +-----+
       .    |                                |  .             |
       ..   |     +-----+                  +-----+  20        |
         .  +-----| A1  |------------------| ABR1|------------+
          .   10  +-----+    15            +-----+
           ...                               ...
              ...                         ...
                 ......              .....
                       ..............

      [S]---//---[B]-------[S1]
        |          |         |
        |          |         |
       [H]-3-[I]--[J]--[K]--[L]
              |         |
              |         |
             [X]--[Y]--[Z]

I think that these are pretty well on the limit of what we can express
in ASCII art, and even then you (well I) have to apply some effort to
visualizing them. Remember these diagrams almost certainly
started out in life as a multi-color diagram on a white board
and that when discussed at the WG meeting they were almost
certainly presented in power point. Unfortunately this level
of clarity is not available for the definitive description
of the concept.

Now imagine how they will look if we replace some number of the
pt-pt links with LANs, and then perhaps show some tunnels say
add a tunnel from say S to R_2 in the first diagram, or perhaps
show the state before and after a node transitions, or overlay
a shortest path tree or two on the diagrams.

It has always been the case that one's ability to abstract and
describe a problem limits one's ability to solve it and to clearly
articulate that solution to others.

I a fairly sure that the ASCII art constraint limits our ability
to think and work on the design of the Internet.

Stewart

---

From: Bill Sommerfeld <[email-masked]>
Date: Fri, 18 Feb 2005 09:47:27 -0500

> in quite the same way as a diagram.

on the other hand, one of the first things I did when (re)implementing a
state-machine-driven protocol (a dhcp client) was to convert the graph in the
RFC into a table *and then fill in all the missing holes and states*.

It's been a while since I looked at it, but the dhcp graph leaves out enough
of the "timeout? retransmit" loops to cause a literal implementation to 
get stuck.  But including such loops could well make the graph too "busy" in 
*any* representation intended to be legible on a letter/A4-size page.

						- Bill

---

From: Jeffrey Haas <[email-masked]>
Date: Fri, 18 Feb 2005 10:14:36 -0500

> Sometimes the problem is just not simple.  

Speaking of someone who wishes that management would stop sending
things in the form of .doc or .ppt, sometimes defining what makes
a given format a "good" format is hard.

While I'll buy into many of the arguments that the existing roff-like
format of the RFCs is perhaps a bit weak in representation, the format
has one huge thing going for it:  searchability.  I think XML would
leave us the searchability (especially if it can generate output 
that resembles the current RFC series) and let us use the meta-info
to enhance things.

> in quite the same way as a diagram.

Which then begs the question of what the format should be.  PS is
generally acceptable since it can display everywhere.  Tabular is
great because it removes the errors that sometimes creep into diagrams.
XML may let you do tabular data in a slightly more palatable format.

> representations in favour of a more ambiguous english representation.

The biggest thing I'd change for many state machines I've seen
in various IETF specifications is to make sure they're full DFAs.
While this would bloat the state machines considerably even for many
trivial protocols, we'd no longer have ambiguous states.  Even if
not part of the base specification, exploring the full DFA occasionally
points out unexpected state machine interactions.

> we use english exclusively when it's ill-suited to the task.

/me hopes not to hear mention of LOGLAN

-- 
Jeff Haas 
NextHop Technologies

---

From: Thierry Ernst <[email-masked]>
Date: Sat, 19 Feb 2005 16:02:12 +0900

I like simplicity too but I fail to see how html would bring more
complexity when the .html is generated from the .xml. I concur with
Gabriel that we should accept to put .html format on the IETF directory,
at least when it's requested by the authors.

I also concur with all who says that ASCII has its limits, while I agree
at the same time it has its benefits. 

A key feature of the IETF has always been flexibility in the
organization, so why are we so narrowed when it comes to publishing?

Thierry

 On Fri, 18 Feb 2005 14:17:01 +0100