Re: Normative figures
Bob Braden wrote: * The draft has expired so I need to point to an external version. This draft * which is looking at the properties of a routing network under conditions of * failure would have been much clearer if it could have used mathematical * notation rather than ASCIIised equations * * http://www.faqs.org/ftp/pub/internet-drafts/draft-atlas-ip-local-protect-uturn-02.txt * * Of course the diagrams could have also been clearer, as is seen by * comparing them to the ones that Alia used in her presentatons on the * subject. * * - Stewart * Stewart, I just looked over this document, and it actually seems to me to support the ASCII art and equations are [just] enough to serve the explanatory purpose school of thought. However the versions of this work that are published without the 72 char ASCII constraint are MUCH easier to read and understand. You need to consider how much attention it reasonable to direct towards understanding the notation and how much towards understanding the technology. You may gather that I think that all the concentration should be directed at the technology. Also if this is JUST, then we are clearly working on the limit, i.e. what we do to make the Internet work better risks being limited by our ability to describe to each other the problems and solutions. Indeed we cannot be sure that we are not already in that limiting state. I really do not see that it would be much clearer if it could have used mathemtical notation. As experienced programmers, we are used to reading linearized formulas, aren't we? And these particular formulas seem quite simple. If linearised formulas were a good idea mathematicians would use them :) Translation to ASCII representation should surely be the final step in implementation not something imposed during the understanding and description phase. Note that if and when this document is published as an RFC, the RFC Editor will supply some additional blank lines and clean up the indentation, which will make the equations much easier to read. Also, as you note, the ASCII art diagrams could really use a cleanup. They are unnecessarily ugly, kind of dyslexic. The non-ASCII versions presented at the RTGWG looked fine. It is true that the discipline of ASCII art forces the author to give some thought to the clarity and modularity of the text. Opinions differ on whether this is a good thing or a bad thing. Indeed, or whether as to whether it enhances of detracts from out ability to do the right thing for the Internet. - Stewart ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: Normative figures
Stewart Bryant writes... If linearised formulas were a good idea mathematicians would use them :) Translation to ASCII representation should surely be the final step in implementation not something imposed during the understanding and description phase. If symbolic formulas were useful in protocol implementations, then programming languages like C or C++ would accept them. IMHO, if it's good enough for the implementation, it's good enough for the specification. Academic and scholarly articles often make extensive use of symbolic mathematical expressions, because that's the language of mathematics, and the accepted format for those publications. I would not like to see these formats used in protocol specifications, as a general rule. ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
OK this discussion is OLD!!! (was: Re: Normative figures)
How about a new mailing list or some such?! Eliot ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
On Wed, Jan 11, 2006 at 01:02:55AM +0100, Frank Ellermann [EMAIL PROTECTED] wrote a message of 11 lines which said: this code should work as it is forever for everybody who wants it to work. Yes, the good point about Graphviz is that it is readable even if you do not know / have the software and that it is represented in ASCII, therefore requiring no change to the procedures or rules. For an ASCII-art output of an arbitrary graph, I wait for a clever CS student to modify Graphviz in that way :-) ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Eric, ... Moreover, I believe there is evidence to this effect, as pointed out previously, in the fact that at least one RFC is essentially only available in PS and PDF format. That is an RFC that predates not only RFC 2026 but also its predecessors, RFC 1602 and 1310. So it doesn't tell us anything about the current rules. ... -- -Original Message- -- From: Stewart Bryant [mailto:[EMAIL PROTECTED] -- Sent: Tuesday, January 10, 2006 12:01 AM -- To: Gray, Eric -- Cc: ietf@ietf.org -- Subject: Re: Normative figures -- -- -- Yes. And, if we're talking about wanting to make the figures -- normative, I assume we are talking about a specification. In -- that case, it is far more important that the description MUST -- be precise, than it is that it MAY be convenient. -- -- -- -- Please can we clarify the existing rules: -- -- For a standards track document is it technically acceptable -- to provide: -- -- A .pdf that is complete (but is non-normative under current rules) -- -- plus -- -- An ASCII text in which the background material refers to -- figures in the -- .pdf but which contains the essential normative statements. -- -- i.e. Is a standards track RFC approvable when it is correct in the -- technical -- sense, even if it is almost incomprehensible without the -- text, figures and -- equations from its non-normative twin. I'd have great difficulty approving such a document for the standards track under RFC 2026: * A stricter requirement applies to standards-track* * specifications: the ASCII text version is the * * definitive reference, and therefore it must be a * * complete and accurate specification of the standard, * * including all necessary diagrams and illustrations. * I don't think 'almost incomprehensible' would pass this test. But in practice, incomprehensible diagrams or equations aren't a problem that I've seen. That's not to deny that (e.g.) PNG graphics might be easier to read sometimes. I'm wondering about non-normative graphical and mathematical annexes to normative documents. Brian ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
* The draft has expired so I need to point to an external version. This draft * which is looking at the properties of a routing network under conditions of * failure would have been much clearer if it could have used mathematical * notation rather than ASCIIised equations * * http://www.faqs.org/ftp/pub/internet-drafts/draft-atlas-ip-local-protect-uturn-02.txt * * Of course the diagrams could have also been clearer, as is seen by * comparing them to the ones that Alia used in her presentatons on the * subject. * * - Stewart * Stewart, I just looked over this document, and it actually seems to me to support the ASCII art and equations are [just] enough to serve the explanatory purpose school of thought. I really do not see that it would be much clearer if it could have used mathemtical notation. As experienced programmers, we are used to reading linearized formulas, aren't we? And these particular formulas seem quite simple. Note that if and when this document is published as an RFC, the RFC Editor will supply some additional blank lines and clean up the indentation, which will make the equations much easier to read. Also, as you note, the ASCII art diagrams could really use a cleanup. They are unnecessarily ugly, kind of dyslexic. It is true that the discipline of ASCII art forces the author to give some thought to the clarity and modularity of the text. Opinions differ on whether this is a good thing or a bad thing. Bob Braden ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
* Scott, * * How about Sections 4.2.3.3 and 4.2.3.4 of RFC 1122 (1889), for examples * of readable equations in ASCII? I my experience, normative protocol * technical specifications rarely need equations much more complex than * these examples. The only significant exception I can think of is the * NTP spec. * * RFC 3247 is quite tricky too. * * Yes, in fact, the RFC Editor could have been persuaded that this particular document fell into the RFC 1119 category -- PDF-only. But note that it is not a standards track document, and that very few areas of IETF endeavor have the mathematical depth of queue management algorithms. Bob ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
On Mon, Jan 09, 2006 at 07:46:42PM +, Stewart Bryant [EMAIL PROTECTED] wrote a message of 73 lines which said: For example you could say the following in text : [long and complicated example deleted] For such examples (do note that your example is an illustration of a point and therefore does not need to be normative, like, say, a state diagram), graph people produced several languages which are non-ambiguous, expressed as ASCII and produce nice output. Some even are free (as in free speech and as in free beer). (Unfortunately, none is standard in any way, AFAIK.) The one I recommend is Graphviz (http://www.research.att.com/sw/tools/graphviz/). An example of Graphviz code for a real network: http://www.seekingfire.com/projects/metanetwork/maps/meta.dot (See http://www.seekingfire.com/projects/metanetwork/info.html for the context) See also: Managing IP Networks with Free Software http://www.nanog.org/mtg-0210/ppt/stephen.pdf has a chapter about Graphviz A Systematic Approach to BGP Configuration Checking http://www.nanog.org/mtg-0310/pdf/feamster.pdf uses cflow to produce Graphviz .dot files. (ACL compilers like Netspoc http://netspoc.berlios.de/ also have an ASCII language to represent networks.) ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
On Mon, Jan 09, 2006 at 05:35:51PM -0500, Gray, Eric [EMAIL PROTECTED] wrote a message of 211 lines which said: The reality is that putting things entirely in pictures means that less validation of the intent of the picture is possible. Automatic validation (by a program) is not possible either with unstructured ASCII art. To do so, you would need a formal graph language (like Graphviz I mentioned before and even Graphviz is too low-level, too drawing-oriented to do so). ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Bob Braden wrote: * * Normative figures perhaps. Normative equations definitely. Scott, How about Sections 4.2.3.3 and 4.2.3.4 of RFC 1122 (1889), for examples of readable equations in ASCII? I my experience, normative protocol technical specifications rarely need equations much more complex than these examples. The only significant exception I can think of is the NTP spec. RFC 3247 is quite tricky too. People who REALLY use equations generally prefer LaTeX. Yes, and if the equations are informative that's fine; they can publish where they want to. But we have a genuine issue when equations are both normative and complicated. Brian ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
On Mon, Jan 09, 2006 at 07:46:42PM +,
Stewart Bryant [EMAIL PROTECTED] wrote
a message of 73 lines which said:
For example you could say the following in text : router A connects
to router B and D, the cost from A to B is 2, and the cost from A to
D is 4. Router B connects to router C. The cost to router A is 6,
and the cost to router C is 10. Router C connects to router D. The
cost to router B is 9 and the cost to router D is 8. The cost from
router D to router A is 16 and the cost to router A is 99.
Here is the Graphviz code, to compare (I also attached the
automatically produced PNG but Graphviz can make PDF or SVG as well):
// See http://www1.ietf.org/mail-archive/web/ietf/current/msg39858.html
digraph bryantnetwork {
label = Stewart Bryant's network;
// Routers
node [shape=box, fontsize=15];
// Links
edge [len=2.0];
A - B [label=2];
A - D [label=4];
B - A [label=6];
B - C [label=10];
C - B [label=9];
C - D [label=8];
D - A [label=16];
D - C [label=99];
}
bryant.png
Description: PNG image
___
Ietf mailing list
Ietf@ietf.org
https://www1.ietf.org/mailman/listinfo/ietf
RE: Normative figures
Stewart, Yes, you are correct. But, if you had correctly understood the comment you quote below, you would realize that we're clearly in agreement already - at least on that aspect of the discussion. :-) My point is that we make inclusion of elaborate figures more difficult because elaborate figures don't necessarily make for a better understanding - any more than complicated equations do. If people generally agree that complicated diagrams, tables, figures or equations is necessary to understanding a specification - then it is quite possible to do so. The fact that this makes it (at least slightly) harder to write a specification if it must include complex art, does not impact on the difficulty in reading the resulting specification. However, as pointed out several times, making it trivially easy to include complex art MAY make reading specifications that do not require it much harder. Since the vast majority of documents produced by the IETF do not appear to require complex art, our process is optimized for the normal case - just as it should be... -- Eric -- -Original Message- -- From: Stewart Bryant [mailto:[EMAIL PROTECTED] -- Sent: Monday, January 09, 2006 11:40 PM -- To: Gray, Eric -- Cc: ietf@ietf.org -- Subject: Re: Normative figures -- -- -- We write specifications so that they are easier to read, validate -- and understand, not so that they are easier to write. -- -- -- -- -- Eric -- -- We write specs so that they will be correctly implemented. -- Anything that makes a specification easier to correctly understand -- surely makes it more likely that it will be correctly implemented? -- -- The cost of incorrect implementation is so high that we can -- can afford to pay a relatively high cost in the effort and -- technology needed to read and write the specification. -- -- - Stewart -- -- -- -- -- ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: Normative figures
Stewart, You address this to me - though I do not make these rules. However, I will do my best to answer your question. In the case you pose below, almost incomprehensible is the key phrase. Had you not qualified incomprehensible, the answer would be no, at least IMO. Moreover, I believe there is evidence to this effect, as pointed out previously, in the fact that at least one RFC is essentially only available in PS and PDF format. However, as long as a text version is comprehensible, it should be the normative version - simply because, however hard it might be to overcome the difficulty in comprehending it for the average reader, it is not sufficient to justify making it absolutely impossible to comprehend for any specific minority of readers (at least among those minorities that are likely to be required to understand it). Minorities in this context inclide anyone who does not have the ability to use the needed document display tools - either because they do not have them or because they are otherwise prevented from using them. However, as must be apparent from other discussion in various related threads, this is only a minority consideration. -- Eric -- -Original Message- -- From: Stewart Bryant [mailto:[EMAIL PROTECTED] -- Sent: Tuesday, January 10, 2006 12:01 AM -- To: Gray, Eric -- Cc: ietf@ietf.org -- Subject: Re: Normative figures -- -- -- Yes. And, if we're talking about wanting to make the figures -- normative, I assume we are talking about a specification. In -- that case, it is far more important that the description MUST -- be precise, than it is that it MAY be convenient. -- -- -- -- Please can we clarify the existing rules: -- -- For a standards track document is it technically acceptable -- to provide: -- -- A .pdf that is complete (but is non-normative under current rules) -- -- plus -- -- An ASCII text in which the background material refers to -- figures in the -- .pdf but which contains the essential normative statements. -- -- i.e. Is a standards track RFC approvable when it is correct in the -- technical -- sense, even if it is almost incomprehensible without the -- text, figures and -- equations from its non-normative twin. -- -- - Stewart -- ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Stewart == Stewart Bryant [EMAIL PROTECTED] writes: Stewart For example you could say the following in text : router Stewart A connects to router B and D, the cost from A to B is 2, Stewart and the cost from A to D is 4. Router B connects to Stewart router C. The cost to router A is 6, and the cost to Stewart router C is 10. Router C connects to router D. The cost Stewart to router B is 9 and the cost to router D is 8. The cost Stewart from router D to router A is 16 and the cost to router A Stewart is 99. I think we fundamentally disagree here that the text is not needed. There's a bit of fuzz in that I think the normative text needs to describe the properties of the graph necessary to make your point and to make it obvious that such a graph exists; it may not need to describe all the labels of all edges. ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Stephane Bortzmeyer wrote: Here is the Graphviz code, to compare (I also attached the automatically produced PNG but Graphviz can make PDF or SVG as well) Nice, I've always loved graph theory. Now let it colour the shortest path fromn B to D, and then ask it for some decent ASCII art output... g Joke off, this code should work as it is forever for everybody who wants it to work. Bye, Frank ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
On 01/09/2006 10:41 AM, Sam Hartman allegedly wrote: Are you looking for normative figures? If so, can you point to an example where you think they are necessary? (I'd like to avoid a discussion of packet diagrams for the moment if that's OK) Normative figures perhaps. Normative equations definitely. Is there any input format for *just* equations (or figures), standing by themselves, which we can agree is open, standardized, stable and deterministic in output? ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Scott == Scott W Brim sbrim@cisco.com writes: Scott On 01/09/2006 10:41 AM, Sam Hartman allegedly wrote: Are you looking for normative figures? If so, can you point to an example where you think they are necessary? (I'd like to avoid a discussion of packet diagrams for the moment if that's OK) Scott Normative figures perhaps. Normative equations definitely. Scott Is there any input format for *just* equations (or Scott figures), standing by themselves, which we can agree is Scott open, standardized, stable and deterministic in output? Mmm. I have some significant accessibility concerns with that if you expect me to review the documents. I think that's a small (although probably impossible at the current point) matter of technology. If you go so far as normative figures I have a lot more questions about why and what you are trying to accomplish. --Sam ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
In message [EMAIL PROTECTED], Scott W Brim writes: On 01/09/2006 10:41 AM, Sam Hartman allegedly wrote: Are you looking for normative figures? If so, can you point to an example where you think they are necessary? (I'd like to avoid a discussion of packet diagrams for the moment if that's OK) Normative figures perhaps. Normative equations definitely. Is there any input format for *just* equations (or figures), standing by themselves, which we can agree is open, standardized, stable and deterministic in output? LaTeX is the standard in the math and theory world. It's free, and runs on just about everything. If I recall correctly what Kernighan once said, eqn was designed so that its input language was more or less what one mathematician would say to another over the phone, which (I assume) would help with accessibility. There are open source versions of eqn; I think that they run on more or less anything, too. In the pure HTML world, there's MathML, though it's *really* ugly to read. I have no idea how much it's supported by today's browsers. (Kernighan started working on an eqn to HTML translator some years ago, but back then no browser really worked properly for it.) Note that I'm *not* saying we should adopt any of these for RFCs; I'm simply saying that there are some well-known systems that satisfy at least your four criteria. --Steven M. Bellovin, http://www.cs.columbia.edu/~smb ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
* * Normative figures perhaps. Normative equations definitely. Scott, How about Sections 4.2.3.3 and 4.2.3.4 of RFC 1122 (1889), for examples of readable equations in ASCII? I my experience, normative protocol technical specifications rarely need equations much more complex than these examples. The only significant exception I can think of is the NTP spec. People who REALLY use equations generally prefer LaTeX. Bob Braden ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Hi. With the exception of packet diagrams, I think all the examples you bring up benefit significantly from clear textual description. I believe I'd think that even if I could see the diagrams and I believe I have enough experience with visualization (although not sight) to be confident in that belief. As such, I don't believe these diagrams should be normative. I actually thin that many of the tunnel overlay network documents (PWE3, L2VPN, L3VPN) could benefit significantly from more focus on the text of the descriptions of situations being described. If you believe that normative documents are required, I'd like you to explain why the diagrams cannot be described in the text, why doing so would decrease the quality of the specification, or why doing so would not be a useful investment in our time. ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Bob Braden wrote: * * Normative figures perhaps. Normative equations definitely. Scott, How about Sections 4.2.3.3 and 4.2.3.4 of RFC 1122 (1889), for examples of readable equations in ASCII? I my experience, normative protocol technical specifications rarely need equations much more complex than these examples. The only significant exception I can think of is the NTP spec. People who REALLY use equations generally prefer LaTeX. Bob Braden The draft has expired so I need to point to an external version. This draft which is looking at the properties of a routing network under conditions of failure would have been much clearer if it could have used mathematical notation rather than ASCIIised equations http://www.faqs.org/ftp/pub/internet-drafts/draft-atlas-ip-local-protect-uturn-02.txt Of course the diagrams could have also been clearer, as is seen by comparing them to the ones that Alia used in her presentatons on the subject. - Stewart ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Sam Hartman wrote: Hi. With the exception of packet diagrams, I think all the examples you bring up benefit significantly from clear textual description. Sam I am not saying that clear text is not needed to accompany a diagram. However a diagram allows a lot less text to be written producing a shorter clearer draft with less clutter. For example you could say the following in text : router A connects to router B and D, the cost from A to B is 2, and the cost from A to D is 4. Router B connects to router C. The cost to router A is 6, and the cost to router C is 10. Router C connects to router D. The cost to router B is 9 and the cost to router D is 8. The cost from router D to router A is 16 and the cost to router A is 99. In fact you would probably need a table to make sure that you did not make a mistake. In either case it is hard for most people to figure out the what the topology is much less imagine packet actions. Now compare this to: The network and costs are as shown in figure foo. Simple text and the visualisation is already done for you so you can focus on the problem. Now I realise the above could be done in ascii art, but we have problems that need 13 or more nodes to set up. I believe I'd think that even if I could see the diagrams and I believe I have enough experience with visualization (although not sight) to be confident in that belief. As such, I don't believe these diagrams should be normative. I actually thin that many of the tunnel overlay network documents (PWE3, L2VPN, L3VPN) could benefit significantly from more focus on the text of the descriptions of situations being described. It is probably a question of how we work and the tools that we find most effective. If you believe that normative documents are required, I'd like you to explain why the diagrams cannot be described in the text, why doing so would decrease the quality of the specification, or why doing so would not be a useful investment in our time. One reason is that it takes a lot of text to describe what can be drawn with a few lines and symbols. Many people will get lost in the text and in any case would have to transcribe the text into a diagram for themselves before they could understand what is happening. - Stewart ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: Normative figures
Stewart, There's a joke that goes something like this: there are three kinds of people in this world - those that are good at Math and those that are not. Funny thing is that there are at least three ways in which people approach mathematical expressions: 1) Some see a nice, clean, symbolic expression and mentally reject it out of hand (for these people, a summation symbol terminates a line of readable text); 2) Some see a symbolic expression, look at it briefly and become (as one person said earlier about figures) convinced they understand it while actually they do not (this can be established by a simple search for published material in which non-sensical mathematical expressions were included without comment in peer reviews); 3) Some people see any symbolic expression and play with it until either they understand it or they know what is wrong with it. In the first two cases - in which, I think we can agree, most people would fall - it is much better to have made the effort to put the expression in plain English - however much prettier it would have been in symbolic representation. -- Eric -- -Original Message- -- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] -- On Behalf Of Stewart Bryant -- Sent: Monday, January 09, 2006 2:22 PM -- To: Bob Braden -- Cc: [EMAIL PROTECTED]; [EMAIL PROTECTED]; -- ietf@ietf.org; sbrim@cisco.com -- Subject: Re: Normative figures -- -- Bob Braden wrote: -- -- * -- * Normative figures perhaps. Normative equations definitely. -- -- Scott, -- -- How about Sections 4.2.3.3 and 4.2.3.4 of RFC 1122 (1889), -- for examples -- of readable equations in ASCII? I my experience, -- normative protocol -- technical specifications rarely need equations much more -- complex than -- these examples. The only significant exception I can -- think of is the -- NTP spec. -- -- People who REALLY use equations generally prefer LaTeX. -- -- Bob Braden -- -- -- -- -- The draft has expired so I need to point to an external -- version. This draft -- which is looking at the properties of a routing network -- under conditions of -- failure would have been much clearer if it could have used -- mathematical -- notation rather than ASCIIised equations -- -- http://www.faqs.org/ftp/pub/internet-drafts/draft-atlas-ip-l -- ocal-protect-uturn-02.txt -- -- Of course the diagrams could have also been clearer, as is seen by -- comparing them to the ones that Alia used in her presentatons on the -- subject. -- -- - Stewart -- -- -- ___ -- Ietf mailing list -- Ietf@ietf.org -- https://www1.ietf.org/mailman/listinfo/ietf -- ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
In message [EMAIL PROTECTED], Scott W Brim writes: On 01/09/2006 10:41 AM, Sam Hartman allegedly wrote: Are you looking for normative figures? If so, can you point to an example where you think they are necessary? (I'd like to avoid a discussion of packet diagrams for the moment if that's OK) Normative figures perhaps. Normative equations definitely. Is there any input format for *just* equations (or figures), standing by themselves, which we can agree is open, standardized, stable and deterministic in output? LaTeX is the standard in the math and theory world. It's free, and runs on just about everything. LaTeX or some other TeX variant. AMS-TeX is one such but there are a bunch of others. (Always fun when you get TeX source that uses a macro package you don't have available.) If I recall correctly what Kernighan once said, eqn was designed so that its input language was more or less what one mathematician would say to another over the phone, which (I assume) would help with accessibility. There are open source versions of eqn; I think that they run on more or less anything, too. Personally, I'm unconvinced that design goal was met. In the pure HTML world, there's MathML, though it's *really* ugly to read. I have no idea how much it's supported by today's browsers. (Kernighan started working on an eqn to HTML translator some years ago, but back then no browser really worked properly for it.) It is probably worth noting that another very popular format in the math world for equations is essentially ASCII art. This is what you tend to get as output from the various symbolic manipulation packages like Reduce, Macsyma, Maple, and last time I looked, Mathematica. Stuff like: 23 2 23 3 ww x (w k + w ) x(3 w k + w ) x (D7)/T/ -- + --- - -- - + . . . 434 3 kk 6 k 6 k is actually pretty readable. And any of these packages can be used to generate this sort of thing; no need to piddle around in an editor. (The example above is a Taylor series expansion from Maxima.) These packages often have TeX and eqn output modes as well. Another interesting development in this space is the new programming language Fortress being developed by Guy Steele, which sticks with simple character strings but uses the full UTF-8 repetoire to advantage. I personally find it hard to get used to after so many years of looking at ASCII art equations, especially when lots of matrix and vectoor stuff is involved, but this might be an interesting avenue to pursue if we ever started allowing UTF-8. See: http://research.sun.com/projects/plrg/ for additional information. Note that I'm *not* saying we should adopt any of these for RFCs; I'm simply saying that there are some well-known systems that satisfy at least your four criteria. Indeed. I will also point out that as with anything having to do with which notation is better or best, getting agreement even in the relatively narrow confines of the math community is next to impossible. You know how it is: The arguments are nasty because the stakes are so low. Ned ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: Normative figures
| -Original Message- | From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] | On Behalf Of Stewart Bryant | Sent: Tuesday, January 10, 2006 6:47 AM | To: Sam Hartman | Cc: Harald Tveit Alvestrand; ietf@ietf.org | Subject: Re: Normative figures | | Sam Hartman wrote: | | Hi. With the exception of packet diagrams, I think all the | examples | you bring up benefit significantly from clear textual description. | | Sam | | I am not saying that clear text is not needed to accompany a diagram. | However a diagram allows a lot less text to be written | producing a shorter clearer draft with less clutter. SNIP Perhaps this is getting to the crux of the issues. I see the IETF documents as breaking down the problems into smaller chunks that can be dealt with one at a time and which add up to a big picture description of the whole Internet. I see each individual document as being simple within itself, limiting the context to the smallest level an issue may be dealt with. By adding more complexity to the documents I feel it is allowing more complex issues to be described in the documents but the documents then become larger, more difficult to comprehend and will be more difficult to process. Using the example you gave for routing costs, I see the description of routing cost basics or specifics as one document and the description of how they may be dealt with as another. By forcing the documents to be in a simple format, there are limitations on the complexity that may be explained in a single document, but I consider this a good thing. It forces everyone to break the problems and issues down to their lowest levels and forces simple explanations that make it easier for everyone to understand. If more complex documents with full diagramatic process flows are required, these could be books written linking a number of IETF documents together to describe a more general practical picture of their implementation. Darryl (Dassa) Lynch ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Note that LaTeX is an input format - it will output to many output formats - even to ASCII. (And, of course, it sits on top of and drives TeX itself.) As a physicist, I have used LaTeX a lot. It has a steep learning curve - much more than with, say, html. When I did a set of conference proceedings in LaTEX - Proc. USNO Workshop on Relativistic Models for use in Space Geodesy, 1991. most of the papers went fine, a few just would not display correctly and took a lot of tweaking just to get them to look halfway right. These last took a lot of time. TeX / LaTeX is like that. So, most journals today use style sheets, such as the AMS-TEX ones, and templates, to enforce their look and feel. I suspect they have issues from time to time even with that. Oh, and if an email line begins with From and get turns into From, LaTex will turn that into upside down ?From, which you can see in the strangest places, once you know to look for it. There are a few WSIWYG editors for Tex/LaTex, but most people I know use a text editor. I certainly would not regard moving everything to LaTeX as a trivial change. Regards Marshall Eubanks On Jan 9, 2006, at 12:59 PM, Steven M. Bellovin wrote: In message [EMAIL PROTECTED], Scott W Brim writes: On 01/09/2006 10:41 AM, Sam Hartman allegedly wrote: Are you looking for normative figures? If so, can you point to an example where you think they are necessary? (I'd like to avoid a discussion of packet diagrams for the moment if that's OK) Normative figures perhaps. Normative equations definitely. Is there any input format for *just* equations (or figures), standing by themselves, which we can agree is open, standardized, stable and deterministic in output? LaTeX is the standard in the math and theory world. It's free, and runs on just about everything. If I recall correctly what Kernighan once said, eqn was designed so that its input language was more or less what one mathematician would say to another over the phone, which (I assume) would help with accessibility. There are open source versions of eqn; I think that they run on more or less anything, too. In the pure HTML world, there's MathML, though it's *really* ugly to read. I have no idea how much it's supported by today's browsers. (Kernighan started working on an eqn to HTML translator some years ago, but back then no browser really worked properly for it.) Note that I'm *not* saying we should adopt any of these for RFCs; I'm simply saying that there are some well-known systems that satisfy at least your four criteria. --Steven M. Bellovin, http://www.cs.columbia.edu/~smb ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
RE: Normative figures
Stewart, You realize that the text example you gave is meaningless - without making some (potentially non-obvious) assumptions, right? -- -Original Message- -- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] -- On Behalf Of Stewart Bryant -- Sent: Monday, January 09, 2006 2:47 PM -- To: Sam Hartman -- Cc: Harald Tveit Alvestrand; ietf@ietf.org -- Subject: Re: Normative figures -- -- Sam Hartman wrote: -- -- Hi. With the exception of packet diagrams, I think all -- the examples -- you bring up benefit significantly from clear textual description. -- -- Sam -- -- I am not saying that clear text is not needed to accompany -- a diagram. -- However a diagram allows a lot less text to be written producing a -- shorter clearer draft with less clutter. -- -- For example you could say the following in text : router A connects to -- router B and D, the cost from A to B is 2, and the cost from A to D is 4. A --(2)-- B | +---(4)-- D -- Router B connects to router C. The cost to router A is 6, and -- the cost to router C is 10. + A --(6)--+ | | | | +--(2)-- B --(10)-- C | +--(4)-- D (Assumes cost is from router B in both cases) -- Router C connects to router D. The cost to router B is 9 -- and the cost to router D is 8. + A --(6)--+ | | | | +--(2)-- B --(9)---+ | | | | +--(10)-- C | | +--(4)-- D (8)---+ (Assumes cost is from router C in both cases) -- The cost from router D to router A is 16 and ... +--+ | | | +- A --(6)--+ | | | | | | +--(2)-- B --(9)---+ | | | | | +--(16)+ +--(10)-- C | | | +--(4)-- D (8)+ -- -- ... the cost to router A is 99. ? (Assuming you meant the cost from D to C - not A) +--+ | | | +- A --(6)--+ | | | | | | +--(2)-- B --(9)---+ | | | | | +--(16)+ +--(10)-- C -+ | | | | +--(4)-- D (8)+ | | | +-(99)+ (Figure foo?) -- -- In fact you would probably need a table to make sure that -- you did not make a mistake. In either case it is hard for -- most people to figure out the what the topology is much -- less imagine packet actions. Actually, you need a figure to make sure that you did not make a mistake, and a second set of eyes to compare what you said to what you apparently meant. -- -- Now compare this to: -- -- The network and costs are as shown in figure foo. -- Is the above actually figure foo? The reality is that it would be better to break it this way: In the network in figure foo, the link costs are as follows: A - B = 2 B - A = 6 +- A B -+ A - D = 4 || D - A = 16 +- D C -+ B - C = 10 C - B = 9 Figure foo C - D = 8 D - C = 99 -- Simple text and the visualisation is already done for you -- so you can focus on the problem. -- The reality is that putting things entirely in pictures means that less validation of the intent of the picture is possible. Keeping pictures as simple as possible is, therefore, a goal since it is far easier to make mistakes in complex figures and far more difficult to determine that a mistake has been made. Using a mixture of text and figure(s), tables or - possibly - equations makes it both more understandable and easier to be certain of conveying the idea(s). For example, in the above, I could verify that I understand your intent by asking: From this it is apparent that the link cost (D-C) is 99, but the actual minimum cost of getting from D to C given by the formula: (D-A) + (A-B) + (B-C) = 16 + 2 + 10 = 28 Is that correct? If we choose to use a simple combination of representations, rather than strictly expecting a figure to explain it all, the figure is likely to be far simpler. For example, using an approach similar to the above, you could probably describe a much more complex network than 13, or 20 or maybe even 30 nodes using ASCII art. The purpose of the picture is to be a simplified referent. -- -- Now I realise the above could be done in ascii art, but we -- have problems that need 13 or more nodes to set up. -- -- I believe I'd think that even if I could see the diagrams -- and I believe I have enough experience with visualization -- (although not sight) to be confident in that belief. -- -- -- -- As such, I don't believe these diagrams should be normative. -- -- -- I actually thin that many of the tunnel overlay network documents -- (PWE3, L2VPN, L3VPN) could benefit significantly from more focus on -- the text of the descriptions of situations being described
Re: Normative figures
Dassa wrote: | -Original Message- | From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] | On Behalf Of Stewart Bryant | Sent: Tuesday, January 10, 2006 6:47 AM | To: Sam Hartman | Cc: Harald Tveit Alvestrand; ietf@ietf.org | Subject: Re: Normative figures | | Sam Hartman wrote: | | Hi. With the exception of packet diagrams, I think all the | examples | you bring up benefit significantly from clear textual description. | | Sam | | I am not saying that clear text is not needed to accompany a diagram. | However a diagram allows a lot less text to be written | producing a shorter clearer draft with less clutter. SNIP Perhaps this is getting to the crux of the issues. I see the IETF documents as breaking down the problems into smaller chunks that can be dealt with one at a time and which add up to a big picture description of the whole Internet. I see each individual document as being simple within itself, limiting the context to the smallest level an issue may be dealt with. By adding more complexity to the documents I feel it is allowing more complex issues to be described in the documents but the documents then become larger, more difficult to comprehend and will be more difficult to process. Using the example you gave for routing costs, I see the description of routing cost basics or specifics as one document and the description of how they may be dealt with as another. By forcing the documents to be in a simple format, there are limitations on the complexity that may be explained in a single document, but I consider this a good thing. It forces everyone to break the problems and issues down to their lowest levels and forces simple explanations that make it easier for everyone to understand. That does not work if you need the costs to set up a scenario that you are about to describe the solution to. If more complex documents with full diagramatic process flows are required, these could be books written linking a number of IETF documents together to describe a more general practical picture of their implementation. It may not be possible to do that. It depends on what we are describing. - Stewart Darryl (Dassa) Lynch ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Eric You are missing the point. I was picking an example out of thin air, but it is the type of construct that we use all the time in fast-reroute. The example was four routers connected together in a square with some randomly chosen asymetric costs. Such a network is trivial, but FRR need to cope with arbitary network fragments with arbitary costs, so there are lots of fragments that we have created for study the properties of. One of the ways to operate on the fragment is to draw it and then to figure out the packet flows, consequences of failure etc etc. Now the question is why should the examples in our drafts be forced by our ability to describe them, rather than being the example that most clearly illustrates the problem and its solution? - Stewart Gray, Eric wrote: Stewart, You realize that the text example you gave is meaningless - without making some (potentially non-obvious) assumptions, right? -- -Original Message- -- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] -- On Behalf Of Stewart Bryant -- Sent: Monday, January 09, 2006 2:47 PM -- To: Sam Hartman -- Cc: Harald Tveit Alvestrand; ietf@ietf.org -- Subject: Re: Normative figures -- -- Sam Hartman wrote: -- -- Hi. With the exception of packet diagrams, I think all -- the examples -- you bring up benefit significantly from clear textual description. -- -- Sam -- -- I am not saying that clear text is not needed to accompany -- a diagram. -- However a diagram allows a lot less text to be written producing a -- shorter clearer draft with less clutter. -- -- For example you could say the following in text : router A connects to -- router B and D, the cost from A to B is 2, and the cost from A to D is 4. A --(2)-- B | +---(4)-- D -- Router B connects to router C. The cost to router A is 6, and -- the cost to router C is 10. + A --(6)--+ | | | | +--(2)-- B --(10)-- C | +--(4)-- D (Assumes cost is from router B in both cases) -- Router C connects to router D. The cost to router B is 9 -- and the cost to router D is 8. + A --(6)--+ | | | | +--(2)-- B --(9)---+ | | | | +--(10)-- C | | +--(4)-- D (8)---+ (Assumes cost is from router C in both cases) -- The cost from router D to router A is 16 and ... +--+ | | | +- A --(6)--+ | | | | | | +--(2)-- B --(9)---+ | | | | | +--(16)+ +--(10)-- C | | | +--(4)-- D (8)+ -- -- ... the cost to router A is 99. ? (Assuming you meant the cost from D to C - not A) +--+ | | | +- A --(6)--+ | | | | | | +--(2)-- B --(9)---+ | | | | | +--(16)+ +--(10)-- C -+ | | | | +--(4)-- D (8)+ | | | +-(99)+ (Figure foo?) -- -- In fact you would probably need a table to make sure that -- you did not make a mistake. In either case it is hard for -- most people to figure out the what the topology is much -- less imagine packet actions. Actually, you need a figure to make sure that you did not make a mistake, and a second set of eyes to compare what you said to what you apparently meant. -- -- Now compare this to: -- -- The network and costs are as shown in figure foo. -- Is the above actually figure foo? The reality is that it would be better to break it this way: In the network in figure foo, the link costs are as follows: A - B = 2 B - A = 6 +- A B -+ A - D = 4 || D - A = 16 +- D C -+ B - C = 10 C - B = 9 Figure foo C - D = 8 D - C = 99 -- Simple text and the visualisation is already done for you -- so you can focus on the problem. -- The reality is that putting things entirely in pictures means that less validation of the intent of the picture is possible. Keeping pictures as simple as possible is, therefore, a goal since it is far easier to make mistakes in complex figures and far more difficult to determine that a mistake has been made. Using a mixture of text and figure(s), tables or - possibly - equations makes it both more understandable and easier to be certain of conveying the idea(s). For example, in the above, I could verify that I understand your intent by asking: From this it is apparent that the link cost (D-C) is 99, but the actual minimum cost of getting from D to C given by the formula: (D-A) + (A-B) + (B-C) = 16 + 2 + 10 = 28 Is that correct? If we choose to use a simple combination of representations, rather than strictly expecting a figure to explain it all, the figure is likely to be far simpler. For example, using an approach similar to the above, you could probably describe
RE: Normative figures
Stewart, See below... -- Eric -- -Original Message- -- From: Stewart Bryant [mailto:[EMAIL PROTECTED] -- Sent: Monday, January 09, 2006 6:50 PM -- To: Gray, Eric -- Cc: ietf@ietf.org -- Subject: Re: Normative figures -- -- Eric -- -- You are missing the point. -- Out of politeness, let's consider the possibility that I am not missing the point. -- -- I was picking an example out of thin air, but it is the -- type of construct that we use all the time in fast-reroute. -- I follow that discussion in each WG in which it has come up. -- -- The example was four routers connected together in a -- square with some randomly chosen asymetric costs. Such a -- network is trivial, but FRR need to cope with arbitary -- network fragments with arbitary costs, so there are lots -- of fragments that we have created for study the properties -- of. -- Yes. And, if we're talking about wanting to make the figures normative, I assume we are talking about a specification. In that case, it is far more important that the description MUST be precise, than it is that it MAY be convenient. As I indicated in my response, it is possible to represent a lot of different topologies in simplistic figures with textual descriptions and - potentially other means of helping readers to understand _and_ verify the specification. -- -- One of the ways to operate on the fragment is to draw it and -- then to figure out the packet flows, consequences of failure etc -- etc. -- -- Now the question is why should the examples in our drafts be forced -- by our ability to describe them, rather than being the example that -- most clearly illustrates the problem and its solution? -- There are two issues built into this question: 1) Are the available tools preventing completion of the task, or do they merely constrain the ways in which it can be done? 2) Is the purpose of the task to describe, or to illustrate, the specified solution? I believe these two questions - taken separately - have been beaten utterly to death. In the first issue, it is clear that a number of people feel that the current tools merely constrain the specification process. To many of those people, this is a good thing. In addition, nobody has yet been able to demonstrate an example of a case where the tools - as they are (and including the potential for PDF use) are preventing the completion of any specification task. In the second issue, it SHOULD be clear that the task is to give as precise a description as possible. Most everyone agrees that figures, tables and equations MAY help. Most everyone agrees that they MAY occasionally be necessary for correct understanding of a specification. And most people agree that text MUST be precise and complete for specification wherever it is possible to do so. Figures help to understand. In many cases, they are not required. The fact that an accurate description in text may not be easy to produce is not nearly as important as the fact that a description in text is easier to test for correctness. We write specifications so that they are easier to read, validate and understand, not so that they are easier to write. -- -- - Stewart -- -- -- Gray, Eric wrote: -- -- Stewart, -- --You realize that the text example you gave is meaningless - -- without making some (potentially non-obvious) assumptions, right? -- -- -- -Original Message- -- -- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] -- -- On Behalf Of Stewart Bryant -- -- Sent: Monday, January 09, 2006 2:47 PM -- -- To: Sam Hartman -- -- Cc: Harald Tveit Alvestrand; ietf@ietf.org -- -- Subject: Re: Normative figures -- -- -- -- Sam Hartman wrote: -- -- -- -- Hi. With the exception of packet diagrams, I think all -- -- the examples -- -- you bring up benefit significantly from clear textual -- description. -- -- -- -- Sam -- -- -- -- I am not saying that clear text is not needed to accompany -- -- a diagram. -- -- However a diagram allows a lot less text to be written -- producing a -- -- shorter clearer draft with less clutter. -- -- -- -- For example you could say the following in text : -- router A connects to -- -- router B and D, the cost from A to B is 2, and the -- cost from A to D is -- 4. -- --A --(2)-- B -- | -- +---(4)-- D -- -- -- Router B connects to router C. The cost to router A is 6, and -- -- the cost to router C is 10. -- -- + A --(6)--+ -- | | | -- | +--(2)-- B --(10)-- C -- | -- +--(4)-- D -- -- (Assumes cost is from router B in both cases) -- -- -- Router C connects to router D. The cost to router B is 9 -- -- and the cost to router D is 8. -- -- + A --(6)--+ -- | | | -- | +--(2)-- B --(9)---+ -- | | | -- | +--(10)-- C -- | | -- +--(4)-- D (8)---+ -- -- (Assumes cost is from router C in both cases) -- -- -- The cost from
Re: Normative figures
We write specifications so that they are easier to read, validate and understand, not so that they are easier to write. Eric We write specs so that they will be correctly implemented. Anything that makes a specification easier to correctly understand surely makes it more likely that it will be correctly implemented? The cost of incorrect implementation is so high that we can can afford to pay a relatively high cost in the effort and technology needed to read and write the specification. - Stewart ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Yes. And, if we're talking about wanting to make the figures normative, I assume we are talking about a specification. In that case, it is far more important that the description MUST be precise, than it is that it MAY be convenient. Please can we clarify the existing rules: For a standards track document is it technically acceptable to provide: A .pdf that is complete (but is non-normative under current rules) plus An ASCII text in which the background material refers to figures in the .pdf but which contains the essential normative statements. i.e. Is a standards track RFC approvable when it is correct in the technical sense, even if it is almost incomprehensible without the text, figures and equations from its non-normative twin. - Stewart ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
Re: Normative figures
Stewart Bryant wrote: We write specifications so that they are easier to read, validate and understand, not so that they are easier to write. Eric We write specs so that they will be correctly implemented. Anything that makes a specification easier to correctly understand surely makes it more likely that it will be correctly implemented? I'm a little confused. What is it about Eric's formulation of the statement that you take exception to in your followup question? They sound the same to me. (Or is it that you believe easier to write necessarily leads to will be more likely to be correctly implemented, and therefore easier to write should not be excluded as a desirable goal of our specification writing process?) cheers, gja ___ Ietf mailing list Ietf@ietf.org https://www1.ietf.org/mailman/listinfo/ietf
