From d9a0d6cf74c127e66030fbb9b744dca22f9bcd9d Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Sat, 27 Dec 2008 15:36:49 -0800 Subject: [PATCH] Factor out common parts of manpages. There was a lot of duplication in the sources for the manpages, because many of the programs have common options. This factors out some of the duplication into include files, using the man ".so" directive. It also uses the ".ds" directive to define strings that should be customized for each program's manpage. --- Makefile.am | 16 +++++------ controller/controller.8.in | 36 ++++--------------------- lib/common.man | 7 +++++ lib/daemon.man | 21 +++++++++++++++ lib/vlog.man | 4 +-- secchan/secchan.8.in | 36 ++++--------------------- soexpand.pl | 26 ++++++++++++++++++ subst | 5 ---- switch/switch.8.in | 4 ++- udatapath/udatapath.8.in | 53 ++++--------------------------------- utilities/dpctl.8.in | 13 +++------ utilities/ofp-discover.8.in | 13 +++------ utilities/ofp-kill.8.in | 10 +++---- utilities/vlogconf.8.in | 6 ++--- 14 files changed, 94 insertions(+), 156 deletions(-) create mode 100644 lib/common.man create mode 100644 lib/daemon.man create mode 100755 soexpand.pl delete mode 100755 subst diff --git a/Makefile.am b/Makefile.am index fd11c40a..2541437e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -45,20 +45,18 @@ noinst_LIBRARIES = noinst_PROGRAMS = noinst_SCRIPTS = -EXTRA_DIST += README.hwtables subst +EXTRA_DIST += README.hwtables soexpand.pl -do_subst = ($(srcdir)/subst VLOG_OPTIONS $(srcdir)/lib/vlog.man | \ - sed -e 's,[@]LOGDIR[@],$(LOGDIR),g' \ - -e 's,[@]PKIDIR[@],$(PKIDIR),g' \ - -e 's,[@]RUNDIR[@],$(RUNDIR),g' \ - -e 's,[@]pkgdatadir[@],$(pkgdatadir),g' \ - -e 's,[@]PERL[@],$(PERL),g') -ro_script = sed "`printf '1a\\' && printf '\\n\# -*- buffer-read-only: t -*-'`" ro_c = echo '/* -*- mode: c; buffer-read-only: t -*- */' SUFFIXES = .in .in: - $(do_subst) < $< > $@ + $(PERL) $(srcdir)/soexpand.pl -I$(srcdir) < $< | \ + sed -e 's,[@]LOGDIR[@],$(LOGDIR),g' \ + -e 's,[@]PKIDIR[@],$(PKIDIR),g' \ + -e 's,[@]RUNDIR[@],$(RUNDIR),g' \ + -e 's,[@]pkgdatadir[@],$(pkgdatadir),g' \ + -e 's,[@]PERL[@],$(PERL),g' > $@ include lib/automake.mk include secchan/automake.mk diff --git a/controller/controller.8.in b/controller/controller.8.in index b608c939..45b8ce17 100644 --- a/controller/controller.8.in +++ b/controller/controller.8.in @@ -1,3 +1,5 @@ +.ds PN controller + .TH controller 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME @@ -124,37 +126,9 @@ through the controller and every packet is flooded. This option is most useful for debugging. It reduces switching performance, so it should not be used in production. -.TP -\fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR] -Causes a file (by default, \fBcontroller.pid\fR) to be created indicating -the PID of the running process. If \fIpidfile\fR is not specified, or -if it does not begin with \fB/\fR, then it is created in -\fB@RUNDIR@\fR. - -.TP -\fB-f\fR, \fB--force\fR -By default, when \fB-P\fR or \fB--pidfile\fR is specified and the -specified pidfile already exists and is locked by a running process, -\fBcontroller\fR refuses to start. Specify \fB-f\fR or \fB--force\fR -to cause it to instead overwrite the pidfile. - -When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no -effect. - -.TP -\fB-D\fR, \fB--detach\fR -Causes \fBcontroller\fR to detach itself from the foreground session and -run as a background process. - -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -@VLOG_OPTIONS@ - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. +.so lib/daemon.man +.so lib/vlog.man +.so lib/common.man .SH EXAMPLES diff --git a/lib/common.man b/lib/common.man new file mode 100644 index 00000000..1f12bb7c --- /dev/null +++ b/lib/common.man @@ -0,0 +1,7 @@ +.TP +.BR \-h ", " \-\^\-help +Prints a brief help message to the console. + +.TP +.BR \-V ", " \-\^\-version +Prints version information to the console. diff --git a/lib/daemon.man b/lib/daemon.man new file mode 100644 index 00000000..4ab65680 --- /dev/null +++ b/lib/daemon.man @@ -0,0 +1,21 @@ +.TP +\fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR] +Causes a file (by default, \fB\*(PN.pid\fR) to be created indicating +the PID of the running process. If \fIpidfile\fR is not specified, or +if it does not begin with \fB/\fR, then it is created in +\fB@RUNDIR@\fR. + +.TP +\fB-f\fR, \fB--force\fR +By default, when \fB-P\fR or \fB--pidfile\fR is specified and the +specified pidfile already exists and is locked by a running process, +\fB\*(PN\fR refuses to start. Specify \fB-f\fR or \fB--force\fR +to cause it to instead overwrite the pidfile. + +When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no +effect. + +.TP +\fB-D\fR, \fB--detach\fR +Causes \fB\*(PN\fR to detach itself from the foreground session and +run as a background process. diff --git a/lib/vlog.man b/lib/vlog.man index 6bc7d298..f6d2acc6 100644 --- a/lib/vlog.man +++ b/lib/vlog.man @@ -40,6 +40,4 @@ Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Refer to \fB--log-file\fR[\fB=\fIfile\fR] Enables logging to a file. If \fIfile\fR is specified, then it is used as the exact name for the log file. The default log file name -used if \fIfile\fR is omitted is @LOGDIR@/\fIprogram\fR.log, where -\fIprogram\fR is the name of the program as invoked -(e.g. \fBsecchan\fR). +used if \fIfile\fR is omitted is \fB@LOGDIR@/\*(PN.log\fR. diff --git a/secchan/secchan.8.in b/secchan/secchan.8.in index 3c5cc62e..9006f980 100644 --- a/secchan/secchan.8.in +++ b/secchan/secchan.8.in @@ -1,3 +1,5 @@ +.ds PN secchan + .TH secchan 8 "October 2008" "OpenFlow" "OpenFlow Manual" .SH NAME @@ -424,37 +426,9 @@ require the controller to send the CA certificate, but \fBcontroller\fR(8) can be configured to do so with the \fB--peer-ca-cert\fR option. -.TP -\fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR] -Causes a file (by default, \fBsecchan.pid\fR) to be created indicating -the PID of the running process. If \fIpidfile\fR is not specified, or -if it does not begin with \fB/\fR, then it is created in -\fB@RUNDIR@\fR. - -.TP -\fB-f\fR, \fB--force\fR -By default, when \fB-P\fR or \fB--pidfile\fR is specified and the -specified pidfile already exists and is locked by a running process, -\fBsecchan\fR refuses to start. Specify \fB-f\fR or \fB--force\fR -to cause it to instead overwrite the pidfile. - -When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no -effect. - -.TP -\fB-D\fR, \fB--detach\fR -Causes \fBsecchan\fR to detach itself from the foreground session and -run as a background process. - -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -@VLOG_OPTIONS@ - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. +.so lib/daemon.man +.so lib/vlog.man +.so lib/common.man .SH "SEE ALSO" diff --git a/soexpand.pl b/soexpand.pl new file mode 100755 index 00000000..4e130056 --- /dev/null +++ b/soexpand.pl @@ -0,0 +1,26 @@ +use strict; +use warnings; +use Getopt::Long; + +my ($exit_code) = 0; +my (@include_dirs); +Getopt::Long::Configure ("bundling"); +GetOptions("I|include=s" => \@include_dirs) or exit(1); +@include_dirs = ('.') if !@include_dirs; +OUTER: while () { + if (my ($name) = /^\.so (\S+)$/) { + foreach my $dir (@include_dirs, '.') { + if (open(INNER, "$dir/$name")) { + while () { + print $_; + } + close(INNER); + next OUTER; + } + } + print STDERR "$name not found in: ", join(' ', @include_dirs), "\n"; + $exit_code = 1; + } + print $_; +} +exit $exit_code; diff --git a/subst b/subst deleted file mode 100755 index c2e71df8..00000000 --- a/subst +++ /dev/null @@ -1,5 +0,0 @@ -#! /bin/sh -exec sed -e "/^@$1@\$/{ -r $2 -d -}" diff --git a/switch/switch.8.in b/switch/switch.8.in index c6aa6060..17db7b1c 100644 --- a/switch/switch.8.in +++ b/switch/switch.8.in @@ -1,3 +1,5 @@ +.ds PN switch + .TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME @@ -110,7 +112,7 @@ run as a background process. .BR \-h ", " \-\^\-help Prints a brief help message to the console. -@VLOG_OPTIONS@ +.so lib/vlog.man .TP .BR \-V ", " \-\^\-version diff --git a/udatapath/udatapath.8.in b/udatapath/udatapath.8.in index ad992c5d..838a44db 100644 --- a/udatapath/udatapath.8.in +++ b/udatapath/udatapath.8.in @@ -1,3 +1,5 @@ +.ds PN udatapath + .TH udatapath 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME @@ -118,54 +120,9 @@ private key to identify a trustworthy datapath. Specifies a PEM file containing the CA certificate used to verify that the datapath is connected to a trustworthy secure channel. -.TP -\fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR] -Causes a file (by default, \fBudatapath.pid\fR) to be created indicating -the PID of the running process. If \fIpidfile\fR is not specified, or -if it does not begin with \fB/\fR, then it is created in -\fB@RUNDIR@\fR. - -.TP -\fB-f\fR, \fB--force\fR -By default, when \fB-P\fR or \fB--pidfile\fR is specified and the -specified pidfile already exists and is locked by a running process, -\fBudatapath\fR refuses to start. Specify \fB-f\fR or \fB--force\fR -to cause it to instead overwrite the pidfile. - -When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no -effect. - -.TP -\fB-D\fR, \fB--detach\fR -Causes \fBudatapath\fR to detach itself from the foreground session and -run as a background process. - -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -.TP -\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] -Sets the logging level for \fImodule\fR in \fIfacility\fR to -\fIlevel\fR. The \fImodule\fR may be any valid module name (as -displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the -special name \fBANY\fR to set the logging levels for all modules. The -\fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels -for logging to the system log or to the console, respectively, or -\fBANY\fR to set the logging levels for both facilities. If it is -omitted, \fIfacility\fR defaults to \fBANY\fR. The \fIlevel\fR must -be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating -the minimum severity of a message for it to be logged. If it is -omitted, \fIlevel\fR defaults to \fBdbg\fR. - -.TP -\fB-v\fR, \fB--verbose\fR -Sets the maximum logging verbosity level, equivalent to -\fB--verbose=ANY:ANY:dbg\fR. - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. +.so lib/daemon.man +.so lib/vlog.man +.so lib/common.man .SH BUGS The userspace datapath's performance lags significantly behind that of diff --git a/utilities/dpctl.8.in b/utilities/dpctl.8.in index 595148e9..da07d452 100644 --- a/utilities/dpctl.8.in +++ b/utilities/dpctl.8.in @@ -1,3 +1,5 @@ +.ds PN dpctl + .TH dpctl 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME @@ -450,15 +452,8 @@ private key to identify a trustworthy controller. Specifies a PEM file containing the CA certificate used to verify that a switch is trustworthy. -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -@VLOG_OPTIONS@ - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. +.so lib/vlog.man +.so lib/common.man .SH EXAMPLES diff --git a/utilities/ofp-discover.8.in b/utilities/ofp-discover.8.in index 304c3c7d..50e6975a 100644 --- a/utilities/ofp-discover.8.in +++ b/utilities/ofp-discover.8.in @@ -1,3 +1,5 @@ +.ds PN ofp\-discover + .TH ofp\-discover 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME @@ -93,15 +95,8 @@ to cause it to instead overwrite the pidfile. When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no effect. -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -@VLOG_OPTIONS@ - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. +.so lib/vlog.man +.so lib/common.man .SH BUGS diff --git a/utilities/ofp-kill.8.in b/utilities/ofp-kill.8.in index 7b45bf0a..6c1298ca 100644 --- a/utilities/ofp-kill.8.in +++ b/utilities/ofp-kill.8.in @@ -1,3 +1,5 @@ +.ds PN ofp\-kill + .TH ofp\-kill 8 "May 2008" "OpenFlow" "OpenFlow Manual" .SH NAME @@ -34,13 +36,7 @@ By default, \fBSIGTERM\fR is sent. Causes \fBofp\-kill\fR to ignore all errors without printing a message to \fBstderr\fR, and to exit with return code 0. -.TP -.BR \-h ", " \-\^\-help -Prints a brief help message to the console. - -.TP -.BR \-V ", " \-\^\-version -Prints version information to the console. +.so lib/common.man .SH "EXIT CODE" diff --git a/utilities/vlogconf.8.in b/utilities/vlogconf.8.in index f1acf62b..b120a387 100644 --- a/utilities/vlogconf.8.in +++ b/utilities/vlogconf.8.in @@ -1,3 +1,5 @@ +.ds PN vlogconf + .TH vlogconf 8 "June 2008" "OpenFlow" "OpenFlow Manual" .SH NAME @@ -171,10 +173,8 @@ is useful after rotating log files, to cause a new log file to be used.) .SH OPTIONS -.TP -\fB\-h\fR, \fB\-\^\-help\fR -Prints a brief help message to the console and exits. +.so lib/common.man .SH "SEE ALSO" -- 2.30.2