[tor-commits] [tor/master] Reword command-options in tor.1.txt

[dgoulet at torproject.org]

commit 8660a32d18e2583fb3003d9a6d9130df23829729
Author: Taylor Yu <catalyst at torproject.org>
Date:   Thu Oct 24 16:27:35 2019 -0500

    Reword command-options in tor.1.txt
    
    Reword the COMMAND-LINE OPTIONS section of tor.1.txt.  Based on a
    patch by Swati Thacker.  Part of ticket 32277.
---
 doc/tor.1.txt | 79 +++++++++++++++++++++++++++++++----------------------------
 1 file changed, 42 insertions(+), 37 deletions(-)

diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index fd09e30d6..b9738cdb6 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -68,13 +68,13 @@ The following options in this section are only recognized on the
 
 [[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
+    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.
+    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__::
     Specify a file in which to find default values for Tor options.  The
@@ -83,18 +83,18 @@ The following options in this section are only recognized on the
     @CONFDIR@/torrc-defaults.)
 
 [[opt-ignore-missing-torrc]] **--ignore-missing-torrc**::
-    Specifies that Tor should treat a missing torrc file as though it
+    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.
+    Generate a hashed password for control port access.
 
 [[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.
+    Verify whether the configuration file is valid.
 
 [[opt-serviceinstall]] **--service install** [**--options** __command-line options__]::
     Install an instance of Tor as a Windows service, with the provided
@@ -115,8 +115,8 @@ The following options in this section are only recognized on the
     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.)
+    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**::
     Display Tor version and exit. The output is a single line of the format
@@ -124,41 +124,46 @@ The following options in this section are only recognized on the
     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.
+    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: 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.
+    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.
++
+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
+    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