From 4441a01cbd42c9c02ce09eeb79020bf28c20a891 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Tue, 2 Dec 2014 11:04:16 -0800 Subject: [PATCH 1/1] dist-docs: New utility to generate a documentation bundle for the website. This utility isn't going to be as portable as most of the Open vSwitch utilities, unfortunately. I'm happy to take improvements to make it able to work with, e.g., the "man" program from BSD. (I haven't tested with that program, but I suspect that it is somewhat different from the GNU version.) The output of this program can already be viewed at: http://openvswitch.org/support/dist-docs/ Signed-off-by: Ben Pfaff Acked-by: Thomas Graf --- Makefile.am | 16 ++++- build-aux/dist-docs | 153 ++++++++++++++++++++++++++++++++++++++++ manpages.mk | 2 + third-party/automake.mk | 5 +- tutorial/automake.mk | 2 +- utilities/automake.mk | 2 +- vtep/automake.mk | 5 +- 7 files changed, 174 insertions(+), 11 deletions(-) create mode 100755 build-aux/dist-docs diff --git a/Makefile.am b/Makefile.am index ddc7acba8..46e861039 100644 --- a/Makefile.am +++ b/Makefile.am @@ -61,7 +61,10 @@ CLEANFILES = CLEAN_LOCAL = DISTCLEANFILES = PYCOV_CLEAN_FILES = build-aux/check-structs,cover -EXTRA_DIST = \ + +# A list of Markdown-formatted documentation that will automatically be +# included in the "make dist-docs" output. +docs = \ CONTRIBUTING.md \ CodingStyle.md \ DESIGN.md \ @@ -80,7 +83,6 @@ EXTRA_DIST = \ INSTALL.userspace.md \ INSTALL.Windows.md \ IntegrationGuide.md \ - NOTICE \ OPENFLOW-1.1+.md \ PORTING.md \ README.md \ @@ -88,12 +90,16 @@ EXTRA_DIST = \ README-native-tunneling.md \ REPORTING-BUGS.md \ TODO.md \ + WHY-OVS.md +EXTRA_DIST = \ + $(docs) \ + NOTICE \ .travis.yml \ .travis/build.sh \ .travis/prepare.sh \ - WHY-OVS.md \ boot.sh \ build-aux/cccl \ + build-aux/dist-docs \ build-aux/sodepends.pl \ build-aux/soexpand.pl \ $(MAN_FRAGMENTS) \ @@ -337,6 +343,10 @@ if LINUX_ENABLED cd datapath/linux && $(MAKE) modules_install endif +dist-docs: + VERSION=$(VERSION) $(srcdir)/build-aux/dist-docs $(srcdir) $(docs) +.PHONY: dist-docs + include m4/automake.mk include lib/automake.mk include ofproto/automake.mk diff --git a/build-aux/dist-docs b/build-aux/dist-docs new file mode 100755 index 000000000..5857c1cf5 --- /dev/null +++ b/build-aux/dist-docs @@ -0,0 +1,153 @@ +#! /bin/sh + +set -e + +# Check command line. +if test ! -d "$1" || test $# -lt 2; then + cat <&2 "$0: $1 not found in \$PATH, please install and try again" + exit 1 +} +search_path man +search_path markdown +search_path ps2pdf + +# Create dist-docs directory. +distdir=dist-docs +abs_distdir=`pwd`/dist-docs +rm -rf $distdir +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 *` + +# Start writing index.html. +exec 3>$distdir/index.html +cat >&3 < + + + Open vSwitch $VERSION Documentation + +

Open vSwitch $VERSION Documentation

+

Documents

+ +EOF + +# Add top-level documentation to index.html, giving it .txt extensions so +# that the webserver doesn't serve it as Markdown and make your web browser +# try to invoke some kind of external helper you don't have installed. +# +# Also translate documentation to HTML. +for file +do + title=`head -1 "$srcdir/$file"` + dir=$distdir/`dirname $file`; test -d "$dir" || mkdir "$dir" + cp "$srcdir/$file" "$distdir/$file.txt" + (cat < + + + $file (Open vSwitch $VERSION) + +EOF + markdown "$distdir/$file.txt" + echo "") > "$distdir/$file.html" + cat < + + + + +EOF +done >&3 + +# Add header for manpages to index.html. +cat >&3 < +

Manpages

+
$file$titleHTML, plain text
+EOF + +# Add manpages to index.html, translating them into PDF, HTML, and plain text. +# The HTML is just slightly marked up from the plain text version; although +# groff supports better HTML output, on my system some of the OVS manpages +# cause the groff HTML output engine to segfault (!). +(cd $distdir + for manpage in $manpages; do + man -l -Tps $manpage | ps2pdf - > $manpage.pdf + man -l -Tutf8 $manpage | sed 's/.//g' > $manpage.txt + (echo '
'
+      man -l -Tutf8 $manpage | sed '
+s/&/&/g
+s//>/g
+s,\(.\)\1,\1,g
+s,_\(.\),\1,g'
+      echo '
' + ) > $manpage.html + + name=`echo $manpage | sed 's/\.\([0-9]\)$/(\1)/'` + echo " " + done +) >&3 +cat >&3 < + +EOF + +# Create CSS style file. +cat >$distdir/style.css <<'EOF' +div { vertical-align:top; } +p { + vertical-align:baseline; +} +a { + text-decoration: none; + font-weight: 700; +} +a:hover { + color:#444; +} +a:visited { + color:#447099; +} +a:link { + color:#447099; +} + +body { + font-family: Arial,Helvetica,sans-serif; + font-size: 14px; + line-height: 1.5em; + color: #444; + background-color:#f5f5f5; +} +EOF diff --git a/manpages.mk b/manpages.mk index 179d6aa30..4a76cf16a 100644 --- a/manpages.mk +++ b/manpages.mk @@ -174,6 +174,7 @@ utilities/ovs-testcontroller.8: \ utilities/ovs-testcontroller.8.in \ lib/common.man \ lib/daemon.man \ + lib/ofp-version.man \ lib/ssl-peer-ca-cert.man \ lib/ssl.man \ lib/unixctl.man \ @@ -183,6 +184,7 @@ utilities/ovs-testcontroller.8: \ utilities/ovs-testcontroller.8.in: lib/common.man: lib/daemon.man: +lib/ofp-version.man: lib/ssl-peer-ca-cert.man: lib/ssl.man: lib/unixctl.man: diff --git a/third-party/automake.mk b/third-party/automake.mk index bce5f8b5e..fea5ac763 100644 --- a/third-party/automake.mk +++ b/third-party/automake.mk @@ -1,3 +1,2 @@ -EXTRA_DIST += \ - third-party/README.md \ - third-party/ofp-tcpdump.patch +docs += third-party/README.md +EXTRA_DIST += third-party/ofp-tcpdump.patch diff --git a/tutorial/automake.mk b/tutorial/automake.mk index 8a75a836f..3d22d7aa4 100644 --- a/tutorial/automake.mk +++ b/tutorial/automake.mk @@ -1,5 +1,5 @@ +docs += tutorial/Tutorial.md EXTRA_DIST += \ - tutorial/Tutorial.md \ tutorial/ovs-sandbox \ tutorial/t-setup \ tutorial/t-stage0 \ diff --git a/utilities/automake.mk b/utilities/automake.mk index ccdd4dcfa..834be5873 100644 --- a/utilities/automake.mk +++ b/utilities/automake.mk @@ -24,11 +24,11 @@ scripts_DATA += utilities/ovs-lib utilities/ovs-lib: $(top_builddir)/config.status +docs += utilities/ovs-command-compgen.INSTALL.md EXTRA_DIST += \ utilities/ovs-check-dead-ifs.in \ utilities/ovs-command-compgen.bash \ utilities/ovs-command-compgen-test.bash \ - utilities/ovs-command-compgen.INSTALL.md \ utilities/ovs-ctl.in \ utilities/ovs-dev.py \ utilities/ovs-docker \ diff --git a/vtep/automake.mk b/vtep/automake.mk index f2a1db290..eac81d0ae 100644 --- a/vtep/automake.mk +++ b/vtep/automake.mk @@ -17,9 +17,8 @@ vtep_vtep_ctl_LDADD = lib/libopenvswitch.la scripts_SCRIPTS += \ vtep/ovs-vtep -EXTRA_DIST += \ - vtep/ovs-vtep \ - vtep/README.ovs-vtep.md +docs += vtep/README.ovs-vtep.md +EXTRA_DIST += vtep/ovs-vtep # VTEP schema and IDL EXTRA_DIST += vtep/vtep.ovsschema -- 2.20.1
$namePDF, HTML, plain text