From 100150a3598d931fbbee361c33374cd5b95a8d86 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Thu, 1 Mar 2018 16:37:07 +0200 Subject: Setup documentation infrastructure --- bdep/bdep.cli | 90 ++++++++++++++++++++++++++++++ bdep/common.cli | 148 +++++++++++++++++++++++++++++++++++++++++++++++++ bdep/help.cli | 30 ++++++++++ bdep/init.cli | 29 ++++++++++ doc/.gitignore | 5 ++ doc/a4.html2ps | 1 + doc/cli.sh | 83 +++++++++++++++++++++++++++ doc/code-box.css | 1 + doc/common.css | 1 + doc/doc-epilogue.xhtml | 1 + doc/doc-prologue.xhtml | 1 + doc/doc.css | 1 + doc/doc.html2ps | 1 + doc/letter.html2ps | 1 + doc/man-epilogue.1 | 1 + doc/man-epilogue.xhtml | 1 + doc/man-prologue.1 | 1 + doc/man-prologue.xhtml | 1 + doc/man.css | 1 + doc/pre-box.css | 1 + doc/toc.css | 1 + 21 files changed, 400 insertions(+) create mode 100644 bdep/bdep.cli create mode 100644 bdep/common.cli create mode 100644 bdep/help.cli create mode 100644 bdep/init.cli create mode 100644 doc/.gitignore create mode 120000 doc/a4.html2ps create mode 100755 doc/cli.sh create mode 120000 doc/code-box.css create mode 120000 doc/common.css create mode 120000 doc/doc-epilogue.xhtml create mode 120000 doc/doc-prologue.xhtml create mode 120000 doc/doc.css create mode 120000 doc/doc.html2ps create mode 120000 doc/letter.html2ps create mode 120000 doc/man-epilogue.1 create mode 120000 doc/man-epilogue.xhtml create mode 120000 doc/man-prologue.1 create mode 120000 doc/man-prologue.xhtml create mode 120000 doc/man.css create mode 120000 doc/pre-box.css create mode 120000 doc/toc.css 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 ; + +"\section=1" +"\name=bdep" +"\summary=project dependency manager" + +namespace bdep +{ + { + " ", + + "\h|SYNOPSIS| + + \cb{bdep --help}\n + \cb{bdep --version}\n + \c{\b{bdep help} [ | ]}\n + \c{\b{bdep} [] [] } + + \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 + and can be specified in any order and + can be specified as part of ." + } + + // 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 + { + "[]", + "\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 ; + +"\section=1" +"\name=bdep-common-options" +"\summary=details on common options" + +namespace bdep +{ + { + "", + + "\h|SYNOPSIS| + + \c{\b{bdep} [] ...} + + \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 + { + "", + "Set the diagnostics verbosity to 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 + { + "", + "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 + { + "", + "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. + { + "", + "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 + { + "", + "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 + { + "", + "Read additional options from . 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 ; + +"\section=1" +"\name=bdep-help" +"\summary=show help for a command or help topic" + +namespace bdep +{ + { + " ", + + "\h|SYNOPSIS| + + \c{\b{bdep help} [ | ]} + + \h|DESCRIPTION| + + Show the detailed help for or help 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 ; + +"\section=1" +"\name=bdep-init" +"\summary=@@ TODO" + +namespace bdep +{ + { + "", + + "\h|SYNOPSIS| + + \c{\b{bdep init} [] @@ 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 -- cgit v1.1