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 +++++++++++ 4 files changed, 297 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 (limited to 'bdep') 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|" + }; +} -- cgit v1.1