NEWS, man: Update documentation, add NEWS entryAlexFazakas/add-bst-init-argument

As we are making breaking changes, add a NEWS entry and
update the documentation.

23 files changed, 71 insertions, 68 deletions

diff --git a/NEWS b/NEWS
index 3e715187b..4b1d63a66 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,9 @@
 buildstream 1.3.1
 =================
 
+  o BREAKING CHANGE: `bst init` no longer uses the `--directory` or `-C`
+    option. Instead, it (optionally) takes a directory as an argument.
+
   o BREAKING CHANGE: `Plugin.node_items` doesn't accept 'dict' values anymore.
     Please used `Node`s instead.
 
diff --git a/man/bst-artifact-checkout.1 b/man/bst-artifact-checkout.1
index 2bf023c8a..eb16f6ffe 100644
--- a/man/bst-artifact-checkout.1
+++ b/man/bst-artifact-checkout.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT CHECKOUT" "1" "27-Jun-2019" "" "bst artifact checkout Manual"
+.TH "BST ARTIFACT CHECKOUT" "1" "01-Jul-2019" "" "bst artifact checkout Manual"
 .SH NAME
 bst\-artifact\-checkout \- Checkout contents of an artifact
 .SH SYNOPSIS
diff --git a/man/bst-artifact-delete.1 b/man/bst-artifact-delete.1
index 4cc737d0e..8f80cbcaa 100644
--- a/man/bst-artifact-delete.1
+++ b/man/bst-artifact-delete.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT DELETE" "1" "27-Jun-2019" "" "bst artifact delete Manual"
+.TH "BST ARTIFACT DELETE" "1" "01-Jul-2019" "" "bst artifact delete Manual"
 .SH NAME
 bst\-artifact\-delete \- Remove artifacts from the local cache
 .SH SYNOPSIS
diff --git a/man/bst-artifact-log.1 b/man/bst-artifact-log.1
index 88c797a78..cfe4b15b1 100644
--- a/man/bst-artifact-log.1
+++ b/man/bst-artifact-log.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT LOG" "1" "27-Jun-2019" "" "bst artifact log Manual"
+.TH "BST ARTIFACT LOG" "1" "01-Jul-2019" "" "bst artifact log Manual"
 .SH NAME
 bst\-artifact\-log \- Show logs of artifacts
 .SH SYNOPSIS
diff --git a/man/bst-artifact-pull.1 b/man/bst-artifact-pull.1
index 1369b97cd..a78178142 100644
--- a/man/bst-artifact-pull.1
+++ b/man/bst-artifact-pull.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT PULL" "1" "27-Jun-2019" "" "bst artifact pull Manual"
+.TH "BST ARTIFACT PULL" "1" "01-Jul-2019" "" "bst artifact pull Manual"
 .SH NAME
 bst\-artifact\-pull \- Pull a built artifact
 .SH SYNOPSIS
diff --git a/man/bst-artifact-push.1 b/man/bst-artifact-push.1
index 0e8bb424c..88115a891 100644
--- a/man/bst-artifact-push.1
+++ b/man/bst-artifact-push.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT PUSH" "1" "27-Jun-2019" "" "bst artifact push Manual"
+.TH "BST ARTIFACT PUSH" "1" "01-Jul-2019" "" "bst artifact push Manual"
 .SH NAME
 bst\-artifact\-push \- Push a built artifact
 .SH SYNOPSIS
diff --git a/man/bst-artifact-server.1 b/man/bst-artifact-server.1
index bf230c73e..7f10ee5d9 100644
--- a/man/bst-artifact-server.1
+++ b/man/bst-artifact-server.1
@@ -1,4 +1,4 @@
-.TH "BST-ARTIFACT-SERVER" "1" "27-Jun-2019" "" "bst-artifact-server Manual"
+.TH "BST-ARTIFACT-SERVER" "1" "01-Jul-2019" "" "bst-artifact-server Manual"
 .SH NAME
 bst-artifact-server \- CAS Artifact Server
 .SH SYNOPSIS
diff --git a/man/bst-artifact.1 b/man/bst-artifact.1
index dbb359bc6..7f65dce5b 100644
--- a/man/bst-artifact.1
+++ b/man/bst-artifact.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT" "1" "27-Jun-2019" "" "bst artifact Manual"
+.TH "BST ARTIFACT" "1" "01-Jul-2019" "" "bst artifact Manual"
 .SH NAME
 bst\-artifact \- Manipulate cached artifacts
 .SH SYNOPSIS
@@ -8,10 +8,6 @@ bst\-artifact \- Manipulate cached artifacts
 Manipulate cached artifacts
 .SH COMMANDS
 .PP
-\fBcheckout\fP
-  Checkout contents of an artifact
-  See \fBbst artifact-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
-.PP
 \fBpull\fP
   Pull a built artifact
   See \fBbst artifact-pull(1)\fP for full documentation on the \fBpull\fP command.
@@ -20,10 +16,14 @@ Manipulate cached artifacts
   Push a built artifact
   See \fBbst artifact-push(1)\fP for full documentation on the \fBpush\fP command.
 .PP
+\fBdelete\fP
+  Remove artifacts from the local cache
+  See \fBbst artifact-delete(1)\fP for full documentation on the \fBdelete\fP command.
+.PP
 \fBlog\fP
   Show logs of artifacts
   See \fBbst artifact-log(1)\fP for full documentation on the \fBlog\fP command.
 .PP
-\fBdelete\fP
-  Remove artifacts from the local cache
-  See \fBbst artifact-delete(1)\fP for full documentation on the \fBdelete\fP command.
+\fBcheckout\fP
+  Checkout contents of an artifact
+  See \fBbst artifact-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
diff --git a/man/bst-build.1 b/man/bst-build.1
index 04b57455d..760f1390e 100644
--- a/man/bst-build.1
+++ b/man/bst-build.1
@@ -1,4 +1,4 @@
-.TH "BST BUILD" "1" "27-Jun-2019" "" "bst build Manual"
+.TH "BST BUILD" "1" "01-Jul-2019" "" "bst build Manual"
 .SH NAME
 bst\-build \- Build elements in a pipeline
 .SH SYNOPSIS
diff --git a/man/bst-help.1 b/man/bst-help.1
index 69de66469..77b2dde3e 100644
--- a/man/bst-help.1
+++ b/man/bst-help.1
@@ -1,4 +1,4 @@
-.TH "BST HELP" "1" "27-Jun-2019" "" "bst help Manual"
+.TH "BST HELP" "1" "01-Jul-2019" "" "bst help Manual"
 .SH NAME
 bst\-help \- Print usage information
 .SH SYNOPSIS
diff --git a/man/bst-init.1 b/man/bst-init.1
index 351551c0e..7ec8cd04b 100644
--- a/man/bst-init.1
+++ b/man/bst-init.1
@@ -1,9 +1,9 @@
-.TH "BST INIT" "1" "27-Jun-2019" "" "bst init Manual"
+.TH "BST INIT" "1" "01-Jul-2019" "" "bst init Manual"
 .SH NAME
 bst\-init \- Initialize a new BuildStream project
 .SH SYNOPSIS
 .B bst init
-[OPTIONS]
+[OPTIONS] [TARGET_DIRECTORY]
 .SH DESCRIPTION
 Initialize a new BuildStream project
 .PP
diff --git a/man/bst-shell.1 b/man/bst-shell.1
index 4a068f7a9..61970597f 100644
--- a/man/bst-shell.1
+++ b/man/bst-shell.1
@@ -1,4 +1,4 @@
-.TH "BST SHELL" "1" "27-Jun-2019" "" "bst shell Manual"
+.TH "BST SHELL" "1" "01-Jul-2019" "" "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 9c4958e61..b7ea98022 100644
--- a/man/bst-show.1
+++ b/man/bst-show.1
@@ -1,4 +1,4 @@
-.TH "BST SHOW" "1" "27-Jun-2019" "" "bst show Manual"
+.TH "BST SHOW" "1" "01-Jul-2019" "" "bst show Manual"
 .SH NAME
 bst\-show \- Show elements in the pipeline
 .SH SYNOPSIS
diff --git a/man/bst-source-checkout.1 b/man/bst-source-checkout.1
index 57c43e926..592be1542 100644
--- a/man/bst-source-checkout.1
+++ b/man/bst-source-checkout.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE CHECKOUT" "1" "27-Jun-2019" "" "bst source checkout Manual"
+.TH "BST SOURCE CHECKOUT" "1" "01-Jul-2019" "" "bst source checkout Manual"
 .SH NAME
 bst\-source\-checkout \- Checkout sources for an element
 .SH SYNOPSIS
diff --git a/man/bst-source-fetch.1 b/man/bst-source-fetch.1
index cdd2bf57a..d3f2d6d81 100644
--- a/man/bst-source-fetch.1
+++ b/man/bst-source-fetch.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE FETCH" "1" "27-Jun-2019" "" "bst source fetch Manual"
+.TH "BST SOURCE FETCH" "1" "01-Jul-2019" "" "bst source fetch Manual"
 .SH NAME
 bst\-source\-fetch \- Fetch sources in a pipeline
 .SH SYNOPSIS
diff --git a/man/bst-source-track.1 b/man/bst-source-track.1
index 92a415d03..df15b3d2e 100644
--- a/man/bst-source-track.1
+++ b/man/bst-source-track.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE TRACK" "1" "27-Jun-2019" "" "bst source track Manual"
+.TH "BST SOURCE TRACK" "1" "01-Jul-2019" "" "bst source track Manual"
 .SH NAME
 bst\-source\-track \- Track new source references
 .SH SYNOPSIS
diff --git a/man/bst-source.1 b/man/bst-source.1
index cc28519e2..1726d50ab 100644
--- a/man/bst-source.1
+++ b/man/bst-source.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE" "1" "27-Jun-2019" "" "bst source Manual"
+.TH "BST SOURCE" "1" "01-Jul-2019" "" "bst source Manual"
 .SH NAME
 bst\-source \- Manipulate sources for an element
 .SH SYNOPSIS
@@ -8,10 +8,6 @@ bst\-source \- Manipulate sources for an element
 Manipulate sources for an element
 .SH COMMANDS
 .PP
-\fBfetch\fP
-  Fetch sources in a pipeline
-  See \fBbst source-fetch(1)\fP for full documentation on the \fBfetch\fP command.
-.PP
 \fBtrack\fP
   Track new source references
   See \fBbst source-track(1)\fP for full documentation on the \fBtrack\fP command.
@@ -19,3 +15,7 @@ Manipulate sources for an element
 \fBcheckout\fP
   Checkout sources for an element
   See \fBbst source-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
+.PP
+\fBfetch\fP
+  Fetch sources in a pipeline
+  See \fBbst source-fetch(1)\fP for full documentation on the \fBfetch\fP command.
diff --git a/man/bst-workspace-close.1 b/man/bst-workspace-close.1
index 6dbd7be74..4331e87fb 100644
--- a/man/bst-workspace-close.1
+++ b/man/bst-workspace-close.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE CLOSE" "1" "27-Jun-2019" "" "bst workspace close Manual"
+.TH "BST WORKSPACE CLOSE" "1" "01-Jul-2019" "" "bst workspace close Manual"
 .SH NAME
 bst\-workspace\-close \- Close workspaces
 .SH SYNOPSIS
diff --git a/man/bst-workspace-list.1 b/man/bst-workspace-list.1
index f318967b9..d892b6a35 100644
--- a/man/bst-workspace-list.1
+++ b/man/bst-workspace-list.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE LIST" "1" "27-Jun-2019" "" "bst workspace list Manual"
+.TH "BST WORKSPACE LIST" "1" "01-Jul-2019" "" "bst workspace list Manual"
 .SH NAME
 bst\-workspace\-list \- List open workspaces
 .SH SYNOPSIS
diff --git a/man/bst-workspace-open.1 b/man/bst-workspace-open.1
index 047330193..522f8d806 100644
--- a/man/bst-workspace-open.1
+++ b/man/bst-workspace-open.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE OPEN" "1" "27-Jun-2019" "" "bst workspace open Manual"
+.TH "BST WORKSPACE OPEN" "1" "01-Jul-2019" "" "bst workspace open Manual"
 .SH NAME
 bst\-workspace\-open \- Open a new workspace
 .SH SYNOPSIS
diff --git a/man/bst-workspace-reset.1 b/man/bst-workspace-reset.1
index 7f3e2c8ae..f0d712c74 100644
--- a/man/bst-workspace-reset.1
+++ b/man/bst-workspace-reset.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE RESET" "1" "27-Jun-2019" "" "bst workspace reset Manual"
+.TH "BST WORKSPACE RESET" "1" "01-Jul-2019" "" "bst workspace reset Manual"
 .SH NAME
 bst\-workspace\-reset \- Reset a workspace to its original state
 .SH SYNOPSIS
diff --git a/man/bst-workspace.1 b/man/bst-workspace.1
index 4d2ee00ff..091ac4df6 100644
--- a/man/bst-workspace.1
+++ b/man/bst-workspace.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE" "1" "27-Jun-2019" "" "bst workspace Manual"
+.TH "BST WORKSPACE" "1" "01-Jul-2019" "" "bst workspace Manual"
 .SH NAME
 bst\-workspace \- Manipulate developer workspaces
 .SH SYNOPSIS
@@ -8,18 +8,18 @@ bst\-workspace \- Manipulate developer workspaces
 Manipulate developer workspaces
 .SH COMMANDS
 .PP
-\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
+\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
-\fBlist\fP
-  List open workspaces
-  See \fBbst workspace-list(1)\fP for full documentation on the \fBlist\fP command.
+\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 3ca3ca3be..dc45b2696 100644
--- a/man/bst.1
+++ b/man/bst.1
@@ -1,4 +1,4 @@
-.TH "BST" "1" "27-Jun-2019" "" "bst Manual"
+.TH "BST" "1" "01-Jul-2019" "" "bst Manual"
 .SH NAME
 bst \- Build and manipulate BuildStream projects...
 .SH SYNOPSIS
@@ -72,33 +72,37 @@ Include an element's build tree when pulling remote element artifacts
 Cache artifact build tree content on creation
 .SH COMMANDS
 .PP
-\fBhelp\fP
-  Print usage information
-  See \fBbst-help(1)\fP for full documentation on the \fBhelp\fP command.
-.PP
-\fBinit\fP
-  Initialize a new BuildStream project
-  See \fBbst-init(1)\fP for full documentation on the \fBinit\fP command.
+\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.
+\fBpull\fP
+  COMMAND OBSOLETE - Pull a built artifact
+  See \fBbst-pull(1)\fP for full documentation on the \fBpull\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.
+\fBtrack\fP
+  COMMAND OBSOLETE - Track new source references
+  See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
 .PP
 \fBsource\fP
   Manipulate sources for an element
   See \fBbst-source(1)\fP for full documentation on the \fBsource\fP command.
 .PP
-\fBworkspace\fP
-  Manipulate developer workspaces
-  See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command.
+\fBpush\fP
+  COMMAND OBSOLETE - Push a built artifact
+  See \fBbst-push(1)\fP for full documentation on the \fBpush\fP command.
+.PP
+\fBbuild\fP
+  Build elements in a pipeline
+  See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
+.PP
+\fBhelp\fP
+  Print usage information
+  See \fBbst-help(1)\fP for full documentation on the \fBhelp\fP command.
 .PP
 \fBartifact\fP
   Manipulate cached artifacts
@@ -108,18 +112,14 @@ Cache artifact build tree content on creation
   COMMAND OBSOLETE - Fetch sources in a pipeline
   See \fBbst-fetch(1)\fP for full documentation on the \fBfetch\fP command.
 .PP
-\fBtrack\fP
-  COMMAND OBSOLETE - Track new source references
-  See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
+\fBshell\fP
+  Shell into an element's sandbox environment
+  See \fBbst-shell(1)\fP for full documentation on the \fBshell\fP command.
+.PP
+\fBinit\fP
+  Initialize a new BuildStream project
+  See \fBbst-init(1)\fP for full documentation on the \fBinit\fP command.
 .PP
 \fBcheckout\fP
   COMMAND OBSOLETE - Checkout a built artifact
   See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
-.PP
-\fBpull\fP
-  COMMAND OBSOLETE - Pull a built artifact
-  See \fBbst-pull(1)\fP for full documentation on the \fBpull\fP command.
-.PP
-\fBpush\fP
-  COMMAND OBSOLETE - Push a built artifact
-  See \fBbst-push(1)\fP for full documentation on the \fBpush\fP command.