doc: made format of man page option lists consistent

11 files changed, 225 insertions, 353 deletions

diff --git a/doc/man/bcfg2-admin.txt b/doc/man/bcfg2-admin.txt
index 26e75050f..6169ec537 100644
--- a/doc/man/bcfg2-admin.txt
+++ b/doc/man/bcfg2-admin.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2-admin
@@ -19,36 +20,18 @@ administration.
 Options
 -------
 
--C *configfile*
-    Specify alternate bcfg2.conf location.
-
--E *encoding*
-    Specify the encoding of Cfg files.
-
--Q *path*
-    Specify the path to the server repository.
-
--S *https://server:port*
-    Manually specify the server location (as opposed to using the value
-    in bcfg2.conf).
-
--d
-    Enable debugging output.
-
--h
-    Print usage information.
-
--o *logfile*
-    Writes a log to the specified path.
-
---ssl-key=\ *key*
-    Specify the path to the SSL key.
-
--v
-    Enable verbose output.
-
--x *password*
-    Use 'password' for client communication.
+-C configfile     Specify alternate bcfg2.conf location.
+-E encoding       Specify the encoding of config files.
+-Q path           Specify the path to the server repository.
+-S server         Manually specify the server location (as opposed to
+                  using the value in bcfg2.conf). This should be in
+                  the format "https://server:port"
+-d                Enable debugging output.
+-h                Print usage information.
+-o logfile        Writes a log to the specified path.
+--ssl-key=key     Specify the path to the SSL key.
+-v                Enable verbose output.
+-x password       Use 'password' for client communication.
 
 Modes
 -----
diff --git a/doc/man/bcfg2-build-reports.txt b/doc/man/bcfg2-build-reports.txt
index eba8244f2..fc5c2e4fa 100644
--- a/doc/man/bcfg2-build-reports.txt
+++ b/doc/man/bcfg2-build-reports.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2-build-reports
@@ -19,19 +20,12 @@ reports. See the Bcfg2 manual for report setup information.
 Options
 -------
 
--A
-    Displays all data.
-
--c *configuration file*
-    Specify an alternate report configuration path. The default is
-    ``repo/etc/reports-configuration.xml``.
-
--h
-    Produce a help message.
-
--s *statistics path*
-    Use an alternative path for the statistics file. The default is
-    ``repo/etc/statistics.xml``.
+-A             Displays all data.
+-c configfile  Specify an alternate report configuration path. The
+               default is ``repo/etc/reports-configuration.xml``.
+-h             Print usage information.
+-s statsfile   Use an alternative path for the statistics file. The
+               default is ``repo/etc/statistics.xml``.
 
 See Also
 --------
diff --git a/doc/man/bcfg2-crypt.txt b/doc/man/bcfg2-crypt.txt
index 37e60482e..34bd1452d 100644
--- a/doc/man/bcfg2-crypt.txt
+++ b/doc/man/bcfg2-crypt.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2-crypt
@@ -23,54 +24,39 @@ usually figure out what to do.
 Options
 -------
 
--C *configfile*
-    Specify alternate bcfg2.conf location.
-
---decrypt, --encrypt
-    Specify which operation you'd like to perform.
-    :program:`bcfg2-crypt` can usually determine which is necessary
-    based on the contents of each file.
-
---cfg
-    Tell :program:`bcfg2-crypt` that an XML file should be encrypted in
-    its entirety rather than element-by-element. This is only necessary
-    if the file is an XML file whose name ends with *.xml* and whose
-    top-level tag is *<Properties>*. See [MODES] below for details.
-
---properties
-    Tell :program:`bcfg2-crypt` to process a file as an XML Properties
-    file, and encrypt the text of each element separately. This is
-    necessary if, for example, you've used a different top-level tag
-    than *Properties* in your Properties files. See [MODES] below for
-    details.
-
---stdout
-    Print the resulting file to stdout instead of writing it to a file.
-
---remove
-    Remove the plaintext file after it has been encrypted.  Only
-    meaningful for Cfg files.
-
---xpath *xpath*
-    Encrypt the character content of all elements that match the
-    specified XPath expression.  The default is *\*[@encrypted]* or
-    *\**; see [MODES] below for more details. Only meaningful for
-    Properties files.
-
--p *passphrase*
-    Specify the name of a passphrase specified in the *[encryption]*
-    section of *bcfg2.conf*. See [SELECTING PASSPHRASE] below for more
-    details.
-
--v
-    Be verbose.
-
--I
-    When encrypting a Properties file, interactively select the elements
-    whose data should be encrypted.
-
--h
-    Display help and exit.
+-C configfile         Specify alternate bcfg2.conf location.
+--decrypt, --encrypt  Select encryption or decryption mode for the
+                      given file(s). This is usually unnecessary, as
+                      :program:`bcfg2-crypt` can often determine which
+                      is necessary based on the contents of each file.
+--cfg                 An XML file should be encrypted in its entirety
+                      rather than element-by-element. This is only
+                      necessary if the file is an XML file whose name
+                      ends with *.xml* and whose top-level tag is
+                      *<Properties>*. See [MODES] below for details.
+--properties          Process a file as an XML Properties file, and
+                      encrypt the text of each element
+                      separately. This is necessary if, for example,
+                      you've used a different top-level tag than
+                      *Properties* in your Properties files. See
+                      [MODES] below for details.
+--stdout              Print the resulting file to stdout instead of
+                      writing it to a file.
+--remove              Remove the plaintext file after it has been
+                      encrypted.  Only meaningful for Cfg files.
+--xpath xpath         Encrypt the character content of all elements
+                      that match the specified XPath expression.  The
+                      default is *\*[@encrypted]* or *\**; see [MODES]
+                      below for more details. Only meaningful for
+                      Properties files.
+-p passphrase         Specify the name of a passphrase specified in
+                      the *[encryption]* section of *bcfg2.conf*. See
+                      [SELECTING PASSPHRASE] below for more details.
+-v                    Be verbose.
+-I                    When encrypting a Properties file, interactively
+                      select the elements whose data should be
+                      encrypted.
+-h                    Print usage information.
 
 Modes
 -----
diff --git a/doc/man/bcfg2-info.txt b/doc/man/bcfg2-info.txt
index 93d159474..0ce3ddd11 100644
--- a/doc/man/bcfg2-info.txt
+++ b/doc/man/bcfg2-info.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2-info
@@ -20,26 +21,13 @@ data examination and debugging purposes.
 Options
 -------
 
--C *configfile*
-    Specify alternate bcfg2.conf location.
-
--E *encoding*
-    Specify the encoding of config files.
-
--Q *repository path*
-    Specify the server repository path.
-
--d
-    Run in debug mode.
-
--h
-    Print usage information.
-
--p *profile*
-    Specify a profile.
-
--x *password*
-    Set the communication password.
+-C configfile     Specify alternate bcfg2.conf location.
+-E encoding       Specify the encoding of config files.
+-Q path           Specify the path to the server repository.
+-d                Enable debugging output.
+-h                Print usage information.
+-p profile        Specify a profile.
+-x password       Use 'password' for client communication.
 
 Modes
 -----
diff --git a/doc/man/bcfg2-lint.conf.txt b/doc/man/bcfg2-lint.conf.txt
index 5b61060f4..0eaa64339 100644
--- a/doc/man/bcfg2-lint.conf.txt
+++ b/doc/man/bcfg2-lint.conf.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2-lint.conf
diff --git a/doc/man/bcfg2-lint.txt b/doc/man/bcfg2-lint.txt
index 1cfedad4e..b7206bd31 100644
--- a/doc/man/bcfg2-lint.txt
+++ b/doc/man/bcfg2-lint.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2-lint
@@ -27,36 +28,31 @@ tool.
 Options
 -------
 
--C *configfile*
-    Specify alternate bcfg2.conf location.
-
--Q
-    Specify the server repository path.
-
--v
-    Be verbose.
-
---lint-config
-    Specify path to bcfg2-lint.conf (default ``/etc/bcfg2-lint.conf``).
-
---stdin
-    Rather than operating on all files in the Bcfg2 specification, only
-    validate a list of files supplied on stdin. This mode is
-    particularly useful in pre-commit hooks.
-
-    This makes a few assumptions:
-
-        Metadata files will only be checked if a valid chain of
-        XIncludes can be followed all the way from clients.xml or
-        groups.xml. Since there are multiple formats of metadata stored
-        in Metadata/ (i.e., clients and groups), there is no way to
-        determine which sort of data a file contains unless there is a
-        valid chain of XIncludes. It may be useful to always specify all
-        metadata files should be checked, even if not all of them have
-        changed.
-
-        Property files will only be validated if both the property file
-        itself and its matching schema are included on stdin.
+-C configfile     Specify alternate bcfg2.conf location.
+-Q path           Specify the path to the server repository.
+-v                Be verbose.
+--lint-config     Specify path to bcfg2-lint.conf (default
+                  ``/etc/bcfg2-lint.conf``).
+--stdin           Rather than operating on all files in the Bcfg2
+                  specification, only validate a list of files
+                  supplied on stdin. This mode is particularly useful
+                  in pre-commit hooks.
+
+                  This makes a few assumptions:
+
+                  Metadata files will only be checked if a valid chain
+                  of XIncludes can be followed all the way from
+                  clients.xml or groups.xml. Since there are multiple
+                  formats of metadata stored in Metadata/ (i.e.,
+                  clients and groups), there is no way to determine
+                  which sort of data a file contains unless there is a
+                  valid chain of XIncludes. It may be useful to always
+                  specify all metadata files should be checked, even
+                  if not all of them have changed.
+
+                  Property files will only be validated if both the
+                  property file itself and its matching schema are
+                  included on stdin.
 
 Plugins
 -------
diff --git a/doc/man/bcfg2-reports.txt b/doc/man/bcfg2-reports.txt
index dbc937711..201a379df 100644
--- a/doc/man/bcfg2-reports.txt
+++ b/doc/man/bcfg2-reports.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2-reports
@@ -25,8 +26,7 @@ standalone application. It does, however, use the models from
 Options
 -------
 
--h
-    Shows help and usage info about :program:`bcfg2-reports`.
+-h                Print usage information.
 
 Modes
 -----
@@ -36,74 +36,58 @@ The following are various modes available for :program:`bcfg2-reports`.
 Single-Host Modes
 +++++++++++++++++
 
--b, --bad *hostname*
-    Shows bad entries from the current interaction of *hostname*.
-
--e, --extra *hostname*
-    Shows extra entries from the current interaction of *hostname*.
-
--m, --modified *hostname*
-    Shows modified entries from the current interaction of *hostname*.
-
--s, --show *hostname*
-    Shows bad, modified, and extra entries from the current interaction
-    of *hostname*.
-
--t, --total *hostname*
-    Shows total number of managed and good entries from the current
-    interaction of *hostname*.
-
--x, --expire *hostname*
-    Toggles expired/unexpired state of *hostname*.
-
--a, --all
-    Show all hosts, including expired hosts.
+-b, --bad hostname       Shows bad entries from the current
+                         interaction of *hostname*.
+-e, --extra hostname     Shows extra entries from the current
+                         interaction of *hostname*.
+-m, --modified hostname  Shows modified entries from the current
+                         interaction of *hostname*.
+-s, --show hostname      Shows bad, modified, and extra entries from
+                         the current interaction of *hostname*.
+-t, --total hostname     Shows total number of managed and good
+                         entries from the current interaction of
+                         *hostname*.
+-x, --expire hostname    Toggles expired/unexpired state of
+                         *hostname*.
+-a, --all                Show all hosts, including expired hosts.
 
 Host Selection Modes
 ++++++++++++++++++++
 
--a, --all
-    Show all hosts, including expired hosts.
-
--c, --clean
-    Show only clean hosts.
-
--d, --dirty
-    Show only dirty hosts.
-
---stale
-    Show hosts that haven't run in the last 24 hours.
+-a, --all     Show all hosts, including expired hosts.
+-c, --clean   Show only clean hosts.
+-d, --dirty   Show only dirty hosts.
+--stale       Show hosts that haven't run in the last 24 hours.
 
 Entry Modes
 +++++++++++
 
---badentry=\ *entry type, entry name*
-    Shows only hosts whose current interaction has bad entries of type
-    *entry type* and name *entry name*.
-
---extraentry=\ *entry type, entry name*
-    Shows only hosts whose current interaction has extra entries of type
-    *entry type* and name *entry name*.
-
---entrystatus=\ *entry type, entry name*
-    Shows the status of entry type *entry type* and name *entry name*
-    on all hosts.
-
---modifiedentry
-    Shows only hosts whose current interaction has modifiedentries of
-    type *entry type* and name *entry name*.
+The following mode flags require either a comma-delimited list of any
+number of *<entry type>:<entry name>* arguments describing entries, or
+the *--file* option.
+
+--badentry=entrylist       Shows only hosts whose current interaction
+                           has bad entries matching the given entry or
+                           entries.
+--extraentry=entrylist     Shows only hosts whose current interaction
+                           has extra entries matching the given entry
+                           or entries.
+--entrystatus=entry        Shows the status of the single entry (given
+                           by *<entry type>:<entry name>*) on all
+                           hosts.
+--modifiedentry=entrylist  Shows only hosts whose current interaction
+                           has modified entries matching the given
+                           entry or entries.
 
 Entry Options
 ^^^^^^^^^^^^^
 
 The following options can be used with the above Entry Modes.
 
---fields=\ *FIELD,FIELD,...*
-    Only display the listed fields.
-
---file=\ *FILE*
-    Read TYPE:NAME pairs from the specified file instead of the command
-    line.
+--fields=fields  Only display the listed fields.  Takes a
+                 comma-delimited list of field names
+--file=file      Read *<entry type>:<entry name>* pairs from the
+                 specified file instead of the command line.
 
 See Also
 --------
diff --git a/doc/man/bcfg2-server.txt b/doc/man/bcfg2-server.txt
index dedc86549..d5945cad6 100644
--- a/doc/man/bcfg2-server.txt
+++ b/doc/man/bcfg2-server.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2-server
@@ -21,29 +22,18 @@ configurations to clients based on the data in its repository.
 Options
 -------
 
--C *configfile*
-    Specify alternate bcfg2.conf location.
-
--D *pidfile*
-    Daemonize, placing the program pid in the specified pidfile.
-
--E *encoding*
-    Specify the encoding of config files (default is UTF-8).
-
--Q *repo path*
-    Set repository path.
-
--S *https://server:port*
-    Set server address.
-
--d
-    Run :program:`bcfg2-server` in debug mode.
-
--v
-    Run :program:`bcfg2-server` in verbose mode.
-
---ssl-key=\ *ssl key*
-    Set path to SSL key.
+-C configfile     Specify alternate bcfg2.conf location.
+-D pidfile        Daemonize, placing the program pid in the specified
+                  pidfile.
+-E encoding       Specify the encoding of config files.
+-Q path           Specify the path to the server repository.
+-S server         Manually specify the server location (as opposed to
+                  using the value in bcfg2.conf). This should be in
+                  the format "https://server:port"
+-d                Enable debugging output.
+-v                Run in verbose mode.
+-h                Print usage information.
+--ssl-key=key     Specify the path to the SSL key.
 
 See Also
 --------
diff --git a/doc/man/bcfg2.conf.txt b/doc/man/bcfg2.conf.txt
index 9756c3891..942ead40d 100644
--- a/doc/man/bcfg2.conf.txt
+++ b/doc/man/bcfg2.conf.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2.conf
diff --git a/doc/man/bcfg2.txt b/doc/man/bcfg2.txt
index 54560127d..6a77a4a3c 100644
--- a/doc/man/bcfg2.txt
+++ b/doc/man/bcfg2.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 bcfg2
@@ -26,139 +27,86 @@ host. This process consists of the following steps.
 Options
 -------
 
--B
-    Configure everything except the given bundle(s).
-
--C *configfile*
-    Specify alternate bcfg2.conf location.
-
--D [*driver1,driver2*]
-    Specify a set of Bcfg2 tool drivers.
-
-    *NOTE: only drivers listed will be loaded. (e.g., if you do not
-    include POSIX, you will be unable to verify/install Path entries).*
-
--E *encoding*
-    Specify the encoding of config files.
-
--I
-    Run bcfg2 in interactive mode. The user will be prompted before
-    each change.
-
--O
-    Omit lock check.
-
--P
-    Run bcfg2 in paranoid mode. Diffs will be logged for configuration
-    files marked as paranoid by the Bcfg2 server.
-
--Q
-    Run bcfg2 in "bundle quick" mode, where only entries in a bundle are
-    verified or installed. This runs much faster than -q, but doesn't
-    provide statistics to the server at all. In order for this option to
-    work, the -b option must also be provided. This option is incompatible
-    with -r.
-
--R *retrycount*
-    Specify the number of times that the client will attempt to retry
-    network communication.
-
--S *https://server:port*
-    Manually specify the server location (as opposed to using the value
-    in bcfg2.conf).
-
--Z
-    Do not configure independent entries.
-
--b *bundle1:bundle2*
-    Run bcfg2 against one or multiple bundles in the configuration.
-
--c *cachefile*
-    Cache a copy of the configuration in cachefile.
-
---ca-cert=\ *cacert*
-    Specifiy the path to the SSL CA certificate.
-
--d
-    Run bcfg2 in debug mode.
-
--e
-    When in verbose mode, display extra entry information (temporary
-    until verbosity rework).
-
--f *path*
-    Configure from a file rather than querying the server.
-
--h
-    Print usage information.
-
--k
-    Run in bulletproof mode. This currently only affects behavior in
-    the debian toolset; it calls apt-get update and clean and dpkg
-    --configure --pending.
-
--l *whitelist|blacklist|none*
-    Run the client in the server decision list mode (unless "none"
-    is specified, which can be done in order to override the decision
-    list mode specified in bcfg2.conf). This approach is needed when
-    particular changes are deemed "high risk". It gives the ability
-    tocentrally specify these changes, but only install them on clients
-    when administrator supervision is available. Because collaborative
-    configuration is one of the remaining hard issues in configuration
-    management, these issues typically crop up in environments with
-    several administrators and much configuration variety. (This setting
-    will be ignored if the -f option is also specified).
-
--n
-    Run bcfg2 in dry-run mode. No changes will be made to the system.
-
--o *logfile*
-    Writes a log to the specified path.
-
--p *profile*
-    Assert a profile for the current client.
-
--q
-    Run bcfg2 in quick mode. Package checksum verification won't be
-    performed. This mode relaxes the constraints of correctness, and
-    thus should only be used in safe conditions.
-
--r *mode*
-    Cause bcfg2 to remove extra configuration elements it detects. Mode
-    is one of all, Services, or Packages. All removes all entries.
-    Likewise, Services and Packages remove only the extra configuration
-    elements of the respective type.
-
--s *servicemode*
-    Set bcfg2 interaction level for services. Default behavior is to
-    modify all services affected by reconfiguration. build mode attempts
-    to stop all services started. disabled suppresses all attempts to
-    modify services.
-
---ssl-cert=\ *cert*
-    Specify the path to the SSL certificate.
-
---ssl-cns=\ *CN1:CN2*
-    List of acceptable SSL server Common Names.
-
---ssl-key=\ *key*
-    Specify the path to the SSL key.
-
--u *user*
-    Attempt to authenticate as 'user'.
-
--t *timeout*
-    Set the timeout (in seconds) for client communication. Default is
-    90 seconds.
-
--v
-    Run bcfg2 in verbose mode.
-
--x *password*
-    Use 'password' for client communication.
-
--z
-    Only configure independent entries, ignore bundles.
+-B                Configure everything except the given bundle(s).
+-C configfile     Specify alternate bcfg2.conf location.
+-D drivers        Specify a comma-delimited set of Bcfg2 tool
+                  drivers. *NOTE: only drivers listed will be
+                  loaded. (e.g., if you do not include POSIX, you will
+                  be unable to verify/install Path entries).*
+-E encoding       Specify the encoding of config files.
+-I                Run bcfg2 in interactive mode. The user will be
+                  prompted before each change.
+-O                Omit lock check.
+-P                Run bcfg2 in paranoid mode. Diffs will be logged for
+                  configuration files marked as paranoid by the Bcfg2
+                  server.
+-Q                Run bcfg2 in "bundle quick" mode, where only entries
+                  in a bundle are verified or installed. This runs
+                  much faster than -q, but doesn't provide statistics
+                  to the server at all. In order for this option to
+                  work, the -b option must also be provided. This
+                  option is incompatible with -r.
+-R retrycount     Specify the number of times that the client will
+                  attempt to retry network communication.
+-S server         Manually specify the server location (as opposed to
+                  using the value in bcfg2.conf). This should be in
+                  the format "https://server:port"
+-Z                Do not configure independent entries.
+-b bundles        Run only the specified colon-delimited set of
+                  bundles.
+-c cachefile      Cache a copy of the configuration in cachefile.
+--ca-cert=cacert  Specifiy the path to the SSL CA certificate.
+-d                Enable debugging output.
+-e                When in verbose mode, display extra entry
+                  information.
+-f path           Configure from a file rather than querying the
+                  server.
+-h                Print usage information.
+-k                Run in bulletproof mode. This currently only
+                  affects behavior in the debian toolset; it calls
+                  apt-get update and clean and dpkg --configure
+                  --pending.
+-l decisionmode   Run the client in the specified decision list mode
+                  ("whitelist" or "blacklist"), or "none", which can
+                  be used in order to override the decision list mode
+                  specified in bcfg2.conf). This approach is needed
+                  when particular changes are deemed "high risk". It
+                  gives the ability tocentrally specify these changes,
+                  but only install them on clients when administrator
+                  supervision is available. Because collaborative
+                  configuration is one of the remaining hard issues in
+                  configuration management, these issues typically
+                  crop up in environments with several administrators
+                  and much configuration variety. (This setting will
+                  be ignored if the -f option is also specified).
+-n                Run bcfg2 in dry-run mode. No changes will be made
+                  to the system.
+-o logfile        Writes a log to the specified path.
+-p profile        Assert a profile for the current client.
+-q                Run bcfg2 in quick mode. Package checksum
+                  verification won't be performed. This mode relaxes
+                  the constraints of correctness, and thus should only
+                  be used in safe conditions.
+-r mode           Cause bcfg2 to remove extra configuration elements
+                  it detects. Mode is one of "all", "Services", or
+                  "Packages". "all" removes all entries. Likewise,
+                  "Services" and "Packages" remove only the extra
+                  configuration elements of the respective type.
+-s servicemode    Set bcfg2 interaction level for services. Default
+                  behavior is to modify all services affected by
+                  reconfiguration. "build" mode attempts to stop all
+                  services started. "disabled" suppresses all attempts
+                  to modify services.
+--ssl-cert=cert   Specify the path to the SSL certificate.
+--ssl-cns=CNs     Colon-delimited list of acceptable SSL server Common
+                  Names.
+--ssl-key=key     Specify the path to the SSL key.
+-u user           Attempt to authenticate as 'user'.
+-t timeout        Set the timeout (in seconds) for client
+                  communication. Default is 90 seconds.
+-v                Run bcfg2 in verbose mode.
+-x password       Use 'password' for client communication.
+-z                Only configure independent entries, ignore bundles.
 
 See Also
 --------
diff --git a/doc/man/index.txt b/doc/man/index.txt
index ae6b88ac2..2df4df8a2 100644
--- a/doc/man/index.txt
+++ b/doc/man/index.txt
@@ -1,3 +1,4 @@
+.. -*- mode: rst -*-
 .. vim: ft=rst
 
 .. _man-index: