[PATCH 1/1] man: portability tweaks

Richard Ipsum richardipsum at fastmail.co.uk
Mon Aug 28 16:02:19 BST 2017


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




More information about the baserock-dev mailing list