Improve help text and documentation of command line options

Removed the “=” in “-a, --a-long-option=VALUE” to make it easier to
understand that “-a=VALUE” isn’t supported. Also improved some of the
placeholder names.

Closes #529.

diff --git a/doc/MANUAL.adoc b/doc/MANUAL.adoc
index 20f21ee032cb0fe620e035aed89310a5f74d986a..cb66609ad4c60b7c04f6f678ba36709e95ae4201 100644 (file)
--- a/doc/MANUAL.adoc
+++ b/doc/MANUAL.adoc
@@ -75,7 +75,7 @@ These options only apply when you invoke ccache as ``ccache''. When invoked as
 a compiler (via a symlink as described in the previous section), the normal
 compiler options apply and you should refer to the compiler's documentation.
 
-*`-c, --cleanup`*::
+*`-c`*, *`--cleanup`*::
 
     Clean up the cache by removing old cached files until the specified file
     number and cache size limits are not exceeded. This also recalculates the
@@ -85,37 +85,37 @@ compiler options apply and you should refer to the compiler's documentation.
     cleanup is mostly useful if you manually modify the cache contents or
     believe that the cache size statistics may be inaccurate.
 
-*`-C, --clear`*::
+*`-C`*, *`--clear`*::
 
     Clear the entire cache, removing all cached files, but keeping the
     configuration file.
 
-*`--dump-manifest`*=_PATH_::
+*`--dump-manifest`* _PATH_::
 
-    Dump manifest file at PATH in text format. This is only useful when
+    Dump manifest file at _PATH_ in text format. This is only useful when
     debugging ccache and its behavior.
 
-*`-k, --get-config`*=_KEY_::
+*`-k`* _KEY_, *`--get-config`* _KEY_::
 
     Print the value of configuration option _KEY_. See
     <<_configuration,CONFIGURATION>> for more information.
 
-*`--hash-file`*=_PATH_::
+*`--hash-file`* _PATH_::
 
-    Print the hash (160 bit BLAKE2b) of the file at PATH. This is only useful
+    Print the hash (160 bit BLAKE2b) of the file at _PATH_. This is only useful
     when debugging ccache and its behavior.
 
-*`-h, --help`*::
+*`-h`*, *`--help`*::
 
     Print an options summary page.
 
-*`-F, --max-files`*=_N_::
+*`-F`* _NUM_, *`--max-files`* _NUM_::
 
-    Set the maximum number of files allowed in the cache. Use 0 for no limit.
-    The value is stored in a configuration file in the cache directory and
-    applies to all future compilations.
+    Set the maximum number of files allowed in the cache to _NUM_. Use 0 for no
+    limit. The value is stored in a configuration file in the cache directory
+    and applies to all future compilations.
 
-*`-M, --max-size`*=_SIZE_::
+*`-M`* _SIZE_, *`--max-size`* _SIZE_::
 
     Set the maximum size of the files stored in the cache. _SIZE_ should be a
     number followed by an optional suffix: k, M, G, T (decimal), Ki, Mi, Gi or
@@ -128,24 +128,24 @@ compiler options apply and you should refer to the compiler's documentation.
     Print statistics counter IDs and corresponding values machine-parsable
     (tab-separated) format.
 
-*`-o, --set-config`*=_KEY=VALUE_::
+*`-o`* _KEY=VALUE_, *`--set-config`* _KEY_=_VALUE_::
 
     Set configuration option _KEY_ to _VALUE_. See
     <<_configuration,CONFIGURATION>> for more information.
 
-*`-p, --show-config`*::
+*`-p`*, *`--show-config`*::
 
     Print current configuration options and from where they originate
     (environment variable, configuration file or compile-time default) in
     human-readable format.
 
-*`-x, --show-compression`*::
+*`-x`*, *`--show-compression`*::
 
     Print cache compression statistics. See <<_cache_compression,CACHE
     COMPRESSION>> for more information. This can potentionally take a long time
     since all files in the cache need to be visited.
 
-*`-X, --recompress`*=_LEVEL_::
+*`-X`* _LEVEL_, *`--recompress`* _LEVEL_::
 
     Recompress the cache using compression level _LEVEL_. The level can be an
     integer, with the same semantics as the
@@ -156,16 +156,16 @@ compiler options apply and you should refer to the compiler's documentation.
     visited. Only files that are currently compressed with a different level
     than _LEVEL_ will be recompressed.
 
-*`-s, --show-stats`*::
+*`-s`*, *`--show-stats`*::
 
     Print a summary of configuration and statistics counters in human-readable
     format.
 
-*`-V, --version`*::
+*`-V`*, *`--version`*::
 
     Print version and copyright information.
 
-*`-z, --zero-stats`*::
+*`-z`*, *`--zero-stats`*::
 
     Zero the cache statistics (but not the configuration options).
 

diff --git a/src/ccache.cpp b/src/ccache.cpp
index 7a1f22712c1a9424de6c0f72ed87ce44b187f3eb..f3312766b3e751471cf386da2f1cd3639e3abdf8 100644 (file)
--- a/src/ccache.cpp
+++ b/src/ccache.cpp
@@ -86,19 +86,20 @@ static const char USAGE_TEXT[] =
   "counters\n"
   "                              (normally not needed as this is done\n"
   "                              automatically)\n"
-  "    -C, --clear               clear the cache completely (except "
-  "configuration)\n"
-  "    -F, --max-files=N         set maximum number of files in cache to N "
-  "(use 0\n"
+  "    -C, --clear               clear the cache completely (except"
+  " configuration)\n"
+  "    -F, --max-files NUM       set maximum number of files in cache to NUM"
+  " (use 0\n"
   "                              for no limit)\n"
-  "    -M, --max-size=SIZE       set maximum size of cache to SIZE (use 0 "
+  "    -M, --max-size SIZE       set maximum size of cache to SIZE (use 0 "
   "for no\n"
   "                              limit); available suffixes: k, M, G, T "
   "(decimal)\n"
   "                              and Ki, Mi, Gi, Ti (binary); default "
   "suffix: G\n"
-  "    -X, --recompress LEVEL    recompress the cache (integer level or"
-  " \"uncompressed\")\n"
+  "    -X, --recompress LEVEL    recompress the cache to LEVEL (integer level"
+  " or\n"
+  "                              \"uncompressed\")\n"
   "    -x, --show-compression    show compression statistics\n"
   "    -p, --show-config         show current configuration options in\n"
   "                              human-readable format\n"
@@ -111,15 +112,15 @@ static const char USAGE_TEXT[] =
   "    -V, --version             print version and copyright information\n"
   "\n"
   "Options for scripting or debugging:\n"
-  "        --dump-manifest=PATH  dump manifest file at PATH in text format\n"
-  "    -k, --get-config=K        print the value of configuration key K\n"
-  "        --hash-file=PATH      print the hash (160 bit BLAKE2b) of the "
+  "        --dump-manifest PATH  dump manifest file at PATH in text format\n"
+  "    -k, --get-config KEY      print the value of configuration key KEY\n"
+  "        --hash-file PATH      print the hash (160 bit BLAKE2b) of the "
   "file at\n"
   "                              PATH\n"
   "        --print-stats         print statistics counter IDs and "
   "corresponding\n"
   "                              values in machine-parsable format\n"
-  "    -o, --set-config=K=V      set configuration item K to value V\n"
+  "    -o, --set-config=KEY=VAL  set configuration item KEY to value VAL\n"
   "\n"
   "See also <https://ccache.dev>.\n";