[ovs-dev] [PATCH v2] docs: directly convert dot diagrams into eps for generating PDF

Shu Shen shu.shen at radisys.com
Sat Jan 31 00:02:40 UTC 2015


The previous workflow is to convert dot diagrams into .pic format and
embed into manpages; double borders and arrows were not used in dot but
introduced in .pic conversion; edge routing in .pic was also worse than
dot.

The updated workflow specifies directly in dot diagram double
boarders for "root set" nodes and solid/bold styles and arrows for
edges. The converted .eps diagram has improved routing. The .eps diagram
is embedded into PDF using groff PSPIC marco package when converting the
manpages.  PSPIC package is automatically loaded by groff when output to
PS/PDF.

In addition, 'constraint=false' option is removed from weak
references to allow positioning of node boxes to avoid overlapping
between multiple edges between "Mirror" and "Port" in
ovs-vswitchd.conf.db.

Signed-off-by: Shu Shen <shu.shen at radisys.com>
---

Changes made in V2:
 - Filter out .eps files from manpages when make manpage-check target
   This prevents manpage-check to perform checks on .eps files

 Makefile.am          |  2 +-
 build-aux/dist-docs  |  4 +--
 ovsdb/automake.mk    |  2 +-
 ovsdb/dot2pic        | 80 ----------------------------------------------------
 ovsdb/ovsdb-doc      |  5 +---
 ovsdb/ovsdb-dot.in   |  7 +++--
 vswitchd/automake.mk | 20 +++++++------
 vtep/automake.mk     | 20 +++++++------
 8 files changed, 33 insertions(+), 107 deletions(-)
 delete mode 100755 ovsdb/dot2pic

diff --git a/Makefile.am b/Makefile.am
index 3e5e0b2..2f3ee56 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -303,7 +303,7 @@ if HAVE_GROFF
 ALL_LOCAL += manpage-check
 manpage-check: $(man_MANS) $(dist_man_MANS) $(noinst_man_MANS)
 	@error=false; \
-	for manpage in $?; do \
+	for manpage in $(filter-out %.eps,$?); do \
 		LANG=en_US.UTF-8 groff -w mac -w delim -w escape -w input -w missing -w tab -T utf8 -man -p -z $$manpage >$@.tmp 2>&1; \
 		if grep warning: $@.tmp; then error=:; fi; \
 		rm -f $@.tmp; \
diff --git a/build-aux/dist-docs b/build-aux/dist-docs
index 5857c1c..04e7d81 100755
--- a/build-aux/dist-docs
+++ b/build-aux/dist-docs
@@ -46,7 +46,7 @@ mkdir $distdir
 # Install manpages.
 make install-man mandir="$abs_distdir"/man
 (cd $distdir && mv `find man -type f` . && rm -rf man)
-manpages=`cd $distdir && echo *`
+manpages=`cd $distdir && find ! -iname '*.eps' -type f -print0 |sort -z | sed -r 's/\.\// /g'`
 
 # Start writing index.html.
 exec 3>$distdir/index.html
@@ -102,7 +102,7 @@ EOF
 # cause the groff HTML output engine to segfault (!).
 (cd $distdir
  for manpage in $manpages; do
-     man -l -Tps $manpage | ps2pdf - > $manpage.pdf
+     groff -man -Tps $manpage | ps2pdf - > $manpage.pdf
      man -l -Tutf8 $manpage | sed 's/.//g' > $manpage.txt
      (echo '<html><head><meta charset="UTF-8"></head><body><pre>'
       man -l -Tutf8 $manpage | sed '
diff --git a/ovsdb/automake.mk b/ovsdb/automake.mk
index a66974a..0c3a94c 100644
--- a/ovsdb/automake.mk
+++ b/ovsdb/automake.mk
@@ -99,7 +99,7 @@ EXTRA_DIST += ovsdb/ovsdb-doc
 OVSDB_DOC = $(run_python) $(srcdir)/ovsdb/ovsdb-doc
 
 # ovsdb-dot
-EXTRA_DIST += ovsdb/ovsdb-dot.in ovsdb/dot2pic
+EXTRA_DIST += ovsdb/ovsdb-dot.in
 noinst_SCRIPTS += ovsdb/ovsdb-dot
 DISTCLEANFILES += ovsdb/ovsdb-dot
 OVSDB_DOT = $(run_python) $(srcdir)/ovsdb/ovsdb-dot.in
diff --git a/ovsdb/dot2pic b/ovsdb/dot2pic
deleted file mode 100755
index d682be5..0000000
--- a/ovsdb/dot2pic
+++ /dev/null
@@ -1,80 +0,0 @@
-#! /usr/bin/perl
-
-# Copyright (c) 2009, 2010, 2011, 2013 Nicira, Inc.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at:
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-use strict;
-use warnings;
-
-use Getopt::Long;
-
-my $font_scale = 0;
-GetOptions("f=i" => \$font_scale) || exit 1;
-
-my ($scale) = 1;
-printf ".ps %+d\n", -$font_scale if $font_scale;
-print ".PS\n";
-print "linethick = 1;\n";
-while (<>) {
-    if (/^graph/) {
-        (undef, $scale) = split;
-    } elsif (/^node/) {
-        my (undef, $name, $x, $y, $width, $height, $label, $style, $shape, $color, $fillcolor) = split;
-        $x *= $scale;
-        $y *= $scale;
-        $width *= $scale;
-        $height *= $scale;
-        print "linethick = ", ($style eq 'bold' ? 0.5 : 1.0), ";\n";
-        print "box at $x,$y wid $width height $height \"$name\"\n";
-        if ($style eq 'bold') {
-            my $inset = 2.0 / 72.0;
-            $width -= $inset * 2;
-            $height -= $inset * 2;
-            print "box at $x,$y wid $width height $height\n";
-        }
-    } elsif (/edge/) {
-        my (undef, $tail, $head, $n, $rest) = split(' ', $_, 5);
-        my @xy;
-        for (1...$n) {
-            my ($x, $y);
-            ($x, $y, $rest) = split(' ', $rest, 3);
-            push(@xy, [$x * $scale, $y * $scale]);
-        }
-        my ($label, $xl, $yl);
-        if (scalar(my @junk = split(' ', $rest)) > 2) {
-            if ($rest =~ s/^"([^"]*)"\s+//) {
-                $label = $1;
-            } else {
-                ($label, $rest) = split(' ', $rest, 2);
-            }
-            ($xl, $yl, $rest) = split(' ', $rest, 3);
-            $xl *= $scale;
-            $yl *= $scale;
-        }
-        my ($style, $color) = split(' ', $rest);
-
-        print "linethick = ", ($style eq 'dotted' ? 0.5 : 1), ";\n";
-
-        print "spline -> from $xy[0][0],$xy[0][1]";
-        for (my ($i) = 0; $i <= $#xy; $i++) {
-            print " to $xy[$i][0],$xy[$i][1]";
-        }
-        print "\n";
-
-        print "\"$label\" at $xl,$yl\n" if defined($label);
-    }
-
-}
-printf ".ps %+d\n", $font_scale if $font_scale;
-print ".PE\n";
diff --git a/ovsdb/ovsdb-doc b/ovsdb/ovsdb-doc
index 6200915..08d22d7 100755
--- a/ovsdb/ovsdb-doc
+++ b/ovsdb/ovsdb-doc
@@ -341,10 +341,7 @@ constraint on the number of allowed values: \\fB?\\fR for zero or one,
 represent strong references; thin lines represent weak references.
 .RS -1in
 """
-        erStream = open(erFile, "r")
-        for line in erStream:
-            s += line + '\n'
-        erStream.close()
+	s += ".PSPIC "+erFile+"\n"
         s += ".RE\\}\n"
 
     for node in tableNodes:
diff --git a/ovsdb/ovsdb-dot.in b/ovsdb/ovsdb-dot.in
index 006d7ed..ffbe121 100755
--- a/ovsdb/ovsdb-dot.in
+++ b/ovsdb/ovsdb-dot.in
@@ -30,8 +30,9 @@ def printEdge(tableName, type, baseType, label):
         options = {}
         options['label'] = '"%s%s"' % (label, arity)
         if baseType.ref_type == 'weak':
-            options['constraint'] = 'false'
-            options['style'] = 'dotted'
+            options['style'] = 'solid'
+	else:
+	    options['style'] = 'bold'
         print "\t%s -> %s [%s];" % (
             tableName,
             baseType.ref_table_name,
@@ -50,7 +51,7 @@ def schemaToDot(schemaFile, arrows):
     for tableName, table in schema.tables.iteritems():
         options = {}
         if table.is_root:
-            options['style'] = 'bold'
+            options['peripheries'] = '2'
         print "\t%s [%s];" % (
             tableName,
             ', '.join(['%s=%s' % (k,v) for k,v in options.items()]))
diff --git a/vswitchd/automake.mk b/vswitchd/automake.mk
index 80affe9..1dcbbdf 100644
--- a/vswitchd/automake.mk
+++ b/vswitchd/automake.mk
@@ -25,18 +25,22 @@ pkgdata_DATA += vswitchd/vswitch.ovsschema
 
 # vswitch E-R diagram
 #
-# If "python" or "dot" is not available, then we do not add graphical diagram
-# to the documentation.
+# If "python" or "dot" or "groff" is not available, then we do not add
+# graphical diagram to the documentation.
 if HAVE_PYTHON
 if HAVE_DOT
+if HAVE_GROFF
 vswitchd/vswitch.gv: ovsdb/ovsdb-dot.in vswitchd/vswitch.ovsschema
-	$(AM_V_GEN)$(OVSDB_DOT) --no-arrows $(srcdir)/vswitchd/vswitch.ovsschema > $@
-vswitchd/vswitch.pic: vswitchd/vswitch.gv ovsdb/dot2pic
-	$(AM_V_GEN)(dot -T plain < vswitchd/vswitch.gv | $(PERL) $(srcdir)/ovsdb/dot2pic -f 3) > $@.tmp && \
+	$(AM_V_GEN)$(OVSDB_DOT) $(srcdir)/vswitchd/vswitch.ovsschema > $@
+vswitchd/vswitch.eps: vswitchd/vswitch.gv
+	$(AM_V_GEN)(dot -T eps < vswitchd/vswitch.gv) > $@.tmp && \
 	mv $@.tmp $@
-VSWITCH_PIC = vswitchd/vswitch.pic
-VSWITCH_DOT_DIAGRAM_ARG = --er-diagram=$(VSWITCH_PIC)
-DISTCLEANFILES += vswitchd/vswitch.gv vswitchd/vswitch.pic
+VSWITCH_PIC = vswitchd/vswitch.eps
+# Install eps diagram to the same folder as the documentation
+VSWITCH_DOT_DIAGRAM_ARG = --er-diagram=vswitch.eps
+man_MANS += $(VSWITCH_PIC)
+DISTCLEANFILES += vswitchd/vswitch.gv $(VSWITCH_PIC)
+endif
 endif
 endif
 
diff --git a/vtep/automake.mk b/vtep/automake.mk
index eac81d0..4197e40 100644
--- a/vtep/automake.mk
+++ b/vtep/automake.mk
@@ -26,18 +26,22 @@ pkgdata_DATA += vtep/vtep.ovsschema
 
 # VTEP E-R diagram
 #
-# If "python" or "dot" is not available, then we do not add graphical diagram
-# to the documentation.
+# If "python" or "dot" or "groff" is not available, then we do not add
+# graphical diagram to the documentation.
 if HAVE_PYTHON
 if HAVE_DOT
+if HAVE_GROFF
 vtep/vtep.gv: ovsdb/ovsdb-dot.in vtep/vtep.ovsschema
-	$(AM_V_GEN)$(OVSDB_DOT) --no-arrows $(srcdir)/vtep/vtep.ovsschema > $@
-vtep/vtep.pic: vtep/vtep.gv ovsdb/dot2pic
-	$(AM_V_GEN)(dot -T plain < vtep/vtep.gv | $(PERL) $(srcdir)/ovsdb/dot2pic -f 3) > $@.tmp && \
+	$(AM_V_GEN)$(OVSDB_DOT) $(srcdir)/vtep/vtep.ovsschema > $@
+vtep/vtep.eps: vtep/vtep.gv
+	$(AM_V_GEN)(dot -T eps < vtep/vtep.gv) > $@.tmp && \
 	mv $@.tmp $@
-VTEP_PIC = vtep/vtep.pic
-VTEP_DOT_DIAGRAM_ARG = --er-diagram=$(VTEP_PIC)
-DISTCLEANFILES += vtep/vtep.gv vtep/vtep.pic
+VTEP_PIC = vtep/vtep.eps
+# Install eps diagram to the same folder as the documentation
+VTEP_DOT_DIAGRAM_ARG = --er-diagram=vtep.eps
+man_MANS += $(VTEP_PIC)
+DISTCLEANFILES += vtep/vtep.gv $(VTEP_PIC)
+endif
 endif
 endif
 
-- 
1.9.1




More information about the dev mailing list