[ovs-dev] [PATCH] docs: Consistently format each form of an option on a separate line.

Wed Feb 22 20:52:19 UTC 2012

Looks good to me.

Ethan

On Tue, Feb 7, 2012 at 15:45, Ben Pfaff <blp at nicira.com> wrote:
> 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 <blp at nicira.com>
> ---
>  lib/common.man               |   13 +++++++++----
>  lib/vlog.man                 |   17 +++++++++++------
>  utilities/ovs-dpctl.8.in     |   13 ++++++++++---
>  utilities/ovs-pki.8.in       |   37 +++++++++++++++++++++----------------
>  utilities/ovs-test.8.in      |   21 +++++++++++++--------
>  utilities/ovs-vlan-test.8.in |    6 ++----
>  6 files changed, 66 insertions(+), 41 deletions(-)
>
> diff --git a/lib/common.man b/lib/common.man
> index ef4b4fa..4cbed0d 100644
> --- 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
> index 0fff860..a2316da 100644
> --- 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
> index bf7f97f..b49dd8a 100644
> --- 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
> index ecc8c96..e40fdee 100644
> --- 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 at 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 at 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
> index afc8221..87c8944 100644
> --- 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
> index 549dcad..539cbb5 100644
> --- a/utilities/ovs-vlan-test.8.in
> +++ b/utilities/ovs-vlan-test.8.in
> @@ -43,8 +43,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 +81,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),
> --
> 1.7.2.5
>
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> http://openvswitch.org/mailman/listinfo/dev