From 1c13ae4ed5d84b32c2c1a0698f9e688c312de989 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Mon, 11 Jan 2016 15:14:32 +0200 Subject: Documentation improvements --- bpkg/bpkg.cli | 58 ++++++++++++++++++++++++++++++-------------------- bpkg/bpkg.cxx | 4 ++-- bpkg/cfg-add.cli | 26 +++++++++++----------- bpkg/cfg-create.cli | 9 ++++---- bpkg/cfg-create.cxx | 3 +++ bpkg/cfg-fetch.cli | 26 ++++++++++++---------- bpkg/common.cli | 14 ++++++------ bpkg/help.cli | 18 ++++++++++++---- bpkg/pkg-build.cli | 29 ++++++++++++++----------- bpkg/pkg-clean.cli | 23 +++++++++++--------- bpkg/pkg-configure.cli | 28 +++++++++++++----------- bpkg/pkg-disfigure.cli | 22 +++++++++++-------- bpkg/pkg-drop.cli | 47 ++++++++++++++++++++++------------------ bpkg/pkg-fetch.cli | 46 +++++++++++++++++++++------------------ bpkg/pkg-install.cli | 2 +- bpkg/pkg-purge.cli | 45 +++++++++++++++++++++------------------ bpkg/pkg-status.cli | 53 ++++++++++++++++++++++++--------------------- bpkg/pkg-uninstall.cli | 4 ++-- bpkg/pkg-unpack.cli | 47 +++++++++++++++++++++------------------- bpkg/pkg-update.cli | 23 +++++++++++--------- bpkg/pkg-verify.cli | 36 ++++++++++++++++++------------- bpkg/rep-create.cli | 25 +++++++++++++++------- bpkg/rep-info.cli | 44 +++++++++++++++++++++----------------- 23 files changed, 359 insertions(+), 273 deletions(-) diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli index e9611ff..cf0125e 100644 --- a/bpkg/bpkg.cli +++ b/bpkg/bpkg.cli @@ -17,125 +17,137 @@ namespace bpkg \cb{bpkg --help}\n \cb{bpkg --version}\n - \c{\b{bpkg help} [|]}\n + \c{\b{bpkg help} [ | ]}\n \c{\b{bpkg} [] [] } \h|DESCRIPTION| - @@ TODO + @@ TODO Is this a good place to describe some general concepts, like + configuration, repositories, packages? + + The example workflow would be: Note that the common options can also be specified as part of the - command-specific options." + command-specific options. + + 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{bpkg-} prefix, for example \l{bpkg-help(1)})." } 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 { "[]", - "Show help for a command or help topic \- \l{bpkg-help(1)}.", + "\l{bpkg-help(1)} \- show help for a command or help topic", "" } bool cfg-create|create { "", - "Create configuration.", + "\l{bpkg-cfg-create(1)} \- create configuration", "" } bool cfg-add|add { "", - "Add repository to configuration.", + "\l{bpkg-cfg-add(1)} \- add repository to configuration", "" } bool cfg-fetch|fetch { - "Fetch list of available packages." + "\l{bpkg-cfg-fetch(1)} \- fetch list of available packages" } bool pkg-status|status { - "Print package status." + "\l{bpkg-pkg-status(1)} \- print package status" } bool pkg-build|build { - "Build package \- \l{bpkg-pkg-build(1)}." + "\l{bpkg-pkg-build(1)} \- build package" } bool pkg-drop|drop { - "Drop package." + "\l{bpkg-pkg-drop(1)} \- drop package" } bool pkg-install|install { - "Install package." + "\l{bpkg-pkg-install(1)} \- install package" } bool pkg-uninstall|uninstall { - "Uninstall package." + "\l{bpkg-pkg-uninstall(1)} \- uninstall package" } bool pkg-update|update { - "Update package." + "\l{bpkg-pkg-update(1)} \- update package" } bool pkg-clean|clean { - "Clean package." + "\l{bpkg-pkg-clean(1)} \- clean package" } bool pkg-verify { "", - "Verify archive is a valid package.", + "\l{bpkg-pkg-verify(1)} \- verify package archive", "" } bool pkg-fetch { "/", - "Fetch package archive.", + "\l{bpkg-pkg-fetch(1)} \- fetch package archive", "" } bool pkg-unpack { - "Unpack package archive." + "\l{bpkg-pkg-unpack(1)} \- unpack package archive" } bool pkg-configure { - "Configure package." + "\l{bpkg-pkg-configure(1)} \- configure package" } bool pkg-disfigure { - "Disfigure package." + "\l{bpkg-pkg-disfigure(1)} \- disfigure package" } bool pkg-purge { - "Purge package." + "\l{bpkg-pkg-purge(1)} \- purge package" } bool rep-info { - "Print information about repository." + "\l{bpkg-rep-info(1)} \- print repository information" } bool rep-create { "[]", - "Generate repository packages manifest.", + "\l{bpkg-rep-create(1)} \- create repository", "" } }; @@ -148,7 +160,7 @@ namespace bpkg bool common-options { - "Details on common options \- \l{bpkg-common-options(1)}." + "\l{bpkg-common-options(1)} \- details on common options" } }; diff --git a/bpkg/bpkg.cxx b/bpkg/bpkg.cxx index 182471c..dc318ed 100644 --- a/bpkg/bpkg.cxx +++ b/bpkg/bpkg.cxx @@ -146,7 +146,7 @@ try if (cmd.help ()) { assert (h); - r = help (ho, "help", help_options::print_usage); + r = help (ho, "help", print_bpkg_help_usage); break; } @@ -155,7 +155,7 @@ try // if (cmd.pkg_verify ()) // { // if (h) - // r = help (ho, "pkg-verify", pkg_verify_options::print_usage); + // r = help (ho, "pkg-verify", print_bpkg_pkg_verify_usage); // else // r = pkg_verify (parse (co, args), args); // diff --git a/bpkg/cfg-add.cli b/bpkg/cfg-add.cli index 34909e9..8bc17c3 100644 --- a/bpkg/cfg-add.cli +++ b/bpkg/cfg-add.cli @@ -8,23 +8,25 @@ include ; "\name=bpkg-cfg-add" "\summary=add repository to configuration" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + " ", -bpkg cfg-add [] " + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg cfg-add}|\b{add} [] } -The \cb{cfg-add} command adds the specified source repository to the -configuration. Note that this command doesn't fetch the available -packages list for the newly added repository. To do that, use the -\cb{cfg-fetch} command. -" -*/ + \h|DESCRIPTION| + + The \cb{cfg-add} command adds the specified package repository to the + configuration. Note that it doesn't fetch the list of available packages + for the newly added repository. For that, use the \l{bpkg-cfg-fetch(1)} + command, normally, after adding all the repositories you wish to use." + } -namespace bpkg -{ class cfg_add_options: configuration_options { + "\h|CFG-ADD OPTIONS|" }; } diff --git a/bpkg/cfg-create.cli b/bpkg/cfg-create.cli index e28778e..2f6070d 100644 --- a/bpkg/cfg-create.cli +++ b/bpkg/cfg-create.cli @@ -15,7 +15,7 @@ namespace bpkg "\h|SYNOPSIS| - \c{\b{bpkg cfg-create} [] [( | )...]} + \c{\b{bpkg cfg-create}|\b{create} [] [( | )...]} \h|DESCRIPTION| @@ -25,7 +25,7 @@ namespace bpkg configuration directory to be empty or to not exist (in which case it will be created). - By default the resulting configuration loads the \cb{config}, \cb{test}, + By default, the resulting configuration loads the \cb{config}, \cb{test}, and \cb{install} modules. However, additional modules and, if required, their configuration variables can be specified as the \cb{cfg-create} arguments. For example: @@ -43,14 +43,15 @@ namespace bpkg dir_path --directory|-d (".") { "", - "Create configuration in rather than in the current working + "Create the configuration in rather than in the current working directory." } bool --wipe { "Wipe the configuration directory clean before creating the new - configuration." + configuration. For safety, this option requires that you specify the + configuration directory explicitly with \cb{--directory|-d}." } }; } diff --git a/bpkg/cfg-create.cxx b/bpkg/cfg-create.cxx index 624edb2..62b39d8 100644 --- a/bpkg/cfg-create.cxx +++ b/bpkg/cfg-create.cxx @@ -23,6 +23,9 @@ namespace bpkg { tracer trace ("cfg_create"); + if (o.wipe () && !o.directory_specified ()) + fail << "--wipe requires explicit --directory|-d"; + dir_path c (o.directory ()); level4 ([&]{trace << "creating configuration in " << c;}); diff --git a/bpkg/cfg-fetch.cli b/bpkg/cfg-fetch.cli index 6b889cc..9cc75fd 100644 --- a/bpkg/cfg-fetch.cli +++ b/bpkg/cfg-fetch.cli @@ -6,23 +6,27 @@ include ; "\section=1" "\name=bpkg-cfg-fetch" -"\summary=fetch available packages list" +"\summary=fetch list of available packages" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + "", -bpkg cfg-fetch []" + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg cfg-fetch}|\b{fetch} []} -The \cb{cfg-fetch} command recursively fetches the prerequisite repository -and available package lists for all the repositories that were added -(\cb{cfg-add}) to the configuration." -*/ + \h|DESCRIPTION| + + The \cb{cfg-fetch} command fetches the list of available packages for all + the repositories that were previously added with the \l{bpkg-cfg-add(1)} + command as well as all their complement and prerequisite repositories, + recursively." + } -namespace bpkg -{ class cfg_fetch_options: configuration_options { + "\h|CFG-FETCH OPTIONS|" }; } diff --git a/bpkg/common.cli b/bpkg/common.cli index 17ee1a6..92c3748 100644 --- a/bpkg/common.cli +++ b/bpkg/common.cli @@ -6,7 +6,7 @@ include ; "\section=1" "\name=bpkg-common-options" -"\summary=options common for all commands" +"\summary=details on common options" namespace bpkg { @@ -19,8 +19,9 @@ namespace bpkg \h|DESCRIPTION| - The common options can be specified either before the command or after, - togethere with the command-specific options." + The common options control behavior that is common to all or most of the + \cb{bpkg} commands. They can be specified either before the command or + after, together with the command-specific options." } class common_options = 0 @@ -32,8 +33,7 @@ namespace bpkg { "", "The common options are summarized below with a more detailed description - available as the \l{bpkg-common-options(1) \cb{common-options}} help - topic.", + available in \l{bpkg-common-options(1)}.", "" } @@ -61,9 +61,9 @@ namespace bpkg \li|high-level information messages| - \li|essential underlying commands that are being executed| + \li|essential underlying commands being executed| - \li|all underlying commands that are being executed| + \li|all underlying commands being executed| \li|information that could be helpful to the user| diff --git a/bpkg/help.cli b/bpkg/help.cli index 69e818c..f50841e 100644 --- a/bpkg/help.cli +++ b/bpkg/help.cli @@ -10,11 +10,21 @@ include ; namespace bpkg { - class help_options: common_options { - /* - "Show detailed help for a command or help topic or the list of + " ", + + "\h|SYNOPSIS| + + \c{\b{bpkg 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/bpkg/pkg-build.cli b/bpkg/pkg-build.cli index 54e0252..aa16f58 100644 --- a/bpkg/pkg-build.cli +++ b/bpkg/pkg-build.cli @@ -6,7 +6,7 @@ include ; "\section=1" "\name=bpkg-pkg-build" -"\summary=build one or more packages" +"\summary=build package" namespace bpkg { @@ -15,19 +15,22 @@ namespace bpkg "\h|SYNOPSIS| - \c{\b{bpkg pkg-build} [] ([/] | | )...} + \c{\b{bpkg pkg-build}|\b{build} [] ([/] | | )...} \h|DESCRIPTION| The \cb{pkg-build} command builds one or more packages including all their prerequisites. Each package can be specified as just the name () with optional package version () in which case the package will be - automatically fetched from one of the configuration's source repositories - (see the \cb{cfg-add} and \cb{cfg-fetch} commands). Alternatively, the - package can be specified as either the path to the package source archive - () or package source directory (). See the \cb{pkg-fetch} and - \cb{pkg-unpack} commands for more information on the semantics of - specifying the package as an archive or directory. + automatically fetched from one of the repositories. See the + \l{bpkg-cfg-add(1)} and \l{bpkg-cfg-fetch(1)} commands for more + information on package repositories. + + Alternatively, the package can be specified as either the path to the + package archive () or to the package directory (). See the + \l{bpkg-pkg-fetch(1)} and \l{bpkg-pkg-unpack(1)} commands for more + information on the semantics of specifying the package as an archive or + a directory. Packages that are specified explicitly on the command line will be \i{held}, that is, they will not be considered for automatic removal if @@ -49,15 +52,15 @@ namespace bpkg "Assume the answer to all prompts is \cb{yes}." } - bool --configure-only|-c - { - "Configure all the packages but don't update." - } - bool --print-only|-p { "Print to \cb{STDOUT} what would be done without actually doing anything." } + + bool --configure-only|-c + { + "Configure all the packages but don't update." + } }; } diff --git a/bpkg/pkg-clean.cli b/bpkg/pkg-clean.cli index 9452291..ffad75a 100644 --- a/bpkg/pkg-clean.cli +++ b/bpkg/pkg-clean.cli @@ -8,21 +8,24 @@ include ; "\name=bpkg-pkg-clean" "\summary=clean package" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + " ", -bpkg pkg-clean ..." + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg pkg-clean}|\b{clean} [] ...} -The \cb{pkg-clean} command cleans the previously configured -(\cb{pkg-configure}) package. Underneath, this command doesn't -do much more than run (\cb{b clean})." -*/ + \h|DESCRIPTION| + + The \cb{pkg-clean} command cleans the previously configured + (via \l{bpkg-pkg-build(1)} or \l{bpkg-pkg-configure(1)}) package. + Underneath, this command doesn't do much more than run \cb{b clean}." + } -namespace bpkg -{ class pkg_clean_options: configuration_options { + "\h|PKG-CLEAN OPTIONS|" }; } diff --git a/bpkg/pkg-configure.cli b/bpkg/pkg-configure.cli index 4ef9707..274a3c3 100644 --- a/bpkg/pkg-configure.cli +++ b/bpkg/pkg-configure.cli @@ -8,24 +8,26 @@ include ; "\name=bpkg-pkg-configure" "\summary=configure package" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + " ", -bpkg pkg-configure []" + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg pkg-configure} [] [...]} -The \cb{pkg-configure} command configures the output directory for -the previously unpacked (\cb{pkg-unpack}) package. The package -inherits the common \cb{build2} configuration values that were -specified when creating the \cb{bpkg} configuration (\cb{cfg-create}). -Additional, package-specific configuration variables can be specified -after the package name." -*/ + \h|DESCRIPTION| + + The \cb{pkg-configure} command configures the previously unpacked + (\l{bpkg-pkg-unpack(1)}) package. The package inherits the common + \cb{build2} configuration values that were specified when creating the + configuration (\l{bpkg-cfg-create(1)}). Additional, package-specific + configuration variables can be specified after the package name." + } -namespace bpkg -{ class pkg_configure_options: configuration_options { + "\h|PKG-CONFIGURE OPTIONS|" }; } diff --git a/bpkg/pkg-disfigure.cli b/bpkg/pkg-disfigure.cli index 6f5c80b..51ab956 100644 --- a/bpkg/pkg-disfigure.cli +++ b/bpkg/pkg-disfigure.cli @@ -8,20 +8,24 @@ include ; "\name=bpkg-pkg-disfigure" "\summary=disfigure package" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + "", -bpkg pkg-disfigure []" + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg pkg-disfigure} [] } -The \cb{pkg-disfigure} command disfigures the previously configured -(\cb{pkg-configure}) package and returns it to the \cb{unpacked} state." -*/ + \h|DESCRIPTION| + + The \cb{pkg-disfigure} command disfigures the previously configured + (via \l{bpkg-pkg-build(1)} or \l{bpkg-pkg-configure(1)}) package and + returns it to the \cb{unpacked} state." + } -namespace bpkg -{ class pkg_disfigure_options: configuration_options { + "\h|PKG-DISFIGURE OPTIONS|" }; } diff --git a/bpkg/pkg-drop.cli b/bpkg/pkg-drop.cli index 6ec7130..7737d15 100644 --- a/bpkg/pkg-drop.cli +++ b/bpkg/pkg-drop.cli @@ -6,29 +6,34 @@ include ; "\section=1" "\name=bpkg-pkg-drop" -"\summary=drop one or more packages" +"\summary=drop package" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + "", -bpkg pkg-drop [] ..." + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg pkg-drop}|\b{drop} [] ...} -The \cb{pkg-drop} command drops one or more packages from the configuration. -If the packages being dropped still have dependents, then those will have -to be drop as well and you will be prompted for a confirmation. Similarly, -if the packages being dropped have prerequisites that are no longer needed, -you will be offered to drop those as well. + \h|DESCRIPTION| -The \cb{pkg-drop} command also supports several \cb{--*-only} options that -allow you to limit the amount of work that will be done. -*/ + The \cb{pkg-drop} command drops one or more packages from the + configuration. If the packages being dropped still have dependent + packages, then those will have to be drop as well and you will be prompted + to confirm. Similarly, if the packages being dropped have prerequisite + packages that would otherwise no longer be needed, you will be offered to + drop those as well. + + The \cb{pkg-drop} command also supports several \cb{--*-only} options that + allow you to limit the amount of work that will be done." + } -namespace bpkg -{ class pkg_drop_options: configuration_options { + "\h|PKG-DROP OPTIONS|" + bool --yes|-y { "Assume the answer to all prompts is \cb{yes}. Note that this option @@ -44,19 +49,19 @@ namespace bpkg bool --drop-dependent { - "Don't warn about or ask for confirmation of dropping dependent + "Don't warn about or ask for confirmation if dropping dependent packages." } - bool --disfigure-only - { - "Disfigure all the packages but don't purge." - } - bool --print-only|-p { "Print to \cb{STDOUT} what would be done without actually doing anything." } + + bool --disfigure-only + { + "Disfigure all the packages but don't purge." + } }; } diff --git a/bpkg/pkg-fetch.cli b/bpkg/pkg-fetch.cli index ba1d5d9..562daab 100644 --- a/bpkg/pkg-fetch.cli +++ b/bpkg/pkg-fetch.cli @@ -8,33 +8,37 @@ include ; "\name=bpkg-pkg-fetch" "\summary=fetch package archive" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + " ", -bpkg pkg-fetch [] (/)|(-e )" + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg pkg-fetch} [] (/) | (-e )} -The \cb{pkg-fetch} command fetches the archive for the specified package -name and version from one of the configuration's repositories. If the -\cb{-r|--replace} option is specified, then \cb{pkg-fetch} will replace the -archive of a package that is already in the \cb{fetched} or \cb{unpacked} -state. Otherwise, \cb{pkg-fetch} expects the package to not exist in the -configuration's database. + \h|DESCRIPTION| -If the \cb{-e|--existing} option is used, then instead of the name and -version argument, \cb{pkg-fetch} expects a local path to the existing -package archive. In this case, \cb{bpkg} will use the archive in place, -without copying it to the configuration or package cache directories. -Also, unless the \cb{-p|--purge} option is specified, \cb{bpkg} will -not attempt to remove the archive when the package is purged with the -\cb{pkg-purge} command." -*/ + The \cb{pkg-fetch} command fetches the archive for the specified package + name and version from one of the repositories (\l{bpkg-cfg-add(1)}). If + the \cb{--replace|-r} option is specified, then \cb{pkg-fetch} will + replace the archive of a package that is already in the \cb{fetched} or + \cb{unpacked} state (\l{bpkg-pkg-status(1)}). Otherwise, \cb{pkg-fetch} + expects the package to not exist in the configuration. + + If the \cb{--existing|-e} option is used, then instead of the name and + version arguments, \cb{pkg-fetch} expects a local path to an existing + package archive. In this case, \cb{bpkg} will use the archive in place, + without copying it to the configuration or package cache directories. + Also, unless the \cb{--purge|-p} option is specified, \cb{bpkg} will not + attempt to remove this archive when the package is later purged with the + \l{bpkg-pkg-purge(1)} command." + } -namespace bpkg -{ class pkg_fetch_options: configuration_options { + "\h|PKG-FETCH OPTIONS|" + bool --replace|-r { "Replace the archive if the package is already fetched or unpacked." @@ -43,7 +47,7 @@ namespace bpkg bool --existing|-e { "Treat the argument as an existing package archive path rather than - package name/version to fetch." + the package name/version to fetch." } bool --purge|-p diff --git a/bpkg/pkg-install.cli b/bpkg/pkg-install.cli index 0c1385b..3c700a0 100644 --- a/bpkg/pkg-install.cli +++ b/bpkg/pkg-install.cli @@ -15,7 +15,7 @@ namespace bpkg "\h|SYNOPSIS| - \c{\b{bpkg pkg-install} [] ...} + \c{\b{bpkg pkg-install}|\b{install} [] ...} \h|DESCRIPTION| diff --git a/bpkg/pkg-purge.cli b/bpkg/pkg-purge.cli index da618d3..490f316 100644 --- a/bpkg/pkg-purge.cli +++ b/bpkg/pkg-purge.cli @@ -8,39 +8,42 @@ include ; "\name=bpkg-pkg-purge" "\summary=purge package" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + " ", -bpkg pkg-purge [] " + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg pkg-purge} [] } -The \cb{pkg-purge} command removes the package directory and archive -from the filesystem and removes the package from the configuration's -database. Only packages in the \cb{fetched} and \cb{unpacked} state can -be purged plus \cb{broken} packages if the \cb{-f|--force} options is -specified (see this option's description for details on purging broken -packages). If the \cb{-k|--keep} option is specified, then the package -archive is not removed (see this option's description for details on -this mode)." -*/ + \h|DESCRIPTION| + + The \cb{pkg-purge} command removes the package directory and archive from + the filesystem and removes the package from the configuration. Only + packages in the \cb{fetched} and \cb{unpacked} state + (\l{bpkg-pkg-status(1)}) can be purged plus \cb{broken} packages if the + \cb{--force|-f} option is specified (see the option's description for + details on purging broken packages). If the \cb{--keep|-k} option is + specified, then the package archive is not removed (see the option's + description for details on this mode)." + } -namespace bpkg -{ class pkg_purge_options: configuration_options { + "\h|PKG-PURGE OPTIONS|" + bool --keep|-k { - "Keep the package archive. Note that in this mode the package is - still retained in the configuration's database in the \cb{fetched} - state." + "Keep the package archive. Note that in this mode the package is still + retained in the configuration's database in the \cb{fetched} state." } bool --force|-f { - "Purge a broken package. In this mode \cb{bpkg} will verify that - the package directory and archive no longer exist and will remove - the package from the configuration's database." + "Purge a broken package. In this mode \cb{bpkg} will verify that the + package directory and archive no longer exist and then remove the + package from the configuration." } }; } diff --git a/bpkg/pkg-status.cli b/bpkg/pkg-status.cli index fb20f78..87ff442 100644 --- a/bpkg/pkg-status.cli +++ b/bpkg/pkg-status.cli @@ -15,7 +15,7 @@ namespace bpkg "\h|SYNOPSIS| - \c{\b{bpkg pkg-status} [] [/]} + \c{\b{bpkg pkg-status}|\b{status} [] [/]} \h|DESCRIPTION| @@ -23,19 +23,19 @@ namespace bpkg if is specified, package version. Note that the status is written to \cb{STDOUT}, not \cb{STDERR}. - The status format is regular. First always comes one of the following - status words: + The status output format is regular. First always comes one of the + following status words: \dl| \li|\cb{unknown} - package is not part of the configuration nor available in one of the + package is not part of the configuration nor available from any of the repositories| \li|\cb{available} - package is not part of the configuration but is available in one of + package is not part of the configuration but is available from one of the repositories| \li|\cb{fetched} @@ -48,7 +48,12 @@ namespace bpkg \li|\cb{configured} - package is part of the configuration and is configured|| + package is part of the configuration and is configured| + + \li|\cb{broken} + + package is part of the configuration and is broken (broken packages + can only be purged; see \l{bpkg-pkg-purge(1)})|| If only the package name was specified without the package version, then @@ -56,47 +61,47 @@ namespace bpkg versions. Similarly, if only the package name was specified, then the \cb{fetched}, - \cb{unpacked}, and \cb{configured} status words are followed by the - version of the package. After the possible package version, these status + \cb{unpacked}, \cb{configured}, and \cb{broken} status words are followed + by the version of the package. After the package version, these status words may be followed by one or more sub-status words. Currently, these - can be \cb{hold_package} (package should not be automatically dropped) - and \cb{hold_version} (package should not be automatically upgraded). - Finally, if only the package name was specified and newer versions are - available in the repositories, then the sub-status words are followed + can be \cb{hold_package} (package should not be automatically dropped) and + \cb{hold_version} (package should not be automatically upgraded). Finally, + if only the package name was specified and newer versions are available + from some of the repositories, then the sub-status word is followed by '\cb{;}', the \cb{available} status word, and the list of newer versions. - Below are some examples, assuming the configuration has libfoo 1.0.0 - configured and held as well as libfoo 1.1.0 and 1.1.1 available from a - repository. + Below are some examples, assuming the configuration has \cb{libfoo} + \cb{1.0.0} configured and held as well as \cb{libfoo} \cb{1.1.0} and + \cb{1.1.1} available from a repository. \ - bpkg pkg-status libbar + bpkg status libbar unknown - bpkg pkg-status libbar/1.0.0 + bpkg status libbar/1.0.0 unknown - bpkg pkg-status libfoo/1.0.0 + bpkg status libfoo/1.0.0 configured hold_package - bpkg pkg-status libfoo/1.1.0 + bpkg status libfoo/1.1.0 available - bpkg pkg-status libfoo + bpkg status libfoo configured 1.0.0 hold_package; available 1.1.0 1.1.1 \ - Assuming now that we dropped libfoo from the configuration: + Assuming now that we dropped \cb{libfoo} from the configuration: \ - bpkg pkg-status libfoo/1.0.0 + bpkg status libfoo/1.0.0 unknown - bpkg pkg-status libfoo/1.1.0 + bpkg status libfoo/1.1.0 available - bpkg pkg-status libfoo + bpkg status libfoo available 1.1.0 1.1.1 \ " diff --git a/bpkg/pkg-uninstall.cli b/bpkg/pkg-uninstall.cli index 536f6ec..89f9dc0 100644 --- a/bpkg/pkg-uninstall.cli +++ b/bpkg/pkg-uninstall.cli @@ -15,12 +15,12 @@ namespace bpkg "\h|SYNOPSIS| - \c{\b{bpkg pkg-uninstall} [] ...} + \c{\b{bpkg pkg-uninstall}|\b{uninstall} [] ...} \h|DESCRIPTION| The \cb{pkg-uninstall} command uninstalls one or more packages that were - previously installed with \l{bpkg-cfg-install(1)}. Underneath, this + previously installed with \l{bpkg-pkg-install(1)}. Underneath, this command doesn't do much more than run \cb{b uninstall}." } diff --git a/bpkg/pkg-unpack.cli b/bpkg/pkg-unpack.cli index 847ecb2..67f37b7 100644 --- a/bpkg/pkg-unpack.cli +++ b/bpkg/pkg-unpack.cli @@ -8,37 +8,40 @@ include ; "\name=bpkg-pkg-unpack" "\summary=unpack package archive" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + " ", -bpkg pkg-unpack [] |(-e )" + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg pkg-unpack} [] | (-e )} -The \cb{pkg-unpack} command unpacks the archive for the previously -fetched (\cb{pkg-fetch}) package. If the \cb{-e|--existing} option -is used, then instead of the package name, \cb{pkg-unpack} expects -a local path to the existing package source directory. In this case, -\cb{bpkg} will use the directory in place, without copying it to the -configuration or package cache directories. Also, unless the -\cb{-p|--purge} option is specified, \cb{bpkg} will not attempt to -remove this directory when the package is purged with the \cb{pkg-purge} -command. + \h|DESCRIPTION| -If \cb{-e|--existing} is specified together with the \cb{-r|--replace} -option, then \cb{pkg-unpack} will replace the archive and/or source -directory of a package that is already in the \cb{unpacked} or -\cb{fetched} state." -*/ + The \cb{pkg-unpack} command unpacks the archive for the previously fetched + (\l{bpkg-pkg-fetch(1)}) package. If the \cb{--existing|-e} option is used, + then instead of the package name, \cb{pkg-unpack} expects a local path to + an existing package directory. In this case, \cb{bpkg} will use the + directory in place, without copying it to the configuration or package + cache directories. Also, unless the \cb{--purge|-p} option is specified, + \cb{bpkg} will not attempt to remove this directory when the package is + later purged with the \l{bpkg-pkg-purge(1)} command. + + If \cb{--existing|-e} is specified together with the \cb{--replace|-r} + option, then \cb{pkg-unpack} will replace the archive and/or source + directory of a package that is already in the \cb{unpacked} or + \cb{fetched} state (\l{bpkg-pkg-status(1)})." + } -namespace bpkg -{ class pkg_unpack_options: configuration_options { + "\h|PKG-UNPACK OPTIONS|" + bool --existing|-e { "Treat the argument as an existing package directory path rather than - package name to unpack." + the package name to unpack." } bool --purge|-p @@ -49,7 +52,7 @@ namespace bpkg bool --replace|-r { "Replace the source directory if the package is already unpacked or - fetched. Can only be specified together with \cb{-e|--existing}." + fetched. Can only be specified together with \cb{--existing|-e}." } }; } diff --git a/bpkg/pkg-update.cli b/bpkg/pkg-update.cli index 09a5f59..cce17b0 100644 --- a/bpkg/pkg-update.cli +++ b/bpkg/pkg-update.cli @@ -8,21 +8,24 @@ include ; "\name=bpkg-pkg-update" "\summary=update package" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + " ", -bpkg pkg-update ..." + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg pkg-update}|\b{update} [] ...} -The \cb{pkg-update} command updates the previously configured -(\cb{pkg-configure}) package. Underneath, this command doesn't -do much more than run (\cb{b update})." -*/ + \h|DESCRIPTION| + + The \cb{pkg-update} command updates the previously configured + (via \l{bpkg-pkg-build(1)} or \l{bpkg-pkg-configure(1)}) package. + Underneath, this command doesn't do much more than run \cb{b update}." + } -namespace bpkg -{ class pkg_update_options: configuration_options { + "\h|PKG-UPDATE OPTIONS|" }; } diff --git a/bpkg/pkg-verify.cli b/bpkg/pkg-verify.cli index 850b7d4..534b98e 100644 --- a/bpkg/pkg-verify.cli +++ b/bpkg/pkg-verify.cli @@ -6,35 +6,41 @@ include ; "\section=1" "\name=bpkg-pkg-verify" -"\summary=verify archive is a valid package" +"\summary=verify package archive" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + " ", -bpkg pkg-verify " + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg pkg-verify} [] } -The \cb{pkg-verify} command verifies that the specified archive is a -valid \cb{bpkg} package. Specifically, it checks that the archive -contains a valid manifest file and that both the archive's name -and its top-level directory match the canonical - -form." -*/ + \h|DESCRIPTION| + + The \cb{pkg-verify} command verifies that the specified archive is a + valid \cb{bpkg} package. Specifically, it checks that the archive's name + and the top-level directory inside the archive match the canonical + '\c{\i{name}\b{-}\i{version}}' form and that there is a valid manifest + file in that top-level directory." + } -namespace bpkg -{ class pkg_verify_options: common_options { + "\h|PKG-VERIFY OPTIONS|" + bool --silent { - "Suppress error messages about the reason why the package is + "Suppress the error messages about the reason why the package is invalid. Just return the error status." } bool --ignore-unknown { - "Ignore unknown manifest entries." + "Ignore unknown manifest entries. By default, \cb{bpkg} will refuse to + declare such a package validate since it cannot be sure the unknown + entries are valid." } }; } diff --git a/bpkg/rep-create.cli b/bpkg/rep-create.cli index b472cfc..fc11a0c 100644 --- a/bpkg/rep-create.cli +++ b/bpkg/rep-create.cli @@ -6,19 +6,28 @@ include ; "\section=1" "\name=bpkg-rep-create" -"\summary=create repository manifest file" +"\summary=create repository" namespace bpkg { - class rep_create_options: common_options { - /* - "Create repository manifest file (\cb{packages}) based on the - packages present in the repository directory." + " ", + + "\h|SYNOPSIS| + + \c{\b{bpkg rep-create} [] []} + + \h|DESCRIPTION| - "Use as the repository root directory instead of the - current working directory." - */ + The \cb{rep-create} command regenerates the \cb{packages} manifest file + based on the files present in the repository directory. If is not + specified, then the current working directory is used as the repository + root." + } + + class rep_create_options: common_options + { + "\h|REP-CREATE OPTIONS|" bool --ignore-unknown { diff --git a/bpkg/rep-info.cli b/bpkg/rep-info.cli index 0db3004..7554620 100644 --- a/bpkg/rep-info.cli +++ b/bpkg/rep-info.cli @@ -6,27 +6,31 @@ include ; "\section=1" "\name=bpkg-rep-info" -"\summary=print information about repository" +"\summary=print repository information" -/* -"\h{SYNOPSIS} +namespace bpkg +{ + { + " ", -bpkg rep-info [] " + "\h|SYNOPSIS| -"\h{DESCRIPTION} + \c{\b{bpkg rep-info} [] } -The \cb{rep-info} command prints information about the specified repository. -By default it print the repository's name and location as the first line -followed by the list of prerequisite/complement repositories and the list -of available packages. This default behavior, however, can be altered in -various ways using options listed below. Note that the information is -written to \cb{STDOUT}, not \cb{STDERR}." -*/ + \h|DESCRIPTION| + + The \cb{rep-info} command prints various information about the specified + repository. By default it print the repository's name and location as the + first line followed by the list of complement and prerequisite + repositories and the list of available packages. This default behavior, + however, can be altered in various ways using options listed below. Note + that the information is written to \cb{STDOUT}, not \cb{STDERR}." + } -namespace bpkg -{ class rep_info_options: common_options { + "\h|REP-INFO OPTIONS|" + bool --name|-n { "Print the specified repository's name and location." @@ -34,20 +38,20 @@ namespace bpkg bool --repositories|-r { - "Print information about prerequisite/complement repositories." + "Print the list of complement and prerequisite repositories." } bool --packages|-p { - "Print information about available packages." + "Print the list of available packages." } bool --manifest|-m { - "Instead of printing the information in the human-readable form, dump - it as manifest(s). Normally you would use this option in combination - with \cb{--packages|-p} or \cb{--repositories|-r} to only dump one - of the manifests." + "Instead of printing the information in the human-readable form, dump it + as manifest(s). Normally you would use this option in combination with + \cb{--packages|-p} or \cb{--repositories|-r} to only dump one of the + manifests." } }; } -- cgit v1.1