docs: Consistently format each form of an option on a separate line.

Most options were formatted like this in the manpage: -o ARGUMENT --option ARGUMENT but a few were formatted like this: -o ARGUMENT | --option ARGUMENT or even as: -o, --option ARGUMENT The former seems least confusing to me, so switch all of the documentation to this format. Signed-off-by: Ben Pfaff <[email protected]>
dhanunjaya · Feb 27, 2012 · 91005f0 · 91005f0
1 parent dd1ba5b
commit 91005f0
Show file tree

Hide file tree

Showing 6 changed files with 71 additions and 41 deletions.
diff --git a/lib/common.man b/lib/common.man
@@ -1,7 +1,12 @@
-.TP
-\fB\-h\fR, \fB\-\-help\fR
+.de IQ
+.  br
+.  ns
+.  IP "\\$1"
+..
+.IP "\fB\-h\fR"
+.IQ "\fB\-\-help\fR"
 Prints a brief help message to the console.
 .
-.TP
-\fB\-V\fR, \fB\-\-version\fR
+.IP "\fB\-V\fR"
+.IQ "\fB\-\-version\fR"
 Prints version information to the console.
diff --git a/lib/vlog.man b/lib/vlog.man
@@ -1,5 +1,10 @@
-.TP
-\fB\-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB\-\-verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
+.de IQ
+.  br
+.  ns
+.  IP "\\$1"
+..
+.IP "\fB\-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]"
+.IQ "\fB\-\-verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]"
 .
 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 \fIlevel\fR:
@@ -28,13 +33,13 @@ logged.  If it is omitted, \fIlevel\fR defaults to \fBdbg\fR.  See
 \fBovs\-appctl\fR(8) for a definition of each log level.
 .RE
 .
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
+.IP "\fB\-v\fR"
+.IQ "\fB\-\-verbose\fR"
 Sets the maximum logging verbosity level, equivalent to
 \fB\-\-verbose=ANY:ANY:dbg\fR.
 .
-.TP
-\fB\-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB\-\-verbose=PATTERN:\fIfacility\fB:\fIpattern\fR
+.IP "\fB\-vPATTERN:\fIfacility\fB:\fIpattern\fR"
+.IQ "\fB\-\-verbose=PATTERN:\fIfacility\fB:\fIpattern\fR"
 Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
 \fBovs\-appctl\fR(8) for a description of the valid syntax for \fIpattern\fR.
 .

diff --git a/utilities/ovs-dpctl.8.in b/utilities/ovs-dpctl.8.in
@@ -1,3 +1,8 @@
+.de IQ
+.  br
+.  ns
+.  IP "\\$1"
+..
 .TH ovs\-dpctl 8 "August 2009" "Open vSwitch" "Open vSwitch Manual"
 .ds PN ovs\-dpctl
 .
@@ -115,11 +120,13 @@ not OpenFlow flow entries.  By deleting them, the process that set them
 up may be confused about their disappearance.
 .
 .SH OPTIONS
-.IP "\fB\-s\fR, \fB\-\-statistics\fR"
+.IP "\fB\-s\fR"
+.IQ "\fB\-\-statistics\fR"
 Causes the \fBshow\fR command to print packet and byte counters for
 each port within the datapaths that it shows.
-.TP
-\fB\-t\fR, \fB\-\-timeout=\fIsecs\fR
+.
+.IP "\fB\-t\fR"
+.IQ "\fB\-\-timeout=\fIsecs\fR"
 Limits \fBovs\-dpctl\fR runtime to approximately \fIsecs\fR seconds.  If
 the timeout expires, \fBovs\-dpctl\fR will exit with a \fBSIGALRM\fR
 signal.

diff --git a/utilities/ovs-pki.8.in b/utilities/ovs-pki.8.in
@@ -1,3 +1,8 @@
+.de IQ
+.  br
+.  ns
+.  IP "\\$1"
+..
 .TH ovs\-pki 8 "May 2008" "Open vSwitch" "Open vSwitch Manual"
 
 .SH NAME
@@ -270,8 +275,8 @@ older than \fIAGE\fR, which must in one of the forms \fIN\fBs\fR,
 \fIN\fBmin\fR, \fIN\fBh\fR, \fIN\fBday\fR.  The default is \fB1day\fR.
 
 .SH OPTIONS
-.TP
-\fB\-k\fR \fItype\fR | \fB\-\^\-key=\fItype\fR
+.IP "\fB\-k\fR \fItype\fR"
+.IQ "\fB\-\^\-key=\fItype\fR"
 For the \fBinit\fR command, sets the public key algorithm to use for
 the new PKI hierarchy.  For the \fBreq\fR and \fBreq+sign\fR commands,
 sets the public key algorithm to use for the key to be generated,
@@ -280,8 +285,8 @@ commands, the value has no effect.
 
 The \fItype\fR may be \fBrsa\fR (the default) or \fBdsa\fR.
 
-.TP
-\fB\-B\fR \fInbits\fR | \fB\-\^\-bits=\fInbits\fR
+.IP "\fB\-B\fR \fInbits\fR"
+.IQ "\fB\-\^\-bits=\fInbits\fR"
 Sets the number of bits in the key to be generated.  When RSA keys are
 in use, this option affects only the \fBinit\fR, \fBreq\fR, and
 \fBreq+sign\fR commands, and the same value should be given each time.
@@ -290,37 +295,37 @@ command.
 
 The value must be at least 1024.  The default is 2048.
 
-.TP
-\fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR
+.IP "\fB\-D\fR \fIfile\fR"
+.IQ "\fB\-\^\-dsaparam=\fIfile\fR"
 Specifies an alternate location for the \fBdsaparam.pem\fR file
 required by the \fBreq\fR and \fBreq+sign\fR commands.  This option
 affects only these commands, and only when DSA keys are used.
 
 The default is \fBdsaparam.pem\fR under the PKI hierarchy.
 
-.TP
-\fB\-b\fR | \fB\-\^\-batch\fR
+.IP "\fB\-b\fR"
+.IQ "\fB\-\^\-batch\fR"
 Suppresses the interactive verification of fingerprints that the
 \fBsign\fR and \fBapprove\fR commands by default require.
 
-.TP
-\fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR
+.IP "\fB\-d\fR \fIdir\fR"
+.IQ "\fB\-\^\-dir=\fR\fIdir\fR"
 Specifies the location of the PKI hierarchy to be used or created by
 the command (default: \fB@PKIDIR@\fR).  All commands, except \fBreq\fR,
 need access to a PKI hierarchy.
 
-.TP
-\fB\-f\fR | \fB\-\^\-force\fR
+.IP "\fB\-f\fR"
+.IQ "\fB\-\^\-force\fR"
 By default, \fBovs\-pki\fR will not overwrite existing files or
 directories.  This option overrides this behavior.
 
-.TP
-\fB\-l\fR \fIfile\fR | \fB\-\^\-log=\fIfile\fR
+.IP "\fB\-l\fR \fIfile\fR"
+.IQ "\fB\-\^\-log=\fIfile\fR"
 Sets the log file to \fIfile\fR.  Default:
 \fB@LOGDIR@/ovs\-pki.log\fR.
 
-.TP
-\fB\-h\fR | \fB\-\^\-help\fR
+.IP "\fB\-h\fR"
+.IQ "\fB\-\^\-help\fR"
 Prints a help usage message and exits.
 
 .SH "SEE ALSO"

diff --git a/utilities/ovs-test.8.in b/utilities/ovs-test.8.in
@@ -1,3 +1,8 @@
+.de IQ
+.  br
+.  ns
+.  IP "\\$1"
+..
 .TH ovs\-test 1 "October 2011" "Open vSwitch" "Open vSwitch Manual"
 .
 .SH NAME
@@ -53,13 +58,14 @@ interface that he originally intended to test.
 .
 .SH OPTIONS
 .
-.TP
-\fB\-s\fR, \fB\-\-server\fR \fIport\fR
+.IP "\fB\-s \fIport\fR"
+.IQ "\fB\-\-server\fR \fIport\fR"
 Run in server mode and wait for a client to establish XML RPC Control
 Connection on TCP \fIport\fR. It is recommended to have ethtool installed on
 the server so that it could retrieve information about NIC driver.
-.TP
-\fB\-c\fR, \fB\-\-client\fR \fIserver1\fR \fIserver2\fR
+.
+.IP "\fB\-c \fIserver1\fR \fIserver2\fR"
+.IQ "\fB\-\-client \fIserver1\fR \fIserver2\fR"
 Run in client mode and schedule tests between \fIserver1\fR and \fIserver2\fR,
 where each \fIserver\fR must be given in following format -
 ControlIP[:ControlPort][,TestIP[:TestPort]]. If TestIP is omitted then
@@ -68,8 +74,9 @@ TCP port where server will listen for incoming XML/RPC control
 connections to schedule tests (by default it is 15531). TestPort
 is port which will be used by server to listen for test traffic
 (by default it is 15532).
-.TP
-\fB\-b\fR, \fB\-\-bandwidth\fR \fIbandwidth\fR
+.
+.IP "\fB\-b \fIbandwidth\fR"
+.IQ "\fB\-\-bandwidth\fR \fIbandwidth\fR"
 Target bandwidth for UDP tests. The \fIbandwidth\fR must be given in bits per
 second. It is possible to use postfix M or K to alter the target bandwidth
 magnitude.
@@ -105,8 +112,6 @@ client will use TCP port 15531 to establish control channel).
 .IP
 .B ovs\-test -c 1.2.3.4 1.2.3.5
 .
-.TP
-
 .SH SEE ALSO
 .
 .BR ovs\-vswitchd (8),

diff --git a/utilities/ovs-vlan-test.8.in b/utilities/ovs-vlan-test.8.in
@@ -1,3 +1,8 @@
+.de IQ
+.  br
+.  ns
+.  IP "\\$1"
+..
 .TH ovs\-vlan\-test 1 "December 2010" "Open vSwitch" "Open vSwitch Manual"
 .
 .SH NAME
@@ -43,8 +48,8 @@ test against a single \fBovs\-vlan\-test\fR server concurrently.
 .
 .SH OPTIONS
 .
-.TP
-\fB\-s\fR, \fB\-\-server\fR
+.IP "\fB\-s\fR"
+.IQ "\fB\-\-server\fR"
 Run in server mode.
 .
 .so lib/common.man
@@ -81,8 +86,6 @@ Run an \fBovs\-vlan\-test\fR client with a control server located at
 .IP
 .B ovs\-vlan\-test 172.16.0.142:8080 1.2.3.4
 .
-.TP
-
 .SH SEE ALSO
 .
 .BR ovs\-vswitchd (8),