Reword FILES section of tor.1.txt

Reword the FILES section of tor.1.txt.  Based on a patch by Swati
Thacker.

Part of #32176.

1 files changed, 89 insertions, 92 deletions

diff --git a/doc/tor.1.txt b/doc/tor.1.txt
index 750c7fbe01..97900dc3ff 100644
--- a/doc/tor.1.txt
+++ b/doc/tor.1.txt
@@ -3392,7 +3392,7 @@ FILES
 -----
 
 **@CONFDIR@/torrc**::
-    The configuration file, which contains "option value" pairs.
+    Default location of the configuration file.
 
 **$HOME/.torrc**::
     Fallback location for torrc, if @CONFDIR@/torrc is not found.
@@ -3402,164 +3402,160 @@ FILES
 
 
 __CacheDirectory__**/cached-certs**::
-    This file holds downloaded directory key certificates that are used to
-    verify authenticity of documents generated by Tor directory authorities.
+    Contains downloaded directory key certificates that are used to verify
+    authenticity of documents generated by the Tor directory authorities.
 
 __CacheDirectory__**/cached-consensus** and/or **cached-microdesc-consensus**::
     The most recent consensus network status document we've downloaded.
 
 __CacheDirectory__**/cached-descriptors** and **cached-descriptors.new**::
-    These files hold downloaded router statuses. Some routers may appear more
-    than once; if so, the most recently published descriptor is used. Lines
-    beginning with @-signs are annotations that contain more information about
-    a given router. The ".new" file is an append-only journal; when it gets
-    too large, all entries are merged into a new cached-descriptors file.
+    These files contain the downloaded router statuses. Some routers may appear
+    more than once; if so, the most recently published descriptor is
+    used. Lines beginning with **`@`**-signs are annotations that contain more
+    information about a given router. The **`.new`** file is an append-only
+    journal; when it gets too large, all entries are merged into a new
+    cached-descriptors file.
 
 __CacheDirectory__**/cached-extrainfo** and **cached-extrainfo.new**::
-   As "cached-descriptors", but holds optionally-downloaded "extra-info"
-   documents. Relays use these documents to send inessential information
-   about statistics, bandwidth history, and network health to the
-   authorities. They aren't fetched by default; see the DownloadExtraInfo
-   option for more info.
+    Similar to **cached-descriptors**, but holds optionally-downloaded
+    "extra-info" documents. Relays use these documents to send inessential
+    information about statistics, bandwidth history, and network health to the
+    authorities. They aren't fetched by default. See the DownloadExtraInfo
+    option for more information.
 
 __CacheDirectory__**/cached-microdescs** and **cached-microdescs.new**::
     These files hold downloaded microdescriptors.  Lines beginning with
-    @-signs are annotations that contain more information about a given
-    router. The ".new" file is an append-only journal; when it gets too
+    **`@`**-signs are annotations that contain more information about a given
+    router. The **`.new`** file is an append-only journal; when it gets too
     large, all entries are merged into a new cached-microdescs file.
 
 __DataDirectory__**/state**::
-    A set of persistent key-value mappings. These are documented in
-    the file. These include:
-            - The current entry guards and their status.
-            - The current bandwidth accounting values.
-            - When the file was last written
-            - What version of Tor generated the state file
-            - A short history of bandwidth usage, as produced in the server
-            descriptors.
+    Contains a set of persistent key-value mappings. These include:
+        - the current entry guards and their status.
+        - the current bandwidth accounting values.
+        - when the file was last written
+        - what version of Tor generated the state file
+        - a short history of bandwidth usage, as produced in the server
+          descriptors.
 
 __DataDirectory__**/sr-state**::
-    Authority only. State file used to record information about the current
+    _Authority only_. This file is used to record information about the current
     status of the shared-random-value voting state.
 
 __CacheDirectory__**/diff-cache**::
-    Directory cache only. Holds older consensuses, and diffs from older
-    consensuses to the most recent consensus of each type, compressed
-    in various ways. Each file contains a set of key-value arguments
-    describing its contents, followed by a single NUL byte, followed by the
-    main file contents.
+    _Directory cache only_. Holds older consensuses and diffs from oldest to
+    the most recent consensus of each type compressed in various ways. Each
+    file contains a set of key-value arguments describing its contents,
+    followed by a single NUL byte, followed by the main file contents.
 
 __DataDirectory__**/bw_accounting**::
-    Used to track bandwidth accounting values (when the current period starts
-    and ends; how much has been read and written so far this period). This file
-    is obsolete, and the data is now stored in the \'state' file instead.
+    This file is obsolete and the data is now stored in the **`state`** file
+    instead. Used to track bandwidth accounting values (when the current period
+    starts and ends; how much has been read and written so far this period).
 
 __DataDirectory__**/control_auth_cookie**::
-    Used for cookie authentication with the controller. Location can be
-    overridden by the CookieAuthFile config option. Regenerated on startup. See
+    This file can be used only when cookie authentication is enabled. Used for
+    cookie authentication with the controller. Location can be overridden by
+    the `CookieAuthFile` configuration option. Regenerated on startup. See
     control-spec.txt in https://spec.torproject.org/[torspec] for details.
-    Only used when cookie authentication is enabled.
 
 __DataDirectory__**/lock**::
-    This file is used to prevent two Tor instances from using same data
-    directory. If access to this file is locked, data directory is already
-    in use by Tor.
+    This file is used to prevent two Tor instances from using the same data
+    directory. If access to this file is locked, data directory is already in
+    use by Tor.
 
 __DataDirectory__**/key-pinning-journal**::
     Used by authorities. A line-based file that records mappings between
-    RSA1024 identity keys and Ed25519 identity keys. Authorities enforce
-    these mappings, so that once a relay has picked an Ed25519 key, stealing
-    or factoring the RSA1024 key will no longer let an attacker impersonate
-    the relay.
+    RSA1024 and Ed25519 identity keys. Authorities enforce these mappings, so
+    that once a relay has picked an Ed25519 key, stealing or factoring the
+    RSA1024 key will no longer let an attacker impersonate the relay.
 
 __KeyDirectory__**/authority_identity_key**::
     A v3 directory authority's master identity key, used to authenticate its
     signing key. Tor doesn't use this while it's running. The tor-gencert
-    program uses this. If you're running an authority, you should keep this
-    key offline, and not actually put it here.
+    program uses this. If you're running an authority, you should keep this key
+    offline, and not put it in this file.
 
 __KeyDirectory__**/authority_certificate**::
-    A v3 directory authority's certificate, which authenticates the authority's
-    current vote- and consensus-signing key using its master identity key.
-    Only directory authorities use this file.
+    Only directory authorities use this file. A v3 directory authority's
+    certificate which authenticates the authority's current vote- and
+    consensus-signing key using its master identity key.
 
 __KeyDirectory__**/authority_signing_key**::
-    A v3 directory authority's signing key, used to sign votes and consensuses.
-    Only directory authorities use this file.  Corresponds to the
+    Only directory authorities use this file. A v3 directory authority's
+    signing key that is used to sign votes and consensuses. Corresponds to the
     **authority_certificate** cert.
 
 __KeyDirectory__**/legacy_certificate**::
-    As authority_certificate: used only when V3AuthUseLegacyKey is set.
-    See documentation for V3AuthUseLegacyKey.
+    As authority_certificate; used only when `V3AuthUseLegacyKey` is set.  See
+    documentation for V3AuthUseLegacyKey.
 
 __KeyDirectory__**/legacy_signing_key**::
-    As authority_signing_key: used only when V3AuthUseLegacyKey is set.
-    See documentation for V3AuthUseLegacyKey.
+    As authority_signing_key: used only when `V3AuthUseLegacyKey` is set.  See
+    documentation for V3AuthUseLegacyKey.
 
 __KeyDirectory__**/secret_id_key**::
     A relay's RSA1024 permanent identity key, including private and public
-    components.  Used to sign router descriptors, and to sign other keys.
+    components. Used to sign router descriptors, and to sign other keys.
 
 __KeyDirectory__**/ed25519_master_id_public_key**::
     The public part of a relay's Ed25519 permanent identity key.
 
 __KeyDirectory__**/ed25519_master_id_secret_key**::
-    The private part of a relay's Ed25519 permanent identity key.  This key
-    is used to sign the medium-term ed25519 signing key.  This file can be
-    kept offline, or kept encrypted. If so, Tor will not be able to generate
-    new signing keys itself; you'll need to use tor --keygen yourself to do
-    so.
+    The private part of a relay's Ed25519 permanent identity key.  This key is
+    used to sign the medium-term ed25519 signing key.  This file can be kept
+    offline or encrypted. If so, Tor will not be able to generate new signing
+    keys automatically; you'll need to use `tor --keygen` to do so.
 
 __KeyDirectory__**/ed25519_signing_secret_key**::
     The private and public components of a relay's medium-term Ed25519 signing
-    key. This key is authenticated by the Ed25519 master key, in turn
+    key. This key is authenticated by the Ed25519 master key, which in turn
     authenticates other keys (and router descriptors).
 
 __KeyDirectory__**/ed25519_signing_cert**::
-    The certificate which authenticates "ed25519_signing_secret_key" as
-    having been signed by the Ed25519 master key.
+    The certificate which authenticates "ed25519_signing_secret_key" as having
+    been signed by the Ed25519 master key.
 
 __KeyDirectory__**/secret_onion_key** and **secret_onion_key.old**::
     A relay's RSA1024 short-term onion key. Used to decrypt old-style ("TAP")
-    circuit extension requests. The ".old" file holds the previously
-    generated key, which the relay uses to handle any requests that were
-    made by clients that didn't have the new one.
+    circuit extension requests. The **`.old`** file holds the previously
+    generated key, which the relay uses to handle any requests that were made
+    by clients that didn't have the new one.
 
 __KeyDirectory__**/secret_onion_key_ntor** and **secret_onion_key_ntor.old**::
     A relay's Curve25519 short-term onion key. Used to handle modern ("ntor")
-    circuit extension requests. The ".old" file holds the previously
-    generated key, which the relay uses to handle any requests that were
-    made by clients that didn't have the new one.
+    circuit extension requests. The **`.old`** file holds the previously
+    generated key, which the relay uses to handle any requests that were made
+    by clients that didn't have the new one.
 
 __DataDirectory__**/fingerprint**::
-    Only used by servers. Holds the fingerprint of the server's identity key.
+    Only used by servers. Contains the fingerprint of the server's identity key.
 
 __DataDirectory__**/hashed-fingerprint**::
-    Only used by bridges. Holds the hashed fingerprint of the bridge's
+    Only used by bridges. Contains the hashed fingerprint of the bridge's
     identity key. (That is, the hash of the hash of the identity key.)
 
 __DataDirectory__**/approved-routers**::
-    Only used by authoritative directory servers. This file lists
-    the status of routers by their identity fingerprint.
-    Each line lists a status and a fingerprint separated by
-    whitespace. See your **fingerprint** file in the __DataDirectory__ for an
-    example line. If the status is **!reject** then descriptors from the
-    given identity (fingerprint) are rejected by this server. If it is
-    **!invalid** then descriptors are accepted but marked in the directory as
-    not valid, that is, not recommended.
+    Only used by authoritative directory servers. This file lists the status of
+    routers by their identity fingerprint.  Each line lists a status and a
+    fingerprint separated by whitespace. See your **`fingerprint`** file in the
+    __DataDirectory__ for an example line. If the status is **!reject**, then
+    the descriptors from the given identity (fingerprint) are rejected by this
+    server. If it is **!invalid**, then the descriptors are accepted but marked
+    in the directory as not valid, that is, not recommended.
 
 __DataDirectory__**/v3-status-votes**::
-    Only for v3 authoritative directory servers. This file contains
-    status votes from all the authoritative directory servers.
+    Only for v3 authoritative directory servers. This file contains status
+    votes from all the authoritative directory servers.
 
 __CacheDirectory__**/unverified-consensus**::
-    This file contains a network consensus document that has been downloaded,
-    but which we didn't have the right certificates to check yet.
+    Contains a network consensus document that has been downloaded, but which
+    we didn't have the right certificates to check yet.
 
 __CacheDirectory__**/unverified-microdesc-consensus**::
-    This file contains a microdescriptor-flavored network consensus document
-    that has been downloaded, but which we didn't have the right certificates
-    to check yet.
+    Contains a microdescriptor-flavored network consensus document that has
+    been downloaded, but which we didn't have the right certificates to check
+    yet.
 
 __DataDirectory__**/unparseable-desc**::
     Onion server descriptors that Tor was unable to parse are dumped to this
@@ -3567,7 +3563,7 @@ __DataDirectory__**/unparseable-desc**::
 
 __DataDirectory__**/router-stability**::
     Only used by authoritative directory servers. Tracks measurements for
-    router mean-time-between-failures so that authorities have a good idea of
+    router mean-time-between-failures so that authorities have a fair idea of
     how to set their Stable flags.
 
 __DataDirectory__**/stats/dirreq-stats**::
@@ -3608,17 +3604,18 @@ __HiddenServiceDirectory__**/hostname**::
     The <base32-encoded-fingerprint>.onion domain name for this hidden service.
     If the hidden service is restricted to authorized clients only, this file
     also contains authorization data for all clients.
- +
-    Note that clients will ignore any extra subdomains prepended to a hidden
-    service hostname. So if you have "xyz.onion" as your hostname, you
-    can tell clients to connect to "www.xyz.onion" or "irc.xyz.onion"
++
+[NOTE]
+    The clients will ignore any extra subdomains prepended to a hidden
+    service hostname. Supposing you have "xyz.onion" as your hostname, you
+    can ask your clients to connect to "www.xyz.onion" or "irc.xyz.onion"
     for virtual-hosting purposes.
 
 __HiddenServiceDirectory__**/private_key**::
-    The private key for this hidden service.
+    Contains the private key for this hidden service.
 
 __HiddenServiceDirectory__**/client_keys**::
-    Authorization data for a hidden service that is only accessible by
+    Contains authorization data for a hidden service that is only accessible by
     authorized clients.
 
 __HiddenServiceDirectory__**/onion_service_non_anonymous**::