bob-[dev, build] manpage: improve command syntax descriptions (#653)

Unify the description of the option syntax. Add the long option where
one is available.

Author: jkloetzke

doc/manpages/bob-build-dev.rst

@@ -170,6 +170,9 @@ Options
     forced=<layer regex>
       like 'yes' above, but fail if any download fails
 
+``-h, --help``
+    Show this help message and exit.
+
 ``--incremental``
     Reuse build directory for incremental builds.
 
@@ -302,7 +305,7 @@ Options
     will skip the execution of it if this is not the case. With this option Bob
     not use that optimization and will execute all build steps.
 
-``-j, --jobs``
+``-j, --jobs [JOBS]``
     Specifies the number of jobs to run simultaneously.
 
     Any checkout/build/package step that needs to be executed are counted as a

doc/manpages/bob-build.rst

@@ -15,11 +15,12 @@ Synopsis
 
 ::
 
-    bob build [-h] [--destination DEST] [-j [JOBS]] [-k] [-f] [-n] [-p]
-              [--without-provided] [-A | --audit] [-b | -B | --normal]
+    bob build [-h, --help] [--destination DEST] [-j, --jobs [JOBS]] [-k, --keep-going] [-f, --force]
+              [-n, --no-deps] [-p, --with-provided] [--without-provided] [-A | --no-audit]
+              [-b, --build-only | -B, --checkout-only | --normal]
               [--clean | --incremental] [--always-checkout RE] [--resume]
-              [-q] [-v] [--no-logfiles] [-D DEFINES] [-c CONFIGFILE]
-              [-lc LAYERCONFIG] [-e NAME] [-E] [-M META] [--upload]
+              [-q, --quiet] [-v, --verbose] [--no-logfiles] [-D VAR=VALUE] [-c CONFIGFILE]
+              [-lc LAYERCONFIG] [-e NAME] [-E] [-M VAR=VALUE] [--upload]
               [--link-deps] [--no-link-deps] [--download MODE]
               [--download-layer MODE] [--shared | --no-shared]
               [--install | --no-install]

doc/manpages/bob-dev.rst

@@ -15,11 +15,12 @@ Synopsis
 
 ::
 
-    bob dev [-h] [--destination DEST] [-j [JOBS]] [-k] [-f] [-n] [-p]
-            [--without-provided] [-A | --audit] [-b | -B | --normal]
+    bob dev [-h, --help] [--destination DEST] [-j, --jobs [JOBS]] [-k, --keep-going] [-f, --force]
+            [-n, --no-deps] [-p, --with-provided] [--without-provided] [-A | --no-audit]
+            [-b, --build-only | -B, --checkout-only | --normal]
             [--clean | --incremental] [--always-checkout RE] [--resume]
-            [-q] [-v] [--no-logfiles] [-D DEFINES] [-c CONFIGFILE]
-            [-lc LAYERCONFIG] [-e NAME] [-E] [-M META] [--upload]
+            [-q, --quiet] [-v, --verbose] [--no-logfiles] [-D VAR=VALUE] [-c CONFIGFILE]
+            [-lc LAYERCONFIG] [-e NAME] [-E] [-M VAR=VALUE] [--upload]
             [--link-deps] [--no-link-deps] [--download MODE]
             [--download-layer MODE] [--shared | --no-shared]
             [--install | --no-install]

pym/bob/cmds/build/build.py

@@ -169,8 +169,8 @@ def _downloadLayerArgument(arg):
         help="Increase verbosity (may be specified multiple times)")
     parser.add_argument('--no-logfiles', default=None, action='store_true',
         help="Disable logFile generation.")
-    parser.add_argument('-D', default=[], action='append', dest="defines",
-        help="Override default environment variable")
+    parser.add_argument('-D', metavar="VAR=VALUE", default=[], action='append', dest="defines",
+        help="Override default or set environment variable <VAR> with value <VALUE>")
     parser.add_argument('-c', dest="configFile", default=[], action='append',
         help="Use config File")
     parser.add_argument('-lc', dest="layerConfig", default=[], action='append',
@@ -179,8 +179,8 @@ def _downloadLayerArgument(arg):
         help="Preserve environment variable")
     parser.add_argument('-E', dest="preserve_env", default=False, action='store_true',
         help="Preserve whole environment")
-    parser.add_argument('-M', default=[], action='append', dest="meta",
-        help="Add meta key to audit trail")
+    parser.add_argument('-M', metavar="VAR=VALUE", default=[], action='append', dest="meta",
+        help="Add meta variable <VAR> to audit trail")
     parser.add_argument('--upload', default=None, action='store_true',
         help="Upload to binary archive")
     parser.add_argument('--link-deps', default=None, help="Add linked dependencies to workspace paths",