Adding man pages to distribution

Man pages are automatically generated but unfortunately committed
to the repository, this should be fixed by integrating the man
page generation as a part of the build step, but this seems to be
very difficult and is not well documented at all.

Tip: The man_pages module of click_man implements a distutils.core.Command
     for generating man pages, this command should be run as a part of setup.py

7 files changed, 238 insertions, 0 deletions

diff --git a/man/bst-build.1 b/man/bst-build.1
new file mode 100644
index 000000000..d00fc500e
--- /dev/null
+++ b/man/bst-build.1
@@ -0,0 +1,18 @@
+.TH "BST BUILD" "1" "12-Apr-2017" "" "bst build Manual"
+.SH NAME
+bst\-build \- Build elements in a pipeline
+.SH SYNOPSIS
+.B bst build
+[OPTIONS] TARGET
+.SH DESCRIPTION
+Build elements in a pipeline
+.SH OPTIONS
+.TP
+\fB\-\-all\fP
+Build elements that would not be needed for the current build plan
+.TP
+\fB\-a,\fP \-\-arch TEXT
+The target architecture (default: x86_64)
+.TP
+\fB\-\-variant\fP TEXT
+A variant of the specified target
\ No newline at end of file
diff --git a/man/bst-checkout.1 b/man/bst-checkout.1
new file mode 100644
index 000000000..80adaffd9
--- /dev/null
+++ b/man/bst-checkout.1
@@ -0,0 +1,19 @@
+.TH "BST CHECKOUT" "1" "12-Apr-2017" "" "bst checkout Manual"
+.SH NAME
+bst\-checkout \- Checkout a built artifact
+.SH SYNOPSIS
+.B bst checkout
+[OPTIONS] TARGET DIRECTORY
+.SH DESCRIPTION
+Checkout a built artifact to the specified directory
+    
+.SH OPTIONS
+.TP
+\fB\-f,\fP \-\-force
+Overwrite files existing in checkout directory
+.TP
+\fB\-a,\fP \-\-arch TEXT
+The target architecture (default: x86_64)
+.TP
+\fB\-\-variant\fP TEXT
+A variant of the specified target
\ No newline at end of file
diff --git a/man/bst-fetch.1 b/man/bst-fetch.1
new file mode 100644
index 000000000..a23d5852c
--- /dev/null
+++ b/man/bst-fetch.1
@@ -0,0 +1,18 @@
+.TH "BST FETCH" "1" "12-Apr-2017" "" "bst fetch Manual"
+.SH NAME
+bst\-fetch \- Fetch sources in a pipeline
+.SH SYNOPSIS
+.B bst fetch
+[OPTIONS] TARGET
+.SH DESCRIPTION
+Fetch sources in a pipeline
+.SH OPTIONS
+.TP
+\fB\-\-needed\fP
+Fetch only sources required to build missing artifacts
+.TP
+\fB\-a,\fP \-\-arch TEXT
+The target architecture (default: x86_64)
+.TP
+\fB\-\-variant\fP TEXT
+A variant of the specified target
\ No newline at end of file
diff --git a/man/bst-shell.1 b/man/bst-shell.1
new file mode 100644
index 000000000..eb173b619
--- /dev/null
+++ b/man/bst-shell.1
@@ -0,0 +1,28 @@
+.TH "BST SHELL" "1" "12-Apr-2017" "" "bst shell Manual"
+.SH NAME
+bst\-shell \- Shell into an element's sandbox environment
+.SH SYNOPSIS
+.B bst shell
+[OPTIONS] TARGET
+.SH DESCRIPTION
+Shell into an element's sandbox environment
+
+This can be used either to debug building or to launch
+test and debug successful build results.
+
+Use the --builddir option with an existing build directory
+or use the --scope option instead to create a new staging
+area automatically.
+.SH OPTIONS
+.TP
+\fB\-b,\fP \-\-builddir DIRECTORY
+Existing build directory
+.TP
+\fB\-s,\fP \-\-scope [build|run]
+Specify element scope to stage
+.TP
+\fB\-a,\fP \-\-arch TEXT
+The target architecture (default: x86_64)
+.TP
+\fB\-\-variant\fP TEXT
+A variant of the specified target
\ No newline at end of file
diff --git a/man/bst-show.1 b/man/bst-show.1
new file mode 100644
index 000000000..371d95240
--- /dev/null
+++ b/man/bst-show.1
@@ -0,0 +1,56 @@
+.TH "BST SHOW" "1" "12-Apr-2017" "" "bst show Manual"
+.SH NAME
+bst\-show \- Show elements in the pipeline
+.SH SYNOPSIS
+.B bst show
+[OPTIONS] TARGET
+.SH DESCRIPTION
+Show elements in the pipeline
+
+By default this will only show the specified element, use
+the --deps option to show an entire pipeline.
+
+
+FORMAT
+~~~~~~
+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 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
+
+The value of the %{symbol} without the leading '%' character is understood
+as a pythonic formatting string, so python formatting features apply,
+examle:
+
+
+    build-stream show target.bst --format \
+        'Name: %{name: ^20} Key: %{key: ^8} State: %{state}'
+
+If you want to use a newline in a format string in bash, use the '$' modifier:
+
+
+    build-stream show target.bst --format \
+        $'---------- %{name} ----------\n%{vars}'
+.SH OPTIONS
+.TP
+\fB\-d,\fP \-\-deps [all|build|run]
+Optionally specify a dependency scope to show
+.TP
+\fB\-\-order\fP [stage|alpha]
+Staging or alphabetic ordering of dependencies
+.TP
+\fB\-f,\fP \-\-format FORMAT
+Format string for each element
+.TP
+\fB\-a,\fP \-\-arch TEXT
+The target architecture (default: x86_64)
+.TP
+\fB\-\-variant\fP TEXT
+A variant of the specified target
\ No newline at end of file
diff --git a/man/bst-track.1 b/man/bst-track.1
new file mode 100644
index 000000000..9c5dde6e0
--- /dev/null
+++ b/man/bst-track.1
@@ -0,0 +1,24 @@
+.TH "BST TRACK" "1" "12-Apr-2017" "" "bst track Manual"
+.SH NAME
+bst\-track \- Track new source references
+.SH SYNOPSIS
+.B bst track
+[OPTIONS] TARGET
+.SH DESCRIPTION
+Track new source references
+
+Updates the project with new source references from
+any sources which are configured to track a remote
+branch or tag.
+
+The project data will be rewritten inline.
+.SH OPTIONS
+.TP
+\fB\-d,\fP \-\-deps [all|build|run]
+Optionally specify a dependency scope to track
+.TP
+\fB\-a,\fP \-\-arch TEXT
+The target architecture (default: x86_64)
+.TP
+\fB\-\-variant\fP TEXT
+A variant of the specified target
\ No newline at end of file
diff --git a/man/bst.1 b/man/bst.1
new file mode 100644
index 000000000..5c3de031d
--- /dev/null
+++ b/man/bst.1
@@ -0,0 +1,75 @@
+.TH "BST" "1" "12-Apr-2017" "" "bst Manual"
+.SH NAME
+bst \- Build and manipulate BuildStream projects...
+.SH SYNOPSIS
+.B bst
+[OPTIONS] COMMAND [ARGS]...
+.SH DESCRIPTION
+Build and manipulate BuildStream projects
+
+Most of the main options override options in the
+user preferences configuration file.
+.SH OPTIONS
+.TP
+\fB\-\-version\fP
+Show the version and exit.
+.TP
+\fB\-c,\fP \-\-config PATH
+Configuration file to use
+.TP
+\fB\-C,\fP \-\-directory DIRECTORY
+Project directory (default: current directory)
+.TP
+\fB\-\-on\-error\fP [continue|quit|terminate]
+What to do when an error is encountered
+.TP
+\fB\-\-fetchers\fP INTEGER
+Maximum simultaneous download tasks
+.TP
+\fB\-\-builders\fP INTEGER
+Maximum simultaneous build tasks
+.TP
+\fB\-\-no\-interactive\fP
+Force non interactive mode, otherwise this is automatically decided
+.TP
+\fB\-\-verbose\fP / \-\-no\-verbose
+Be extra verbose
+.TP
+\fB\-\-debug\fP / \-\-no\-debug
+Print debugging output
+.TP
+\fB\-\-error\-lines\fP INTEGER
+Maximum number of lines to show from a task log
+.TP
+\fB\-\-log\-file\fP FILENAME
+A file to store the main log (allows storing the main log while in interactive mode)
+.SH COMMANDS
+.PP
+\fBtrack\fP
+  Track new source references
+  See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
+
+.PP
+\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
+\fBcheckout\fP
+  Checkout a built artifact
+  See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\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.