aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--bdep/bdep.cli90
-rw-r--r--bdep/common.cli148
-rw-r--r--bdep/help.cli30
-rw-r--r--bdep/init.cli29
-rw-r--r--doc/.gitignore5
l---------doc/a4.html2ps1
-rwxr-xr-xdoc/cli.sh83
l---------doc/code-box.css1
l---------doc/common.css1
l---------doc/doc-epilogue.xhtml1
l---------doc/doc-prologue.xhtml1
l---------doc/doc.css1
l---------doc/doc.html2ps1
l---------doc/letter.html2ps1
l---------doc/man-epilogue.11
l---------doc/man-epilogue.xhtml1
l---------doc/man-prologue.11
l---------doc/man-prologue.xhtml1
l---------doc/man.css1
l---------doc/pre-box.css1
l---------doc/toc.css1
21 files changed, 400 insertions, 0 deletions
diff --git a/bdep/bdep.cli b/bdep/bdep.cli
new file mode 100644
index 0000000..67460b0
--- /dev/null
+++ b/bdep/bdep.cli
@@ -0,0 +1,90 @@
+// file : bdep/bdep.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license : MIT; see accompanying LICENSE file
+
+include <bdep/common.cli>;
+
+"\section=1"
+"\name=bdep"
+"\summary=project dependency manager"
+
+namespace bdep
+{
+ {
+ "<command> <topic> <common-options> <command-options> <command-args>",
+
+ "\h|SYNOPSIS|
+
+ \cb{bdep --help}\n
+ \cb{bdep --version}\n
+ \c{\b{bdep help} [<command> | <topic>]}\n
+ \c{\b{bdep} [<common-options>] <command> [<command-options>] <command-args>}
+
+ \h|DESCRIPTION|
+
+ The \cb{build2} project dependency manager is used to @@ TODO.
+
+ For a detailed description of any command or help topic, use the
+ \cb{help} command or see the corresponding man page (the man pages have
+ the \cb{bdep-} prefix, for example \l{bdep-help(1)}). Note also that
+ <command-options> and <command-args> can be specified in any order and
+ <common-options> can be specified as part of <command-options>."
+ }
+
+ // For usage it's nice to see the list of commands on the first page. So
+ // let's not put this "extended" description into usage.
+ //
+ {
+ "",
+ "",
+
+ //@@ TODO
+ "Description...
+ "
+ }
+
+ class commands
+ {
+ "\h|COMMANDS|"
+
+ //
+ // NOTE: Use the same sentence as in the page's \summary and make
+ // sure it is short enough to fit in one line in usage.
+ //
+
+ bool help
+ {
+ "[<topic>]",
+ "\l{bdep-help(1)} \- show help for a command or help topic",
+ ""
+ }
+
+ bool init
+ {
+ "\l{bdep-init(1)} \- @@ TODO"
+ }
+ };
+
+ // Make sure these don't conflict with command names above.
+ //
+ class topics
+ {
+ "\h|HELP TOPICS|"
+
+ bool common-options
+ {
+ "\l{bdep-common-options(1)} \- details on common options"
+ }
+ };
+
+ class options: common_options
+ {
+ bool --help;
+ bool --version;
+ };
+
+ "\h|EXIT STATUS|
+
+ Non-zero exit status is returned in case of an error.
+ "
+}
diff --git a/bdep/common.cli b/bdep/common.cli
new file mode 100644
index 0000000..168233b
--- /dev/null
+++ b/bdep/common.cli
@@ -0,0 +1,148 @@
+// file : bdep/common.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license : MIT; see accompanying LICENSE file
+
+// @@ TODO
+//include <bdep/types.hxx>;
+
+"\section=1"
+"\name=bdep-common-options"
+"\summary=details on common options"
+
+namespace bdep
+{
+ {
+ "<common-options>",
+
+ "\h|SYNOPSIS|
+
+ \c{\b{bdep} [<common-options>] ...}
+
+ \h|DESCRIPTION|
+
+ The common options control behavior that is common to all or most of the
+ \cb{bdep} commands. They can be specified either before the command or
+ after, together with the command-specific options."
+ }
+
+ class common_options = 0
+ {
+ "\h|COMMON OPTIONS|"
+
+ // Retain this note only in the summary.
+ //
+ {
+ "",
+ "The common options are summarized below with a more detailed description
+ available in \l{bdep-common-options(1)}.",
+ ""
+ }
+
+ bool -v
+ {
+ "Print essential underlying commands being executed. This is equivalent
+ to \cb{--verbose 2}."
+ }
+
+ bool -V
+ {
+ "Print all underlying commands being executed. This is equivalent to
+ \cb{--verbose 3}."
+ }
+
+ bool --quiet|-q
+ {
+ "Run quietly, only printing error messages. This is equivalent
+ to \cb{--verbose 0}."
+ }
+
+ uint16_t --verbose = 1
+ {
+ "<level>",
+ "Set the diagnostics verbosity to <level> between 0 and 6. Level 0
+ disables any non-error messages while level 6 produces lots of
+ information, with level 1 being the default. The following additional
+ types of diagnostics are produced at each level:
+
+ \ol|
+
+ \li|High-level information messages.|
+
+ \li|Essential underlying commands being executed.|
+
+ \li|All underlying commands being executed.|
+
+ \li|Information that could be helpful to the user.|
+
+ \li|Information that could be helpful to the developer.|
+
+ \li|Even more detailed information.||"
+ }
+
+ path --build
+ {
+ "<path>",
+ "The build program to be used to build packages. This should be the path
+ to the build2 \cb{b} executable. You can also specify additional options
+ that should be passed to the build program with \cb{--build-option}.
+
+ If the build program is not explicitly specified, then \cb{bdep} will
+ by default use \cb{b} plus an executable suffix if one was specified
+ when building \cb{bdep}. So, for example, if \cb{bdep} name was set
+ to \cb{bdep-1.0}, then it will look for \cb{b-1.0}."
+ }
+
+ strings --build-option
+ {
+ "<opt>",
+ "Additional option to be passed to the build program. See \cb{--build}
+ for more information on the build program. Repeat this option to specify
+ multiple build options."
+ }
+
+ //@@ TODO: add --bpkg and --bpkg-option
+
+ string --pager // String to allow empty value.
+ {
+ "<path>",
+ "The pager program to be used to show long text. Commonly used pager
+ programs are \cb{less} and \cb{more}. You can also specify additional
+ options that should be passed to the pager program with
+ \cb{--pager-option}. If an empty string is specified as the pager
+ program, then no pager will be used. If the pager program is not
+ explicitly specified, then \cb{bdep} will try to use \cb{less}. If it
+ is not available, then no pager will be used."
+ }
+
+ strings --pager-option
+ {
+ "<opt>",
+ "Additional option to be passed to the pager program. See \cb{--pager}
+ for more information on the pager program. Repeat this option to
+ specify multiple pager options."
+ }
+
+ // The following option is "fake" in that it is actually handled by
+ // argv_file_scanner. We have it here for documentation.
+ //
+ string --options-file
+ {
+ "<file>",
+ "Read additional options from <file>. Each option should appearing on a
+ separate line optionally followed by space and an option value. Empty
+ lines and lines starting with \cb{#} are ignored. Option values can
+ be enclosed in double (\cb{\"}) or single (\cb{'}) quotes to preserve
+ leading and trailing whitespaces as well as to specify empty values.
+ If the value itself contains trailing or leading quotes, enclose it
+ with an extra pair of quotes, for example \cb{'\"x\"'}. Non-leading
+ and non-trailing quotes are interpreted as being part of the option
+ value.
+
+ The semantics of providing options in a file is equivalent to providing
+ the same set of options in the same order on the command line at the
+ point where the \cb{--options-file} option is specified except that
+ the shell escaping and quoting is not required. You can repeat this
+ option to specify more than one options file."
+ }
+ };
+}
diff --git a/bdep/help.cli b/bdep/help.cli
new file mode 100644
index 0000000..c62a604
--- /dev/null
+++ b/bdep/help.cli
@@ -0,0 +1,30 @@
+// file : bdep/help.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license : MIT; see accompanying LICENSE file
+
+include <bdep/common.cli>;
+
+"\section=1"
+"\name=bdep-help"
+"\summary=show help for a command or help topic"
+
+namespace bdep
+{
+ {
+ "<command> <topic>",
+
+ "\h|SYNOPSIS|
+
+ \c{\b{bdep help} [<command> | <topic>]}
+
+ \h|DESCRIPTION|
+
+ Show the detailed help for <command> or help <topic> or a summary of
+ available commands and topics if none was specified."
+ }
+
+ class help_options: common_options
+ {
+ //"\h|HELP OPTIONS|"
+ };
+}
diff --git a/bdep/init.cli b/bdep/init.cli
new file mode 100644
index 0000000..75178f8
--- /dev/null
+++ b/bdep/init.cli
@@ -0,0 +1,29 @@
+// file : bdep/init.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license : MIT; see accompanying LICENSE file
+
+include <bdep/common.cli>;
+
+"\section=1"
+"\name=bdep-init"
+"\summary=@@ TODO"
+
+namespace bdep
+{
+ {
+ "<options>",
+
+ "\h|SYNOPSIS|
+
+ \c{\b{bdep init} [<options>] @@ TODO}
+
+ \h|DESCRIPTION|
+
+ The \cb{init} command..."
+ }
+
+ class init_options: common_options
+ {
+ //"\h|INIT OPTIONS|"
+ };
+}
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..66632ae
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,5 @@
+bdep*.xhtml
+bdep*.1
+build2-project-manager-manual*.ps
+build2-project-manager-manual*.pdf
+build2-project-manager-manual.xhtml
diff --git a/doc/a4.html2ps b/doc/a4.html2ps
new file mode 120000
index 0000000..4b31c06
--- /dev/null
+++ b/doc/a4.html2ps
@@ -0,0 +1 @@
+style/a4.html2ps \ No newline at end of file
diff --git a/doc/cli.sh b/doc/cli.sh
new file mode 100755
index 0000000..d06c181
--- /dev/null
+++ b/doc/cli.sh
@@ -0,0 +1,83 @@
+#! /usr/bin/env bash
+
+version=0.7.0-a.0.z
+date="$(date +"%B %Y")"
+
+trap 'exit 1' ERR
+set -o errtrace # Trap in functions.
+
+function info () { echo "$*" 1>&2; }
+function error () { info "$*"; exit 1; }
+
+while [ $# -gt 0 ]; do
+ case $1 in
+ --clean)
+ rm -f bdep*.xhtml bdep*.1
+ rm -f build2-project-manager-manual*.ps \
+ build2-project-manager-manual*.pdf \
+ build2-project-manager-manual.xhtml
+ exit 0
+ ;;
+ *)
+ error "unexpected $1"
+ ;;
+ esac
+done
+
+function compile ()
+{
+ local n=$1; shift
+
+ # Use a bash array to handle empty arguments.
+ #
+ local o=()
+ while [ $# -gt 0 ]; do
+ o=("${o[@]}" "$1")
+ shift
+ done
+
+ cli -I .. -v project="bdep" -v version="$version" -v date="$date" \
+--include-base-last "${o[@]}" --generate-html --html-prologue-file \
+man-prologue.xhtml --html-epilogue-file man-epilogue.xhtml --html-suffix .xhtml \
+--link-regex '%bdep(#.+)?%build2-project-manager-manual.xhtml$1%' \
+../bdep/$n.cli
+
+ cli -I .. -v project="bdep" -v version="$version" -v date="$date" \
+--include-base-last "${o[@]}" --generate-man --man-prologue-file \
+man-prologue.1 --man-epilogue-file man-epilogue.1 --man-suffix .1 \
+--link-regex '%bdep(#.+)?%$1%' \
+../bdep/$n.cli
+}
+
+o="--output-prefix bdep- --class-doc bdep::common_options=short"
+
+# A few special cases.
+#
+compile "common" $o --output-suffix "-options" --class-doc bdep::common_options=long
+compile "bdep" $o --output-prefix "" --suppress-undocumented --class-doc bdep::commands=short --class-doc bdep::topics=short
+
+pages="bdep common help init"
+
+for p in $pages; do
+ compile $p $o
+done
+
+# Manual.
+#
+exit 0
+
+cli -I .. \
+-v version="$(echo "$version" | sed -e 's/^\([^.]*\.[^.]*\).*/\1/')" \
+-v date="$date" \
+--generate-html --html-suffix .xhtml \
+--html-prologue-file doc-prologue.xhtml \
+--html-epilogue-file doc-epilogue.xhtml \
+--link-regex '%b([-.].+)%../../build2/doc/b$1%' \
+--link-regex '%build2(#.+)?%../../build2/doc/build2-build-system-manual.xhtml$1%' \
+--output-prefix build2-project-manager- manual.cli
+
+html2ps -f doc.html2ps:a4.html2ps -o build2-project-manager-manual-a4.ps build2-project-manager-manual.xhtml
+ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true build2-project-manager-manual-a4.ps build2-project-manager-manual-a4.pdf
+
+html2ps -f doc.html2ps:letter.html2ps -o build2-project-manager-manual-letter.ps build2-project-manager-manual.xhtml
+ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true build2-project-manager-manual-letter.ps build2-project-manager-manual-letter.pdf
diff --git a/doc/code-box.css b/doc/code-box.css
new file mode 120000
index 0000000..e442993
--- /dev/null
+++ b/doc/code-box.css
@@ -0,0 +1 @@
+style/code-box.css \ No newline at end of file
diff --git a/doc/common.css b/doc/common.css
new file mode 120000
index 0000000..3ddf6fc
--- /dev/null
+++ b/doc/common.css
@@ -0,0 +1 @@
+style/common.css \ No newline at end of file
diff --git a/doc/doc-epilogue.xhtml b/doc/doc-epilogue.xhtml
new file mode 120000
index 0000000..5111ca2
--- /dev/null
+++ b/doc/doc-epilogue.xhtml
@@ -0,0 +1 @@
+style/doc-epilogue.xhtml \ No newline at end of file
diff --git a/doc/doc-prologue.xhtml b/doc/doc-prologue.xhtml
new file mode 120000
index 0000000..e1fd108
--- /dev/null
+++ b/doc/doc-prologue.xhtml
@@ -0,0 +1 @@
+style/doc-prologue.xhtml \ No newline at end of file
diff --git a/doc/doc.css b/doc/doc.css
new file mode 120000
index 0000000..6cb3fd5
--- /dev/null
+++ b/doc/doc.css
@@ -0,0 +1 @@
+style/doc.css \ No newline at end of file
diff --git a/doc/doc.html2ps b/doc/doc.html2ps
new file mode 120000
index 0000000..dc19855
--- /dev/null
+++ b/doc/doc.html2ps
@@ -0,0 +1 @@
+style/doc.html2ps \ No newline at end of file
diff --git a/doc/letter.html2ps b/doc/letter.html2ps
new file mode 120000
index 0000000..607ca58
--- /dev/null
+++ b/doc/letter.html2ps
@@ -0,0 +1 @@
+style/letter.html2ps \ No newline at end of file
diff --git a/doc/man-epilogue.1 b/doc/man-epilogue.1
new file mode 120000
index 0000000..878a9ae
--- /dev/null
+++ b/doc/man-epilogue.1
@@ -0,0 +1 @@
+style/man-epilogue.1 \ No newline at end of file
diff --git a/doc/man-epilogue.xhtml b/doc/man-epilogue.xhtml
new file mode 120000
index 0000000..6c1722a
--- /dev/null
+++ b/doc/man-epilogue.xhtml
@@ -0,0 +1 @@
+style/man-epilogue.xhtml \ No newline at end of file
diff --git a/doc/man-prologue.1 b/doc/man-prologue.1
new file mode 120000
index 0000000..08b5b4b
--- /dev/null
+++ b/doc/man-prologue.1
@@ -0,0 +1 @@
+style/man-prologue.1 \ No newline at end of file
diff --git a/doc/man-prologue.xhtml b/doc/man-prologue.xhtml
new file mode 120000
index 0000000..34997e3
--- /dev/null
+++ b/doc/man-prologue.xhtml
@@ -0,0 +1 @@
+style/man-prologue.xhtml \ No newline at end of file
diff --git a/doc/man.css b/doc/man.css
new file mode 120000
index 0000000..e0c4308
--- /dev/null
+++ b/doc/man.css
@@ -0,0 +1 @@
+style/man.css \ No newline at end of file
diff --git a/doc/pre-box.css b/doc/pre-box.css
new file mode 120000
index 0000000..b9ec76c
--- /dev/null
+++ b/doc/pre-box.css
@@ -0,0 +1 @@
+style/pre-box.css \ No newline at end of file
diff --git a/doc/toc.css b/doc/toc.css
new file mode 120000
index 0000000..477b331
--- /dev/null
+++ b/doc/toc.css
@@ -0,0 +1 @@
+style/toc.css \ No newline at end of file