[ovs-dev] [PATCH v3] docs: directly convert dot diagrams into eps for generating PDF
Shu Shen
shu.shen at radisys.com
Wed Feb 4 07:53:29 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 V3:
- .eps files are no longer added to manpages (man_MANS). They are listed as
dependancy for make dist-docs target only and passed as enviroment variable
MAN_DEPS to the script dist-docs. The files will be copied by script dist-docs
into $abs_distdir for generating PDF only.
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 | 5 ++--
build-aux/dist-docs | 8 +++++-
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, 40 insertions(+), 107 deletions(-)
delete mode 100755 ovsdb/dot2pic
diff --git a/Makefile.am b/Makefile.am
index 3e5e0b2..5fdd6ec 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -119,6 +119,7 @@ dist_scripts_DATA =
INSTALL_DATA_LOCAL =
UNINSTALL_LOCAL =
man_MANS =
+man_DEPS =
MAN_FRAGMENTS =
MAN_ROOTS =
noinst_DATA =
@@ -346,8 +347,8 @@ if LINUX_ENABLED
cd datapath/linux && $(MAKE) modules_install
endif
-dist-docs:
- VERSION=$(VERSION) $(srcdir)/build-aux/dist-docs $(srcdir) $(docs)
+dist-docs: $(man_DEPS)
+ VERSION=$(VERSION) MAN_DEPS="$(man_DEPS)" $(srcdir)/build-aux/dist-docs $(srcdir) $(docs)
.PHONY: dist-docs
include m4/automake.mk
diff --git a/build-aux/dist-docs b/build-aux/dist-docs
index 5857c1c..2b31fac 100755
--- a/build-aux/dist-docs
+++ b/build-aux/dist-docs
@@ -48,6 +48,12 @@ make install-man mandir="$abs_distdir"/man
(cd $distdir && mv `find man -type f` . && rm -rf man)
manpages=`cd $distdir && echo *`
+# Install manpage dependencies
+for mandep in $MAN_DEPS; do
+ cp "$mandep" "$abs_distdir"
+done
+
+
# Start writing index.html.
exec 3>$distdir/index.html
cat >&3 <<EOF
@@ -102,7 +108,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..d5d57e1 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_DEPS += $(VSWITCH_PIC)
+DISTCLEANFILES += vswitchd/vswitch.gv $(VSWITCH_PIC)
+endif
endif
endif
diff --git a/vtep/automake.mk b/vtep/automake.mk
index eac81d0..e3767c2 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_DEPS += $(VTEP_PIC)
+DISTCLEANFILES += vtep/vtep.gv $(VTEP_PIC)
+endif
endif
endif
--
1.9.1
More information about the dev
mailing list