man: Updated man pages for new `--max-jobs` CLI argumenttristan/bst-1/config-max-jobs

17 files changed, 101 insertions, 112 deletions

diff --git a/man/bst-build.1 b/man/bst-build.1
index 81a866494..8c465fccd 100644
--- a/man/bst-build.1
+++ b/man/bst-build.1
@@ -1,4 +1,4 @@
-.TH "BST BUILD" "1" "06-Aug-2018" "" "bst build Manual"
+.TH "BST BUILD" "1" "14-Jul-2019" "" "bst build Manual"
 .SH NAME
 bst\-build \- Build elements in a pipeline
 .SH SYNOPSIS
@@ -24,4 +24,4 @@ Except certain dependencies from tracking
 Allow tracking to cross junction boundaries
 .TP
 \fB\-\-track\-save\fP
-Deprecated: This is ignored
\ No newline at end of file
+Deprecated: This is ignored
diff --git a/man/bst-checkout.1 b/man/bst-checkout.1
index aa3ff5913..e1c2d0374 100644
--- a/man/bst-checkout.1
+++ b/man/bst-checkout.1
@@ -1,4 +1,4 @@
-.TH "BST CHECKOUT" "1" "06-Aug-2018" "" "bst checkout Manual"
+.TH "BST CHECKOUT" "1" "14-Jul-2019" "" "bst checkout Manual"
 .SH NAME
 bst\-checkout \- Checkout a built artifact
 .SH SYNOPSIS
@@ -22,4 +22,4 @@ Whether to run integration commands
 Checkout hardlinks instead of copies (handle with care)
 .TP
 \fB\-\-tar\fP
-Create a tarball from the artifact contents instead of a file tree. If LOCATION is '-', the tarball will be dumped to the standard output.
\ No newline at end of file
+Create a tarball from the artifact contents instead of a file tree. If LOCATION is '-', the tarball will be dumped to the standard output.
diff --git a/man/bst-fetch.1 b/man/bst-fetch.1
index 97ee37741..c6169f56b 100644
--- a/man/bst-fetch.1
+++ b/man/bst-fetch.1
@@ -1,4 +1,4 @@
-.TH "BST FETCH" "1" "06-Aug-2018" "" "bst fetch Manual"
+.TH "BST FETCH" "1" "14-Jul-2019" "" "bst fetch Manual"
 .SH NAME
 bst\-fetch \- Fetch sources in a pipeline
 .SH SYNOPSIS
@@ -6,14 +6,14 @@ bst\-fetch \- Fetch sources in a pipeline
 [OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
 Fetch sources required to build the pipeline
-
+.PP
 By default this will only try to fetch sources which are
 required for the build plan of the specified target element,
 omitting sources for any elements which are already built
 and available in the artifact cache.
-
+.PP
 Specify `--deps` to control which sources to fetch:
-
+.PP
 
     none:  No dependencies, just the element itself
     plan:  Only dependencies required for the build plan
@@ -30,4 +30,4 @@ The dependencies to fetch (default: plan)
 Track new source references before fetching
 .TP
 \fB\-J,\fP \-\-track\-cross\-junctions
-Allow tracking to cross junction boundaries
\ No newline at end of file
+Allow tracking to cross junction boundaries
diff --git a/man/bst-help.1 b/man/bst-help.1
index 655e5b438..df6caf815 100644
--- a/man/bst-help.1
+++ b/man/bst-help.1
@@ -1,4 +1,4 @@
-.TH "BST HELP" "1" "06-Aug-2018" "" "bst help Manual"
+.TH "BST HELP" "1" "14-Jul-2019" "" "bst help Manual"
 .SH NAME
 bst\-help \- Print usage information
 .SH SYNOPSIS
@@ -6,4 +6,4 @@ bst\-help \- Print usage information
 [OPTIONS] COMMAND
 .SH DESCRIPTION
 Print usage information about a given command
-    
\ No newline at end of file
+    
diff --git a/man/bst-init.1 b/man/bst-init.1
index 73dbed15d..91d942d7b 100644
--- a/man/bst-init.1
+++ b/man/bst-init.1
@@ -1,4 +1,4 @@
-.TH "BST INIT" "1" "06-Aug-2018" "" "bst init Manual"
+.TH "BST INIT" "1" "14-Jul-2019" "" "bst init Manual"
 .SH NAME
 bst\-init \- Initialize a new BuildStream project
 .SH SYNOPSIS
@@ -6,10 +6,10 @@ bst\-init \- Initialize a new BuildStream project
 [OPTIONS]
 .SH DESCRIPTION
 Initialize a new BuildStream project
-
+.PP
 Creates a new BuildStream project.conf in the project
 directory.
-
+.PP
 Unless `--project-name` is specified, this will be an
 interactive session.
 .SH OPTIONS
@@ -24,4 +24,4 @@ The required format version (default: 12)
 The subdirectory to store elements in (default: elements)
 .TP
 \fB\-f,\fP \-\-force
-Allow overwriting an existing project.conf
\ No newline at end of file
+Allow overwriting an existing project.conf
diff --git a/man/bst-pull.1 b/man/bst-pull.1
index e3adda1b9..8be9ec446 100644
--- a/man/bst-pull.1
+++ b/man/bst-pull.1
@@ -1,4 +1,4 @@
-.TH "BST PULL" "1" "06-Aug-2018" "" "bst pull Manual"
+.TH "BST PULL" "1" "14-Jul-2019" "" "bst pull Manual"
 .SH NAME
 bst\-pull \- Pull a built artifact
 .SH SYNOPSIS
@@ -6,13 +6,13 @@ bst\-pull \- Pull a built artifact
 [OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
 Pull a built artifact from the configured remote artifact cache.
-
+.PP
 By default the artifact will be pulled one of the configured caches
 if possible, following the usual priority order. If the `--remote` flag
 is given, only the specified cache will be queried.
-
+.PP
 Specify `--deps` to control which artifacts to pull:
-
+.PP
 
     none:  No dependencies, just the element itself
     all:   All dependencies
@@ -22,4 +22,4 @@ Specify `--deps` to control which artifacts to pull:
 The dependency artifacts to pull (default: none)
 .TP
 \fB\-r,\fP \-\-remote TEXT
-The URL of the remote cache (defaults to the first configured cache)
\ No newline at end of file
+The URL of the remote cache (defaults to the first configured cache)
diff --git a/man/bst-push.1 b/man/bst-push.1
index 9721a8781..88cf5915f 100644
--- a/man/bst-push.1
+++ b/man/bst-push.1
@@ -1,4 +1,4 @@
-.TH "BST PUSH" "1" "06-Aug-2018" "" "bst push Manual"
+.TH "BST PUSH" "1" "14-Jul-2019" "" "bst push Manual"
 .SH NAME
 bst\-push \- Push a built artifact
 .SH SYNOPSIS
@@ -6,12 +6,12 @@ bst\-push \- Push a built artifact
 [OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
 Push a built artifact to a remote artifact cache.
-
+.PP
 The default destination is the highest priority configured cache. You can
 override this by passing a different cache URL with the `--remote` flag.
-
+.PP
 Specify `--deps` to control which artifacts to push:
-
+.PP
 
     none:  No dependencies, just the element itself
     all:   All dependencies
@@ -21,4 +21,4 @@ Specify `--deps` to control which artifacts to push:
 The dependencies to push (default: none)
 .TP
 \fB\-r,\fP \-\-remote TEXT
-The URL of the remote cache (defaults to the first configured cache)
\ No newline at end of file
+The URL of the remote cache (defaults to the first configured cache)
diff --git a/man/bst-shell.1 b/man/bst-shell.1
index 09e5b6da8..7f0c5fc5d 100644
--- a/man/bst-shell.1
+++ b/man/bst-shell.1
@@ -1,4 +1,4 @@
-.TH "BST SHELL" "1" "06-Aug-2018" "" "bst shell Manual"
+.TH "BST SHELL" "1" "14-Jul-2019" "" "bst shell Manual"
 .SH NAME
 bst\-shell \- Shell into an element's sandbox environment
 .SH SYNOPSIS
@@ -6,18 +6,18 @@ bst\-shell \- Shell into an element's sandbox environment
 [OPTIONS] ELEMENT [COMMAND]...
 .SH DESCRIPTION
 Run a command in the target element's sandbox environment
-
+.PP
 This will stage a temporary sysroot for running the target
 element, assuming it has already been built and all required
 artifacts are in the local cache.
-
+.PP
 Use the --build option to create a temporary sysroot for
 building the element instead.
-
+.PP
 Use the --sysroot option with an existing failed build
 directory or with a checkout of the given target, in order
 to use a specific sysroot.
-
+.PP
 If no COMMAND is specified, the default is to attempt
 to run an interactive shell.
 .SH OPTIONS
@@ -32,4 +32,4 @@ An existing sysroot
 Mount a file or directory into the sandbox
 .TP
 \fB\-\-isolate\fP
-Create an isolated build sandbox
\ No newline at end of file
+Create an isolated build sandbox
diff --git a/man/bst-show.1 b/man/bst-show.1
index 4495bf21d..36d18e097 100644
--- a/man/bst-show.1
+++ b/man/bst-show.1
@@ -1,4 +1,4 @@
-.TH "BST SHOW" "1" "06-Aug-2018" "" "bst show Manual"
+.TH "BST SHOW" "1" "14-Jul-2019" "" "bst show Manual"
 .SH NAME
 bst\-show \- Show elements in the pipeline
 .SH SYNOPSIS
@@ -6,25 +6,25 @@ bst\-show \- Show elements in the pipeline
 [OPTIONS] [ELEMENTS]...
 .SH DESCRIPTION
 Show elements in the pipeline
-
+.PP
 By default this will show all of the dependencies of the
 specified target element.
-
+.PP
 Specify `--deps` to control which elements to show:
-
+.PP
 
     none:  No dependencies, just the element itself
     plan:  Dependencies required for a build plan
     run:   Runtime dependencies, including the element itself
     build: Build time dependencies, excluding the element itself
     all:   All dependencies
-
+.PP
 
 FORMAT
 ~~~~~~
 The --format option controls what should be printed for each element,
 the following symbols can be used in the format string:
-
+.PP
 
     %{name}           The element name
     %{key}            The abbreviated cache key (if all sources are consistent)
@@ -36,17 +36,17 @@ the following symbols can be used in the format string:
     %{public}         Public domain data
     %{workspaced}     If the element is workspaced
     %{workspace-dirs} A list of workspace directories
-
+.PP
 The value of the %{symbol} without the leading '%' character is understood
 as a pythonic formatting string, so python formatting features apply,
 examle:
-
+.PP
 
     bst show target.bst --format \
         'Name: %{name: ^20} Key: %{key: ^8} State: %{state}'
-
+.PP
 If you want to use a newline in a format string in bash, use the '$' modifier:
-
+.PP
 
     bst show target.bst --format \
         $'---------- %{name} ----------\n%{vars}'
@@ -62,4 +62,4 @@ The dependencies to show (default: all)
 Staging or alphabetic ordering of dependencies
 .TP
 \fB\-f,\fP \-\-format FORMAT
-Format string for each element
\ No newline at end of file
+Format string for each element
diff --git a/man/bst-source-bundle.1 b/man/bst-source-bundle.1
index ce94dde7e..6540630ab 100644
--- a/man/bst-source-bundle.1
+++ b/man/bst-source-bundle.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE-BUNDLE" "1" "06-Aug-2018" "" "bst source-bundle Manual"
+.TH "BST SOURCE-BUNDLE" "1" "14-Jul-2019" "" "bst source-bundle Manual"
 .SH NAME
 bst\-source-bundle \- Produce a build bundle to be manually executed
 .SH SYNOPSIS
@@ -22,4 +22,4 @@ Track new source references before bundling
 Overwrite an existing tarball
 .TP
 \fB\-\-directory\fP TEXT
-The directory to write the tarball to
\ No newline at end of file
+The directory to write the tarball to
diff --git a/man/bst-track.1 b/man/bst-track.1
index 98fa311b0..5a1319942 100644
--- a/man/bst-track.1
+++ b/man/bst-track.1
@@ -1,4 +1,4 @@
-.TH "BST TRACK" "1" "06-Aug-2018" "" "bst track Manual"
+.TH "BST TRACK" "1" "14-Jul-2019" "" "bst track Manual"
 .SH NAME
 bst\-track \- Track new source references
 .SH SYNOPSIS
@@ -7,12 +7,12 @@ bst\-track \- Track new source references
 .SH DESCRIPTION
 Consults the specified tracking branches for new versions available
 to build and updates the project with any newly available references.
-
+.PP
 By default this will track just the specified element, but you can also
 update a whole tree of dependencies in one go.
-
+.PP
 Specify `--deps` to control which sources to track:
-
+.PP
 
     none:  No dependencies, just the specified elements
     all:   All dependencies of all specified elements
@@ -25,4 +25,4 @@ Except certain dependencies from tracking
 The dependencies to track (default: none)
 .TP
 \fB\-J,\fP \-\-cross\-junctions
-Allow crossing junction boundaries
\ No newline at end of file
+Allow crossing junction boundaries
diff --git a/man/bst-workspace-close.1 b/man/bst-workspace-close.1
index 4abaad358..0bcf74bf7 100644
--- a/man/bst-workspace-close.1
+++ b/man/bst-workspace-close.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE CLOSE" "1" "06-Aug-2018" "" "bst workspace close Manual"
+.TH "BST WORKSPACE CLOSE" "1" "14-Jul-2019" "" "bst workspace close Manual"
 .SH NAME
 bst\-workspace\-close \- Close workspaces
 .SH SYNOPSIS
@@ -12,4 +12,4 @@ Close a workspace
 Remove the path that contains the closed workspace
 .TP
 \fB\-a,\fP \-\-all
-Close all open workspaces
\ No newline at end of file
+Close all open workspaces
diff --git a/man/bst-workspace-list.1 b/man/bst-workspace-list.1
index e2e67c4eb..199ff3461 100644
--- a/man/bst-workspace-list.1
+++ b/man/bst-workspace-list.1
@@ -1,8 +1,8 @@
-.TH "BST WORKSPACE LIST" "1" "06-Aug-2018" "" "bst workspace list Manual"
+.TH "BST WORKSPACE LIST" "1" "14-Jul-2019" "" "bst workspace list Manual"
 .SH NAME
 bst\-workspace\-list \- List open workspaces
 .SH SYNOPSIS
 .B bst workspace list
 [OPTIONS]
 .SH DESCRIPTION
-List open workspaces
\ No newline at end of file
+List open workspaces
diff --git a/man/bst-workspace-open.1 b/man/bst-workspace-open.1
index a0fae85b7..176223655 100644
--- a/man/bst-workspace-open.1
+++ b/man/bst-workspace-open.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE OPEN" "1" "06-Aug-2018" "" "bst workspace open Manual"
+.TH "BST WORKSPACE OPEN" "1" "14-Jul-2019" "" "bst workspace open Manual"
 .SH NAME
 bst\-workspace\-open \- Open a new workspace
 .SH SYNOPSIS
@@ -15,4 +15,4 @@ Do not checkout the source, only link to the given directory
 Overwrite files existing in checkout directory
 .TP
 \fB\-\-track\fP
-Track and fetch new source references before checking out the workspace
\ No newline at end of file
+Track and fetch new source references before checking out the workspace
diff --git a/man/bst-workspace-reset.1 b/man/bst-workspace-reset.1
index 29689a9c6..255840434 100644
--- a/man/bst-workspace-reset.1
+++ b/man/bst-workspace-reset.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE RESET" "1" "06-Aug-2018" "" "bst workspace reset Manual"
+.TH "BST WORKSPACE RESET" "1" "14-Jul-2019" "" "bst workspace reset Manual"
 .SH NAME
 bst\-workspace\-reset \- Reset a workspace to its original state
 .SH SYNOPSIS
@@ -15,4 +15,4 @@ Reset workspace state without affecting its contents
 Track and fetch the latest source before resetting
 .TP
 \fB\-a,\fP \-\-all
-Reset all open workspaces
\ No newline at end of file
+Reset all open workspaces
diff --git a/man/bst-workspace.1 b/man/bst-workspace.1
index b249ed4d5..aab453ccc 100644
--- a/man/bst-workspace.1
+++ b/man/bst-workspace.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE" "1" "06-Aug-2018" "" "bst workspace Manual"
+.TH "BST WORKSPACE" "1" "14-Jul-2019" "" "bst workspace Manual"
 .SH NAME
 bst\-workspace \- Manipulate developer workspaces
 .SH SYNOPSIS
@@ -8,21 +8,18 @@ bst\-workspace \- Manipulate developer workspaces
 Manipulate developer workspaces
 .SH COMMANDS
 .PP
-\fBreset\fP
-  Reset a workspace to its original state
-  See \fBbst workspace-reset(1)\fP for full documentation on the \fBreset\fP command.
-
+\fBopen\fP
+  Open a new workspace
+  See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command.
 .PP
 \fBclose\fP
   Close workspaces
   See \fBbst workspace-close(1)\fP for full documentation on the \fBclose\fP command.
-
+.PP
+\fBreset\fP
+  Reset a workspace to its original state
+  See \fBbst workspace-reset(1)\fP for full documentation on the \fBreset\fP command.
 .PP
 \fBlist\fP
   List open workspaces
   See \fBbst workspace-list(1)\fP for full documentation on the \fBlist\fP command.
-
-.PP
-\fBopen\fP
-  Open a new workspace
-  See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command.
diff --git a/man/bst.1 b/man/bst.1
index dfe1a7d2c..1b5dee207 100644
--- a/man/bst.1
+++ b/man/bst.1
@@ -1,4 +1,4 @@
-.TH "BST" "1" "06-Aug-2018" "" "bst Manual"
+.TH "BST" "1" "14-Jul-2019" "" "bst Manual"
 .SH NAME
 bst \- Build and manipulate BuildStream projects...
 .SH SYNOPSIS
@@ -6,15 +6,15 @@ bst \- Build and manipulate BuildStream projects...
 [OPTIONS] COMMAND [ARGS]...
 .SH DESCRIPTION
 Build and manipulate BuildStream projects
-
+.PP
 Most of the main options override options in the
 user preferences configuration file.
 .SH OPTIONS
 .TP
 \fB\-\-version\fP
-
+.PP
 .TP
-\fB\-c,\fP \-\-config PATH
+\fB\-c,\fP \-\-config FILE
 Configuration file to use
 .TP
 \fB\-C,\fP \-\-directory DIRECTORY
@@ -32,6 +32,9 @@ Maximum simultaneous build tasks
 \fB\-\-pushers\fP INTEGER
 Maximum simultaneous upload tasks
 .TP
+\fB\-\-max\-jobs\fP INTEGER
+Number of parallel jobs allowed for a given build task
+.TP
 \fB\-\-network\-retries\fP INTEGER
 Maximum retries for network tasks
 .TP
@@ -66,61 +69,50 @@ Specify a project option
 The mirror to fetch from first, before attempting other mirrors
 .SH COMMANDS
 .PP
-\fBshow\fP
-  Show elements in the pipeline
-  See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command.
-
+\fBhelp\fP
+  Print usage information
+  See \fBbst-help(1)\fP for full documentation on the \fBhelp\fP command.
 .PP
-\fBpush\fP
-  Push a built artifact
-  See \fBbst-push(1)\fP for full documentation on the \fBpush\fP command.
-
+\fBinit\fP
+  Initialize a new BuildStream project
+  See \fBbst-init(1)\fP for full documentation on the \fBinit\fP command.
 .PP
-\fBcheckout\fP
-  Checkout a built artifact
-  See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
-
+\fBbuild\fP
+  Build elements in a pipeline
+  See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
 .PP
 \fBfetch\fP
   Fetch sources in a pipeline
   See \fBbst-fetch(1)\fP for full documentation on the \fBfetch\fP command.
-
-.PP
-\fBworkspace\fP
-  Manipulate developer workspaces
-  See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command.
-
-.PP
-\fBbuild\fP
-  Build elements in a pipeline
-  See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
-
 .PP
 \fBtrack\fP
   Track new source references
   See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
-
 .PP
-\fBsource-bundle\fP
-  Produce a build bundle to be manually executed
-  See \fBbst-source-bundle(1)\fP for full documentation on the \fBsource-bundle\fP command.
-
+\fBpull\fP
+  Pull a built artifact
+  See \fBbst-pull(1)\fP for full documentation on the \fBpull\fP command.
 .PP
-\fBinit\fP
-  Initialize a new BuildStream project
-  See \fBbst-init(1)\fP for full documentation on the \fBinit\fP command.
-
+\fBpush\fP
+  Push a built artifact
+  See \fBbst-push(1)\fP for full documentation on the \fBpush\fP command.
+.PP
+\fBshow\fP
+  Show elements in the pipeline
+  See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command.
 .PP
 \fBshell\fP
   Shell into an element's sandbox environment
   See \fBbst-shell(1)\fP for full documentation on the \fBshell\fP command.
-
 .PP
-\fBpull\fP
-  Pull a built artifact
-  See \fBbst-pull(1)\fP for full documentation on the \fBpull\fP command.
-
+\fBcheckout\fP
+  Checkout a built artifact
+  See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
 .PP
-\fBhelp\fP
-  Print usage information
-  See \fBbst-help(1)\fP for full documentation on the \fBhelp\fP command.
+\fBworkspace\fP
+  Manipulate developer workspaces
+  See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command.
+.PP
+\fBsource-bundle\fP
+  Produce a build bundle to be manually executed
+  See \fBbst-source-bundle(1)\fP for full documentation on the \fBsource-bundle\fP command.