[PATCH 1/1] man: portability tweaks

Some minor alterations that will make these man pages portable. --- man/bst-artifact-receive.1 | 2 +- man/bst-checkout.1 | 2 +- man/bst-fetch.1 | 17 ++++++---- man/bst-shell.1 | 4 +-- man/bst-show.1 | 79 ++++++++++++++++++++++++++-------------------- man/bst-source-bundle.1 | 15 +++++---- man/bst-track.1 | 15 +++++---- man/bst-workspace.1 | 36 ++++++++++++++------- man/bst.1 | 72 ++++++++++++++++++++++++++++-------------- 9 files changed, 149 insertions(+), 93 deletions(-) diff --git a/man/bst-artifact-receive.1 b/man/bst-artifact-receive.1 index 4b158d9..23da928 100644 --- a/man/bst-artifact-receive.1 +++ b/man/bst-artifact-receive.1 @@ -6,7 +6,7 @@ bst-artifact-receive \- Receive pushed artifacts over ssh [OPTIONS] REPO .SH DESCRIPTION A BuildStream sister program for receiving artifacts send to a shared artifact cache - +.PP .SH OPTIONS .TP \fB\-v,\fP \-\-verbose diff --git a/man/bst-checkout.1 b/man/bst-checkout.1 index 36786c6..4bd3180 100644 --- a/man/bst-checkout.1 +++ b/man/bst-checkout.1 @@ -6,7 +6,7 @@ bst\-checkout \- Checkout a built artifact [OPTIONS] TARGET DIRECTORY .SH DESCRIPTION Checkout a built artifact to the specified directory - +.PP .SH OPTIONS .TP \fB\-f,\fP \-\-force diff --git a/man/bst-fetch.1 b/man/bst-fetch.1 index 7b9c929..a6e00f0 100644 --- a/man/bst-fetch.1 +++ b/man/bst-fetch.1 @@ -6,18 +6,21 @@ bst\-fetch \- Fetch sources in a pipeline [OPTIONS] TARGET .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: - - - none: No dependencies, just the element itself - plan: Only dependencies required for the build plan - all: All dependencies +.PP +.nf +.RS +none: No dependencies, just the element itself +plan: Only dependencies required for the build plan +all: All dependencies +.RE +.fi .SH OPTIONS .TP \fB\-\-except\fP TEXT diff --git a/man/bst-shell.1 b/man/bst-shell.1 index 510a491..c8e18db 100644 --- a/man/bst-shell.1 +++ b/man/bst-shell.1 @@ -6,10 +6,10 @@ bst\-shell \- Shell into an element's sandbox environment [OPTIONS] TARGET .SH DESCRIPTION Shell into an element's sandbox environment - +.PP This can be used either to debug building or to launch test and debug successful build results. - +.PP Use the --builddir option with an existing build directory or use the --scope option instead to create a new staging area automatically. diff --git a/man/bst-show.1 b/man/bst-show.1 index eb09711..d7ea6bf 100644 --- a/man/bst-show.1 +++ b/man/bst-show.1 @@ -6,51 +6,62 @@ bst\-show \- Show elements in the pipeline [OPTIONS] TARGET .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: - - - 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 +.nf +.RS +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 +.RE +.fi +.PP 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 - %{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 - +.PP +.nf +.RS +%{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 +.RE +.fi +.PP The value of the %{symbol} without the leading '%' character is understood as a pythonic formatting string, so python formatting features apply, examle: - - - bst show target.bst --format \ - 'Name: %{name: ^20} Key: %{key: ^8} State: %{state}' - +.PP +.nf +.RS +bst show target.bst --format \ + 'Name: %{name: ^20} Key: %{key: ^8} State: %{state}' +.RE +.fi +.PP If you want to use a newline in a format string in bash, use the '$' modifier: - - - bst show target.bst --format \ - $'---------- %{name} ----------\n%{vars}' +.PP +.nf +.RS +bst show target.bst --format \ +$'---------- %{name} ----------\n%{vars}' +.RE +.fi .SH OPTIONS .TP \fB\-\-except\fP TEXT diff --git a/man/bst-source-bundle.1 b/man/bst-source-bundle.1 index 43abe4d..942dc96 100644 --- a/man/bst-source-bundle.1 +++ b/man/bst-source-bundle.1 @@ -6,13 +6,16 @@ bst\-source-bundle \- Produce a build bundle to be manually executed [OPTIONS] TARGET .SH DESCRIPTION Produce a build bundle to be manually executed - +.PP Specify `--deps` to control which elements to show: - - - none: No dependencies, just the element itself - run: Runtime dependencies, including the element itself - build: Build time dependencies, excluding the element itself +.PP +.nf +.RS +none: No dependencies, just the element itself +run: Runtime dependencies, including the element itself +build: Build time dependencies, excluding the element itself +.RE +.fi .SH OPTIONS .TP \fB\-\-except\fP TEXT diff --git a/man/bst-track.1 b/man/bst-track.1 index b14ff3a..94c10e6 100644 --- a/man/bst-track.1 +++ b/man/bst-track.1 @@ -7,15 +7,18 @@ 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: - - - none: No dependencies, just the element itself - all: All dependencies +.PP +.nf +.RS +none: No dependencies, just the element itself +all: All dependencies +.RE +.fi .SH OPTIONS .TP \fB\-\-except\fP TEXT diff --git a/man/bst-workspace.1 b/man/bst-workspace.1 index bf1c789..f34b6cc 100644 --- a/man/bst-workspace.1 +++ b/man/bst-workspace.1 @@ -7,22 +7,34 @@ bst\-workspace \- Manipulate developer workspaces .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. - +.nf +.RS +Close a workspace +See \fBbst workspace-close(1)\fP for full documentation on the \fBclose\fP command. +.RE +.fi .PP \fBlist\fP - List open workspaces - See \fBbst workspace-list(1)\fP for full documentation on the \fBlist\fP command. - +.nf +.RS +List open workspaces +See \fBbst workspace-list(1)\fP for full documentation on the \fBlist\fP command. +.RE +.fi .PP \fBreset\fP - Reset a workspace to its original state - See \fBbst workspace-reset(1)\fP for full documentation on the \fBreset\fP command. - +.nf +.RS +Reset a workspace to its original state +See \fBbst workspace-reset(1)\fP for full documentation on the \fBreset\fP command. +.RE +.fi .PP \fBopen\fP - Open a new workspace - See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command. +.nf +.RS +Open a new workspace +See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command. +.RE +.fi diff --git a/man/bst.1 b/man/bst.1 index 5134784..453596f 100644 --- a/man/bst.1 +++ b/man/bst.1 @@ -68,42 +68,66 @@ Machine architecture for build output (defaults to --arch) \fB\-\-strict\fP / \-\-no\-strict Elements must be rebuilt when their dependencies have changed .SH COMMANDS -.PP \fBshell\fP - Shell into an element's sandbox environment - See \fBbst-shell(1)\fP for full documentation on the \fBshell\fP command. - +.nf +.RS +Shell into an element's sandbox environment +See \fBbst-shell(1)\fP for full documentation on the \fBshell\fP command. +.RE +.fi .PP \fBbuild\fP - Build elements in a pipeline - See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command. - +.nf +.RS +Build elements in a pipeline +See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command. +.RE +.fi .PP \fBtrack\fP - Track new source references - See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command. - +.nf +.RS +Track new source references +See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command. +.RE +.fi .PP \fBshow\fP - Show elements in the pipeline - See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command. - +.nf +.RS +Show elements in the pipeline +See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command. +.RE +.fi .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. - +.nf +.RS +Produce a build bundle to be manually executed +See \fBbst-source-bundle(1)\fP for full documentation on the \fBsource-bundle\fP command. +.RE +.fi .PP \fBfetch\fP - Fetch sources in a pipeline - See \fBbst-fetch(1)\fP for full documentation on the \fBfetch\fP command. - +.nf +.RS +Fetch sources in a pipeline +See \fBbst-fetch(1)\fP for full documentation on the \fBfetch\fP command. +.RE +.fi .PP \fBcheckout\fP - Checkout a built artifact - See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command. - +.nf +.RS +Checkout a built artifact +See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command. +.RE +.fi .PP \fBworkspace\fP - Manipulate developer workspaces - See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command. +.nf +.RS +Manipulate developer workspaces +See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command. +.RE +.fi \ No newline at end of file -- 2.11.0