Merge branch 'tor-github/pr/1468'

2 files changed, 123 insertions, 96 deletions

diff --git a/changes/ticket32277 b/changes/ticket32277
new file mode 100644
index 0000000000..1ef0c4ab56
--- /dev/null
+++ b/changes/ticket32277
@@ -0,0 +1,5 @@
+  o Documentation (manpage):
+    - In the tor(1) manpage, reword and improve formatting of the
+      COMMAND-LINE OPTIONS and DESCRIPTION sections.  Closes ticket
+      32277.  Based on work by Swati Thacker as part of Google Season
+      of Docs.
diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 05e7fc948a..d5297f77ce 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -18,145 +18,167 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Tor is a connection-oriented anonymizing communication
-service. Users choose a source-routed path through a set of nodes, and
-negotiate a "virtual circuit" through the network, in which each node
-knows its predecessor and successor, but no others. Traffic flowing down
-the circuit is unwrapped by a symmetric key at each node, which reveals
-the downstream node. +
-
-Basically, Tor provides a distributed network of servers or relays ("onion routers").
-Users bounce their TCP streams -- web traffic, ftp, ssh, etc. -- around the
-network, and recipients, observers, and even the relays themselves have
-difficulty tracking the source of the stream.
-
-By default, **tor** will act as a client only.  To help the network
-by providing bandwidth as a relay, change the **ORPort** configuration
-option -- see below.  Please also consult the documentation on the Tor
-Project's website.
+
+Tor is a connection-oriented anonymizing communication service. Users
+choose a source-routed path through a set of nodes, and negotiate a
+"virtual circuit" through the network. Each node in a virtual circuit
+knows its predecessor and successor nodes, but no other nodes. Traffic
+flowing down the circuit is unwrapped by a symmetric key at each node,
+which reveals the downstream node. +
+
+Basically, Tor provides a distributed network of servers or relays
+("onion routers").  Users bounce their TCP streams, including web
+traffic, ftp, ssh, etc., around the network, so that recipients,
+observers, and even the relays themselves have difficulty tracking the
+source of the stream.
+
+[NOTE]
+By default, **tor** acts as a client only.  To help the network by
+providing bandwidth as a relay, change the **ORPort** configuration
+option as mentioned below.  Please also consult the documentation on
+the Tor Project's website.
 
 COMMAND-LINE OPTIONS
 --------------------
-[[opt-h]] **-h**, **--help**::
+
+Tor has a powerful command-line interface. This section lists optional
+arguments you can specify at the command line using the **`tor`**
+command.
+
+Configuration options can be specified on the command line in the
+format **`--`**_OptionName_ _OptionValue_, on the command line in the
+format _OptionName_ _OptionValue_, or in a configuration file.  For
+instance, you can tell Tor to start listening for SOCKS connections on
+port 9999 by passing either **`--SocksPort 9999`** or **`SocksPort
+9999`** on the command line, or by specifying **`SocksPort 9999`** in
+the configuration file.  On the command line, quote option values that
+contain spaces. For instance, if you want Tor to log all debugging
+messages to **`debug.log`**, you must specify **`--Log "debug file
+debug.log"`**.
+
+NOTE: Configuration options on the command line override those in
+configuration files.  See **<<conf-format,THE CONFIGURATION FILE
+FORMAT>>** for more information.
+
+The following options in this section are only recognized on the
+**`tor`** command line, not in a configuration file.
+
+[[opt-h]] **`-h`**, **`--help`**::
     Display a short help message and exit.
 
-[[opt-f]] **-f** __FILE__::
+[[opt-f]] **`-f`** __FILE__::
     Specify a new configuration file to contain further Tor configuration
-    options OR pass *-* to make Tor read its configuration from standard
-    input. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not
-    found)
+    options, or pass *-* to make Tor read its configuration from standard
+    input. (Default: **`@CONFDIR@/torrc`**, or **`$HOME/.torrc`** if
+    that file is not found)
 
-[[opt-allow-missing-torrc]] **--allow-missing-torrc**::
-    Do not require that configuration file specified by **-f** exist if
-    default torrc can be accessed.
+[[opt-allow-missing-torrc]] **`--allow-missing-torrc`**::
+    Allow the configuration file specified by **`-f`** to be missing,
+    if the defaults-torrc file (see below) is accessible.
 
-[[opt-defaults-torrc]] **--defaults-torrc** __FILE__::
+[[opt-defaults-torrc]] **`--defaults-torrc`** __FILE__::
     Specify a file in which to find default values for Tor options.  The
     contents of this file are overridden by those in the regular
     configuration file, and by those on the command line. (Default:
-    @CONFDIR@/torrc-defaults.)
+    **`@CONFDIR@/torrc-defaults`**.)
 
-[[opt-ignore-missing-torrc]] **--ignore-missing-torrc**::
-    Specifies that Tor should treat a missing torrc file as though it
+[[opt-ignore-missing-torrc]] **`--ignore-missing-torrc`**::
+    Specify that Tor should treat a missing torrc file as though it
     were empty. Ordinarily, Tor does this for missing default torrc files,
     but not for those specified on the command line.
 
-[[opt-hash-password]] **--hash-password** __PASSWORD__::
-    Generates a hashed password for control port access.
+[[opt-hash-password]] **`--hash-password`** __PASSWORD__::
+    Generate a hashed password for control port access.
 
-[[opt-list-fingerprint]] **--list-fingerprint**::
+[[opt-list-fingerprint]] **`--list-fingerprint`**::
     Generate your keys and output your nickname and fingerprint.
 
-[[opt-verify-config]] **--verify-config**::
-    Verify the configuration file is valid.
+[[opt-verify-config]] **`--verify-config`**::
+    Verify whether the configuration file is valid.
 
-[[opt-serviceinstall]] **--service install** [**--options** __command-line options__]::
+[[opt-serviceinstall]] **`--service install`** [**`--options`** __command-line options__]::
     Install an instance of Tor as a Windows service, with the provided
     command-line options. Current instructions can be found at
     https://www.torproject.org/docs/faq#NTService
 
-[[opt-service]] **--service** **remove**|**start**|**stop**::
+[[opt-service]] **`--service`** **`remove`**|**`start`**|**`stop`**::
     Remove, start, or stop a configured Tor Windows service.
 
-[[opt-nt-service]] **--nt-service**::
+[[opt-nt-service]] **`--nt-service`**::
     Used internally to implement a Windows service.
 
-[[opt-list-torrc-options]] **--list-torrc-options**::
+[[opt-list-torrc-options]] **`--list-torrc-options`**::
     List all valid options.
 
-[[opt-list-deprecated-options]] **--list-deprecated-options**::
+[[opt-list-deprecated-options]] **`--list-deprecated-options`**::
     List all valid options that are scheduled to become obsolete in a
     future version. (This is a warning, not a promise.)
 
-[[opt-list-modules]] **--list-modules**::
-    For each optional module, list whether or not it has been compiled
-    into Tor.  (Any module not listed is not optional in this version of Tor.)
+[[opt-list-modules]] **`--list-modules`**::
+    List whether each optional module has been compiled into Tor.
+    (Any module not listed is not optional in this version of Tor.)
 
-[[opt-version]] **--version**::
+[[opt-version]] **`--version`**::
     Display Tor version and exit. The output is a single line of the format
     "Tor version [version number]."  (The version number format
     is as specified in version-spec.txt.)
 
-[[opt-quiet]] **--quiet**|**--hush**::
-    Override the default console log.  By default, Tor starts out logging
-    messages at level "notice" and higher to the console.  It stops doing so
-    after it parses its configuration, if the configuration tells it to log
-    anywhere else.  You can override this behavior with the **--hush** option,
-    which tells Tor to only send warnings and errors to the console, or with
-    the **--quiet** option, which tells Tor not to log to the console at all.
-
-[[opt-keygen]] **--keygen** [**--newpass**]::
-   Running "tor --keygen" creates a new ed25519 master identity key for a
-   relay, or only a fresh temporary signing key and certificate, if you
-   already have a master key.  Optionally you can encrypt the master identity
-   key with a passphrase: Tor will ask you for one. If you don't want to
-   encrypt the master key, just don't enter any passphrase when asked. +
- +
-   The **--newpass** option should be used with --keygen only when you need
-   to add, change, or remove a passphrase on an existing ed25519 master
-   identity key. You will be prompted for the old passphase (if any),
-   and the new passphrase (if any). +
- +
-   When generating a master key, you will probably want to use
-   **--DataDirectory** to control where the keys
-   and certificates will be stored, and **--SigningKeyLifetime** to
-   control their lifetimes.  Their behavior is as documented in the
-   server options section below.  (You must have write access to the specified
-   DataDirectory.) +
- +
-   To use the generated files, you must copy them to the DataDirectory/keys
-   directory of your Tor daemon, and make sure that they are owned by the
-   user actually running the Tor daemon on your system.
-
-**--passphrase-fd** __FILEDES__::
-    Filedescriptor to read the passphrase from.  Note that unlike with the
+[[opt-quiet]] **`--quiet`**|**`--hush`**::
+    Override the default console logging behavior.  By default, Tor
+    starts out logging messages at level "notice" and higher to the
+    console.  It stops doing so after it parses its configuration, if
+    the configuration tells it to log anywhere else.  These options
+    override the default console logging behavior.  Use the
+    **`--hush`** option if you want Tor to log only warnings and
+    errors to the console, or use the **`--quiet`** option if you want
+    Tor not to log to the console at all.
+
+[[opt-keygen]] **`--keygen`** [**`--newpass`**]::
+    Running **`tor --keygen`** creates a new ed25519 master identity key
+    for a relay, or only a fresh temporary signing key and
+    certificate, if you already have a master key.  Optionally, you
+    can encrypt the master identity key with a passphrase.  When Tor
+    asks you for a passphrase and you don't want to encrypt the master
+    key, just don't enter any passphrase when asked. +
+ +
+    Use the **`--newpass`** option with **`--keygen`** only when you
+    need to add, change, or remove a passphrase on an existing ed25519
+    master identity key. You will be prompted for the old passphase
+    (if any), and the new passphrase (if any).
++
+[NOTE]
+    When generating a master key, you may want to use
+    **`--DataDirectory`** to control where the keys and certificates
+    will be stored, and **`--SigningKeyLifetime`** to control their
+    lifetimes.  See the server options section to learn more about the
+    behavior of these options.  You must have write access to the
+    specified DataDirectory.
++
+[normal]
+    To use the generated files, you must copy them to the
+    __DataDirectory__/**`keys`** directory of your Tor daemon, and
+    make sure that they are owned by the user actually running the Tor
+    daemon on your system.
+
+**`--passphrase-fd`** __FILEDES__::
+    File descriptor to read the passphrase from.  Note that unlike with the
     tor-gencert program, the entire file contents are read and used as
     the passphrase, including any trailing newlines.
-    Default: read from the terminal.
+    If the file descriptor is not specified, the passphrase is read
+    from the terminal by default.
 
-[[opt-key-expiration]] **--key-expiration** [**purpose**]::
-    The **purpose** specifies which type of key certificate to determine
-    the expiration of.  The only currently recognised **purpose** is
+[[opt-key-expiration]] **`--key-expiration`** [__purpose__]::
+    The __purpose__ specifies which type of key certificate to determine
+    the expiration of.  The only currently recognised __purpose__ is
     "sign". +
  +
-    Running "tor --key-expiration sign" will attempt to find your signing
-    key certificate and will output, both in the logs as well as to stdout,
-    the signing key certificate's expiration time in ISO-8601 format.
-    For example, the output sent to stdout will be of the form:
-    "signing-cert-expiry: 2017-07-25 08:30:15 UTC"
-
-Other options can be specified on the command-line in the format "--option
-value", in the format "option value", or in a configuration file.  For
-instance, you can tell Tor to start listening for SOCKS connections on port
-9999 by passing --SocksPort 9999 or SocksPort 9999 to it on the command line,
-or by putting "SocksPort 9999" in the configuration file.  You will need to
-quote options with spaces in them: if you want Tor to log all debugging
-messages to debug.log, you will probably need to say **--Log** `"debug file
-debug.log"`.
-
-Options on the command line override those in configuration files. See the
-next section for more information.
+    Running **`tor --key-expiration sign`** will attempt to find your
+    signing key certificate and will output, both in the logs as well
+    as to stdout, the signing key certificate's expiration time in
+    ISO-8601 format.  For example, the output sent to stdout will be
+    of the form: "signing-cert-expiry: 2017-07-25 08:30:15 UTC"
 
+[[conf-format]]
 THE CONFIGURATION FILE FORMAT
 -----------------------------