Skip to content

Commit

Permalink
Fix excessive white space in manpages.
Browse files Browse the repository at this point in the history
In nroff manpages, a blank line adds vertical white space.  When this is
followed by another command that also starts a new paragraph, the result
is a vertical skip twice as big as the normal inter-paragraph gap.  The
solution is to use a line that contains just "." for white space within
the manpage, instead of a blank line.  The resulting manpages look better.
  • Loading branch information
blp committed Feb 24, 2010
1 parent 02a987d commit a9b4a41
Show file tree
Hide file tree
Showing 12 changed files with 274 additions and 280 deletions.
2 changes: 1 addition & 1 deletion lib/common.man
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.TP
\fB-h\fR, \fB--help\fR
Prints a brief help message to the console.

.
.TP
\fB-V\fR, \fB--version\fR
Prints version information to the console.
10 changes: 5 additions & 5 deletions lib/daemon.man
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,21 @@ 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--overwrite-pidfile\fR
By default, when \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--overwrite-pidfile\fR to cause it to instead
overwrite the pidfile.

.IP
When \fB--pidfile\fR is not specified, this option has no effect.

.
.TP
\fB--detach\fR
Causes \fB\*(PN\fR to detach itself from the foreground session and
run as a background process.

.
.TP
\fB--monitor\fR
Creates an additional process to monitor the \fB\*(PN\fR daemon. If
Expand All @@ -29,7 +29,7 @@ monitor process exits.
.IP
This option is normally used with \fB--detach\fR, but it also
functions without it.

.
.TP
\fB--no-chdir\fR
By default, when \fB--detach\fR is specified, \fB\*(PN\fR
Expand Down
3 changes: 2 additions & 1 deletion lib/dpif.man
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@
Datapath number \fIN\fR, where \fIN\fR is a number between 0 and 255,
inclusive. If \fItype\fR is given, it specifies the datapath provider of
\fBdp\fIN\fR, otherwise the default provider \fBsystem\fR is assumed.

.
.TP
[\fItype\fB@\fR]\fIname\fR
The name of the network device associated with the datapath's local
port. (\fB\*(PN\fR internally converts this into a datapath number,
as above.) If \fItype\fR is given, it specifies the datapath provider of
\fIname\fR, otherwise the default provider \fBsystem\fR is assumed.
.RE
4 changes: 2 additions & 2 deletions lib/ssl.man
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@
.IQ "\fB\-\-private\-key=\fIprivkey.pem\fR"
Specifies a PEM file containing the private key used as \fB\*(PN\fR's
identity for outgoing SSL connections.

.
.IP "\fB\-c\fR \fIcert.pem\fR"
.IQ "\fB\-\-certificate=\fIcert.pem\fR"
Specifies a PEM file containing a certificate that certifies the
private key specified on \fB\-p\fR or \fB\-\-private\-key\fR to be
trustworthy. The certificate must be signed by the certificate
authority (CA) that the peer in SSL connections will use to verify it.

.
.IP "\fB\-C\fR \fIswitch\-cacert.pem\fR"
.IQ "\fB\-\-ca\-cert=\fIswitch\-cacert.pem\fR"
Specifies a PEM file containing the CA certificate that \fB\*(PN\fR
Expand Down
4 changes: 2 additions & 2 deletions lib/vconn-active.man
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@ The specified SSL \fIport\fR (default: 6633) on the host at the given
\fIip\fR, which must be expressed as an IP address (not a DNS name).
The \fB\-\-private\-key\fR, \fB\-\-certificate\fR, and
\fB\-\-ca\-cert\fR options are mandatory when this form is used.

.
.IP "\fBtcp:\fIip\fR[\fB:\fIport\fR]"
The specified TCP \fIport\fR (default: 6633) on the host at the given
\fIip\fR, which must be expressed as an IP address (not a DNS name).

.
.TP
\fBunix:\fIfile\fR
The Unix domain server socket named \fIfile\fR.
6 changes: 3 additions & 3 deletions lib/vconn-passive.man
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@ The \fB\-\-private\-key\fR, \fB\-\-certificate\fR, and
default, \fB\*(PN\fR listens for connections to any local IP address,
but \fIip\fR may be specified to listen only for connections to the
given \fIip\fR.

.
.IP "\fBptcp:\fR[\fIport\fR][\fB:\fIip\fR]"
Listens for OpenFlow TCP connections on \fIport\fR (default: 6633).
By default, \fB\*(PN\fR listens for connections to any local IP
address, but \fIip\fR may be specified to listen only for connections
to the given \fIip\fR.

to the given \fIip\Ar.
.
.IP "\fBpunix:\fIfile\fR"
Listens for OpenFlow connections on the Unix domain server socket
named \fIfile\fR.
16 changes: 8 additions & 8 deletions lib/vlog.man
Original file line number Diff line number Diff line change
@@ -1,42 +1,42 @@
.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:

.
.RS
.IP \(bu
\fImodule\fR may be any valid module name (as displayed by the
\fB--list\fR action on \fBovs\-appctl\fR(8)), or the special name
\fBANY\fR to set the logging levels for all modules.

.
.IP \(bu
\fIfacility\fR may be \fBsyslog\fR, \fBconsole\fR, or \fBfile\fR to
set the levels for logging to the system log, the console, or a file
respectively, or \fBANY\fR to set the logging levels for both
facilities. If it is omitted, \fIfacility\fR defaults to \fBANY\fR.

.IP
Regardless of the log levels set for \fBfile\fR, logging to a file
will not take place unless \fB--log-file\fR is also specified (see
below).

.
.IP \(bu
\fIlevel\fR must be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR,
\fBinfo\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.
.RE

.
.TP
\fB-v\fR, \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
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.

.
.TP
\fB--log-file\fR[\fB=\fIfile\fR]
Enables logging to a file. If \fIfile\fR is specified, then it is
Expand Down
57 changes: 28 additions & 29 deletions utilities/ovs-appctl.8.in
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@
..
.TH ovs\-appctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual"
.ds PN ovs\-appctl

.
.SH NAME
ovs\-appctl \- utility for configuring running Open vSwitch daemons

.
.SH SYNOPSIS
\fBovs\-appctl\fR [\fB--target=\fItarget\fR | \fB-t\fR \fItarget\fR]
\fIcommand \fR[\fIarg\fR...]
Expand All @@ -24,14 +24,13 @@ commands for querying and adjusting its logging settings documented
under \fBLOGGING COMMANDS\fR below, and \fBovs\-vswitchd\fR in
particular accepts a number of additional commands documented in
\fBovs\-vswitchd\fR(8).

.PP
The \fBovs\-appctl\fR program provides a simple way to invoke these
commands. The command to be sent is specified on \fBovs\-appctl\fR's
command line as non-option arguments. \fBovs\-appctl\fR sends the
command and prints the daemon's response on standard output.

.PP
In normal use only a single option is accepted:

.IP "\fB\-t \fItarget\fR"
.IQ "\fB\-\-target=\fItarget\fR"
Tells \fBovs\-appctl\fR which daemon to contact.
Expand Down Expand Up @@ -81,90 +80,90 @@ message is logged to \fIfacility\fR, \fIpattern\fR determines the
message's formatting. Most characters in \fIpattern\fR are copied
literally to the log, but special escapes beginning with \fB%\fR are
expanded as follows:

.
.RS
.IP \fB%A\fR
The name of the application logging the message, e.g. \fBovs-vswitchd\fR.

.
.IP \fB%c\fR
The name of the module (as shown by \fBovs\-appctl --list\fR) logging
the message.

.
.IP \fB%d\fR
The current date and time in ISO 8601 format (YYYY-MM-DD HH:MM:SS).

.
.IP \fB%d{\fIformat\fB}\fR
The current date and time in the specified \fIformat\fR, which takes
the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).

.
.IP \fB%m\fR
The message being logged.

.
.IP \fB%N\fR
A serial number for this message within this run of the program, as a
decimal number. The first message a program logs has serial number 1,
the second one has serial number 2, and so on.

.
.IP \fB%n\fR
A new-line.

.
.IP \fB%p\fR
The level at which the message is logged, e.g. \fBDBG\fR.

.
.IP \fB%P\fR
The program's process ID (pid), as a decimal number.

.
.IP \fB%r\fR
The number of milliseconds elapsed from the start of the application
to the time the message was logged.

.
.IP \fB%%\fR
A literal \fB%\fR.
.RE

.
.IP
A few options may appear between the \fB%\fR and the format specifier
character, in this order:

.
.RS
.IP \fB-\fR
Left justify the escape's expansion within its field width. Right
justification is the default.

.
.IP \fB0\fR
Pad the field to the field width with \fB0\fRs. Padding with spaces
is the default.

.
.IP \fIwidth\fR
A number specifies the minimum field width. If the escape expands to
fewer characters than \fIwidth\fR then it is padded to fill the field
width. (A field wider than \fIwidth\fR is not truncated to fit.)
.RE

.
.IP
The default pattern for console output is \fB%d{%b %d
%H:%M:%S}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR.

.
.IP "\fBvlog/reopen\fR"
Causes the daemon to close and reopen its log file. (This
is useful after rotating log files, to cause a new log file to be
used.)

.IP
This has no effect if the target application was not invoked with the
\fB--log-file\fR option.

.
.SH OPTIONS

.
.so lib/common.man

.
.SH BUGS

.
The protocol used to speak to Open vSwitch daemons does not contain a
quoting mechanism, so command arguments should not generally contain
white space.

.
.SH "SEE ALSO"

.
\fBovs\-appctl\fR can control the following daemons:
.BR ovs\-vswitchd (8),
.BR ovs\-openflowd (8),
Expand Down
Loading

0 comments on commit a9b4a41

Please sign in to comment.