Merge lp:~yarkot/mailman/docs-graphviz into lp:mailman

[yarko]

clean up graphviz graph syntax, to get rid of some forward graphviz/dot errors:

base graphviz: 2.26.3 (changes continue to work w/ this also);
tested graphviz: 2.28.0, 3.30.0

- remove line-continuation back-slashes (not needed; no longer tolerated by graphviz);
- clean up message flow graph (remove redundancies; make graph flow orderly / more readable);

[Barry Warsaw (barry)]

Thanks for taking this on Yarko.

On Mar 19, 2013, at 01:44 AM, yarko wrote:

>base graphviz: 2.26.3 (changes continue to work w/ this also);

Does it still look weird to you in 2.26.3? I'm still getting strange curvy
lines, but this could just be 2.26 acting stupid.

>tested graphviz: 2.28.0, 3.30.0

I don't have time right now to test this, but I saw that it looked better on
your box with the newer graphviz's. I don't have time to try to upgrade
Ubuntu's graphviz package (and given that Ubuntu is in feature freeze, I'd
have to justify getting the newer one in before 13.04). Given that it still
builds and doesn't look *worse* <wink>, I'll just go ahead and merge the
change.

Thanks for the contribution to Mailman!

[Barry Warsaw (barry)]

On Mar 22, 2013, at 05:43 AM, yarko wrote:

>If you were going to upgrade a minimum graphviz version, might as well bump
>to >= 2.30

I'll have to try to get that upgraded after the upcoming Debian Wheezy and
Ubuntu Raring releases.

[yarko (yarkot)]

Yes - for the record, it looks like graphviz (standalone too) 2.26.* incorrectly parses "records", so that rather than box1:field1->box2:field0, it effects/draws box2:field1->box1:field0; 2.28 draws correctly (but draws unnecessarily wavy arcs); 2.30 draws correctly, and nice, straight lines where appropriate too.

If you were going to upgrade a minimum graphviz version, might as well bump to >= 2.30

=== modified file 'src/mailman/docs/8-miles-high.rst'
--- src/mailman/docs/8-miles-high.rst	2012-12-30 23:24:26 +0000
+++ src/mailman/docs/8-miles-high.rst	2013-03-19 01:43:24 +0000
@@ -66,8 +66,8 @@
 
    digraph pipeline {
    node [shape=box, style=rounded, group=0]
-   { "MIME\ndelete" -> "cleanse headers" -> "add headers" -> \
-     "calculate\nrecipients" -> "to digest" -> "to archive" -> \
+   { "MIME\ndelete" -> "cleanse headers" -> "add headers" -> 
+     "calculate\nrecipients" -> "to digest" -> "to archive" ->
      "to outgoing" }
    node [shape=box, color=lightblue, style=filled, group=1]
    { rank=same; PIPELINE -> "MIME\ndelete" }
@@ -91,48 +91,54 @@
 .. graphviz::
 
    digraph chain_rules {
-     rankdir=LR    /* This gives the right orientation of the columns. */
-     rank=same
-     subgraph in { IN [shape=box, color=lightblue, style=filled] }
-     subgraph rules {
-       rankdir=TB
-       rank=same
-       node [shape=record]
-       approved [group=0, label="<f0> approved | {<f1> | <f2>}"]
-       emergency [group=0, label="<f0> emergency | {<f1> | <f2>}"]
-       loop [group=0, label="<f0> loop | {<f1> | <f2>}"]
-       modmember [group=0, label="<f0> member\nmoderated | {<f1> | <f2>}"]
-       administrivia [group=0, label="<f0> administrivia | <f1>"]
-       maxsize [group=0, label="<f0> max\ size | {<f1> | <f2>}"]
-       any [group=0, label="<f0> any | {<f1> | <f2>}"]
-       truth [label="<f0> truth | <f1>"]
-       approved:f1 -> emergency:f0 [weight=100]
-       emergency:f1 -> loop:f0
-       loop:f1 -> modmember:f0
-       modmember:f1 -> administrivia:f0
-       administrivia:f1 -> maxsize:f0
-       maxsize:f1 -> any:f0
-       any:f1 -> truth:f0
-     }
-     subgraph queues {
-       rankdir=TB
-       rank=same
-       node [shape=box, style=filled];
-       DISCARD [shape=invhouse, color=black, style=solid];
-       MODERATION [color=wheat];
-       HOLD [color=wheat];
-     }
-     { PIPELINE [shape=box, style=filled, color=cyan]; }
-
-     IN -> approved:f0
-     approved:f2 -> PIPELINE [minlen=2]
-     loop:f2 -> DISCARD
-     modmember:f2 -> MODERATION
-
-     emergency:f2:e -> HOLD
-     maxsize:f2 -> MODERATION
-     any:f2 -> MODERATION
-     truth:f1 -> PIPELINE [minlen=2]
+        rankdir=LR;    /* This gives the right orientation of the columns. */
+        rank=same;
+        subgraph in { IN [shape=box, color=lightblue, style=filled]; }
+        subgraph rules {
+          rankdir=TB;
+          node [shape=record];
+          approved [label="<in> approved | { <no> | <yes> }"];
+          emergency [label="<in> emergency | { <no> | <yes> }"];
+          loop [label="<in> loop | { <no> | <yes> }"];
+          modmember [label="<in> member\nmoderated | { <no> | <yes> }"];
+          administrivia [group="0", label="<in> administrivia | <always> "];
+          maxsize [label="<in> max\ size | {<in> no | <yes>}"];
+          any [label="<in> any | {<no> | <yes>}"];
+          truth [label="<in> truth | <always>"];
+
+        }
+
+        subgraph queues {
+          rankdir=TB;
+          node [shape=box, style=filled];
+          DISCARD [shape=invhouse, color=black, style=solid];
+          MODERATION [color=wheat];
+          HOLD [color=wheat];
+        }
+        { PIPELINE [shape=box, style=filled, color=cyan]; }
+
+        IN -> approved:in;
+        approved:no -> emergency:in [weight="100"];
+        approved:yes -> PIPELINE [minlen=2];
+
+        emergency:no -> loop:in;
+        emergency:yes -> HOLD;
+
+        loop:no -> modmember:in;
+        loop:yes -> DISCARD;
+
+        modmember:no -> administrivia:in;
+        modmember:yes -> MODERATION;
+
+        administrivia:always -> maxsize:in;
+
+        maxsize:no -> any:in;
+        maxsize:yes -> MODERATION;
+
+        any:no -> truth:in;
+        any:yes -> MODERATION;
+
+        truth:always -> PIPELINE [minlen=2];
    }