Updated man pages.

Now includes man pages for workspace commands and
also the bst-artifact-receive helper program.

14 files changed, 163 insertions, 31 deletions

diff --git a/man/bst-artifact-receive.1 b/man/bst-artifact-receive.1
new file mode 100644
index 000000000..4b158d9ac
--- /dev/null
+++ b/man/bst-artifact-receive.1
@@ -0,0 +1,16 @@
+.TH "BST-ARTIFACT-RECEIVE" "1" "27-Jul-2017" "" "bst-artifact-receive Manual"
+.SH NAME
+bst-artifact-receive \- Receive pushed artifacts over ssh
+.SH SYNOPSIS
+.B bst-artifact-receive
+[OPTIONS] REPO
+.SH DESCRIPTION
+A BuildStream sister program for receiving artifacts send to a shared artifact cache
+    
+.SH OPTIONS
+.TP
+\fB\-v,\fP \-\-verbose
+Verbose mode
+.TP
+\fB\-d,\fP \-\-debug
+Debug mode
\ No newline at end of file
diff --git a/man/bst-build.1 b/man/bst-build.1
index e262754eb..36b61e7d9 100644
--- a/man/bst-build.1
+++ b/man/bst-build.1
@@ -1,4 +1,4 @@
-.TH "BST BUILD" "1" "11-Jul-2017" "" "bst build Manual"
+.TH "BST BUILD" "1" "27-Jul-2017" "" "bst build Manual"
 .SH NAME
 bst\-build \- Build elements in a pipeline
 .SH SYNOPSIS
diff --git a/man/bst-checkout.1 b/man/bst-checkout.1
index 09c69ec46..36786c6aa 100644
--- a/man/bst-checkout.1
+++ b/man/bst-checkout.1
@@ -1,4 +1,4 @@
-.TH "BST CHECKOUT" "1" "11-Jul-2017" "" "bst checkout Manual"
+.TH "BST CHECKOUT" "1" "27-Jul-2017" "" "bst checkout Manual"
 .SH NAME
 bst\-checkout \- Checkout a built artifact
 .SH SYNOPSIS
diff --git a/man/bst-fetch.1 b/man/bst-fetch.1
index 96217b316..7b9c929b4 100644
--- a/man/bst-fetch.1
+++ b/man/bst-fetch.1
@@ -1,4 +1,4 @@
-.TH "BST FETCH" "1" "11-Jul-2017" "" "bst fetch Manual"
+.TH "BST FETCH" "1" "27-Jul-2017" "" "bst fetch Manual"
 .SH NAME
 bst\-fetch \- Fetch sources in a pipeline
 .SH SYNOPSIS
diff --git a/man/bst-shell.1 b/man/bst-shell.1
index 0c5faa31f..510a4918e 100644
--- a/man/bst-shell.1
+++ b/man/bst-shell.1
@@ -1,4 +1,4 @@
-.TH "BST SHELL" "1" "11-Jul-2017" "" "bst shell Manual"
+.TH "BST SHELL" "1" "27-Jul-2017" "" "bst shell Manual"
 .SH NAME
 bst\-shell \- Shell into an element's sandbox environment
 .SH SYNOPSIS
diff --git a/man/bst-show.1 b/man/bst-show.1
index 541004ad0..eb09711bc 100644
--- a/man/bst-show.1
+++ b/man/bst-show.1
@@ -1,4 +1,4 @@
-.TH "BST SHOW" "1" "11-Jul-2017" "" "bst show Manual"
+.TH "BST SHOW" "1" "27-Jul-2017" "" "bst show Manual"
 .SH NAME
 bst\-show \- Show elements in the pipeline
 .SH SYNOPSIS
@@ -26,14 +26,17 @@ The --format option controls what should be printed for each element,
 the following symbols can be used in the format string:
 
 
-    %{name}     The element name
-    %{key}      The abbreviated cache key (if all sources are consistent)
-    %{full-key} The full cache key (if all sources are consistent)
-    %{state}    cached, buildable, waiting or inconsistent
-    %{config}   The element configuration
-    %{vars}     Variable configuration
-    %{env}      Environment settings
-    %{public}   Public domain data
+    %{name}           The element name
+    %{variant}        The selected element variant
+    %{key}            The abbreviated cache key (if all sources are consistent)
+    %{full-key}       The full cache key (if all sources are consistent)
+    %{state}          cached, buildable, waiting or inconsistent
+    %{config}         The element configuration
+    %{vars}           Variable configuration
+    %{env}            Environment settings
+    %{public}         Public domain data
+    %{workspaced}     If the element is workspaced
+    %{workspace-dirs} A list of workspace directories
 
 The value of the %{symbol} without the leading '%' character is understood
 as a pythonic formatting string, so python formatting features apply,
diff --git a/man/bst-source-bundle.1 b/man/bst-source-bundle.1
index 45eefbd7a..43abe4dd6 100644
--- a/man/bst-source-bundle.1
+++ b/man/bst-source-bundle.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE-BUNDLE" "1" "11-Jul-2017" "" "bst source-bundle Manual"
+.TH "BST SOURCE-BUNDLE" "1" "27-Jul-2017" "" "bst source-bundle Manual"
 .SH NAME
 bst\-source-bundle \- Produce a build bundle to be manually executed
 .SH SYNOPSIS
diff --git a/man/bst-track.1 b/man/bst-track.1
index d5aeecf15..b14ff3a1e 100644
--- a/man/bst-track.1
+++ b/man/bst-track.1
@@ -1,4 +1,4 @@
-.TH "BST TRACK" "1" "11-Jul-2017" "" "bst track Manual"
+.TH "BST TRACK" "1" "27-Jul-2017" "" "bst track Manual"
 .SH NAME
 bst\-track \- Track new source references
 .SH SYNOPSIS
diff --git a/man/bst-workspace-close.1 b/man/bst-workspace-close.1
new file mode 100644
index 000000000..d3cdc2794
--- /dev/null
+++ b/man/bst-workspace-close.1
@@ -0,0 +1,18 @@
+.TH "BST WORKSPACE CLOSE" "1" "27-Jul-2017" "" "bst workspace close Manual"
+.SH NAME
+bst\-workspace\-close \- Close a workspace
+.SH SYNOPSIS
+.B bst workspace close
+[OPTIONS] ELEMENT
+.SH DESCRIPTION
+Close a workspace
+.SH OPTIONS
+.TP
+\fB\-s,\fP \-\-source TEXT
+The source of the workspace to remove. Projects with one source may omit this
+.TP
+\fB\-\-remove\-dir\fP
+Remove the path that contains the closed workspace
+.TP
+\fB\-\-variant\fP TEXT
+A variant of the specified target
\ No newline at end of file
diff --git a/man/bst-workspace-list.1 b/man/bst-workspace-list.1
new file mode 100644
index 000000000..8c25e2854
--- /dev/null
+++ b/man/bst-workspace-list.1
@@ -0,0 +1,8 @@
+.TH "BST WORKSPACE LIST" "1" "27-Jul-2017" "" "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
diff --git a/man/bst-workspace-open.1 b/man/bst-workspace-open.1
new file mode 100644
index 000000000..bcf8cf0af
--- /dev/null
+++ b/man/bst-workspace-open.1
@@ -0,0 +1,24 @@
+.TH "BST WORKSPACE OPEN" "1" "27-Jul-2017" "" "bst workspace open Manual"
+.SH NAME
+bst\-workspace\-open \- Open a new workspace
+.SH SYNOPSIS
+.B bst workspace open
+[OPTIONS] ELEMENT DIRECTORY
+.SH DESCRIPTION
+Open a workspace for manual source modification
+.SH OPTIONS
+.TP
+\fB\-\-no\-checkout\fP
+Do not checkout the source, only link to the given directory
+.TP
+\fB\-f,\fP \-\-force
+Overwrite files existing in checkout directory
+.TP
+\fB\-s,\fP \-\-source TEXT
+The source to create a workspace for. Projects with one source may omit this
+.TP
+\fB\-\-variant\fP TEXT
+A variant of the specified target
+.TP
+\fB\-\-track\fP
+Track and fetch new source references before checking out the workspace
\ No newline at end of file
diff --git a/man/bst-workspace-reset.1 b/man/bst-workspace-reset.1
new file mode 100644
index 000000000..215f5ca23
--- /dev/null
+++ b/man/bst-workspace-reset.1
@@ -0,0 +1,24 @@
+.TH "BST WORKSPACE RESET" "1" "27-Jul-2017" "" "bst workspace reset Manual"
+.SH NAME
+bst\-workspace\-reset \- Reset a workspace to its original state
+.SH SYNOPSIS
+.B bst workspace reset
+[OPTIONS] ELEMENT
+.SH DESCRIPTION
+Reset a workspace to its original state
+.SH OPTIONS
+.TP
+\fB\-s,\fP \-\-source TEXT
+The source of the workspace to reset. Projects with one source may omit this
+.TP
+\fB\-\-track\fP
+Track and fetch the latest source before resetting
+.TP
+\fB\-\-no\-checkout\fP
+Do not checkout the source, only link to the given directory
+.TP
+\fB\-\-variant\fP TEXT
+A variant of the specified target
+.TP
+\fB\-\-yes\fP
+Confirm the action without prompting.
\ No newline at end of file
diff --git a/man/bst-workspace.1 b/man/bst-workspace.1
new file mode 100644
index 000000000..bf1c78928
--- /dev/null
+++ b/man/bst-workspace.1
@@ -0,0 +1,28 @@
+.TH "BST WORKSPACE" "1" "27-Jul-2017" "" "bst workspace Manual"
+.SH NAME
+bst\-workspace \- Manipulate developer workspaces
+.SH SYNOPSIS
+.B bst workspace
+[OPTIONS] COMMAND [ARGS]...
+.SH DESCRIPTION
+Manipulate developer workspaces
+.SH COMMANDS
+.PP
+\fBclose\fP
+  Close a workspace
+  See \fBbst workspace-close(1)\fP for full documentation on the \fBclose\fP command.
+
+.PP
+\fBlist\fP
+  List open workspaces
+  See \fBbst workspace-list(1)\fP for full documentation on the \fBlist\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
+\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 34b77f049..513478464 100644
--- a/man/bst.1
+++ b/man/bst.1
@@ -1,4 +1,4 @@
-.TH "BST" "1" "11-Jul-2017" "" "bst Manual"
+.TH "BST" "1" "27-Jul-2017" "" "bst Manual"
 .SH NAME
 bst \- Build and manipulate BuildStream projects...
 .SH SYNOPSIS
@@ -32,6 +32,9 @@ Maximum simultaneous build tasks
 \fB\-\-pushers\fP INTEGER
 Maximum simultaneous upload tasks
 .TP
+\fB\-\-network\-retries\fP INTEGER
+Maximum retries for network tasks
+.TP
 \fB\-\-no\-interactive\fP
 Force non interactive mode, otherwise this is automatically decided
 .TP
@@ -61,28 +64,16 @@ Machine architecture for the sandbox (defaults to --arch)
 .TP
 \fB\-\-target\-arch\fP TEXT
 Machine architecture for build output (defaults to --arch)
+.TP
+\fB\-\-strict\fP / \-\-no\-strict
+Elements must be rebuilt when their dependencies have changed
 .SH COMMANDS
 .PP
-\fBcheckout\fP
-  Checkout a built artifact
-  See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\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
-\fBfetch\fP
-  Fetch sources in a pipeline
-  See \fBbst-fetch(1)\fP for full documentation on the \fBfetch\fP command.
-
-.PP
-\fBshow\fP
-  Show elements in the pipeline
-  See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command.
-
-.PP
 \fBbuild\fP
   Build elements in a pipeline
   See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
@@ -93,6 +84,26 @@ Machine architecture for build output (defaults to --arch)
   See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
 
 .PP
+\fBshow\fP
+  Show elements in the pipeline
+  See \fBbst-show(1)\fP for full documentation on the \fBshow\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.
+
+.PP
+\fBfetch\fP
+  Fetch sources in a pipeline
+  See \fBbst-fetch(1)\fP for full documentation on the \fBfetch\fP command.
+
+.PP
+\fBcheckout\fP
+  Checkout a built artifact
+  See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
+
+.PP
+\fBworkspace\fP
+  Manipulate developer workspaces
+  See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command.