Maintain cave.txt manually for now

3 files changed, 398 insertions, 2 deletions

diff --git a/.gitignore b/.gitignore
index b527f8415..1ac1260b0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -498,6 +498,7 @@ paludis-*.*.*.tar.bz2
 /src/clients/appareo/*.xml
 /src/clients/cave/cave
 /src/clients/cave/*.txt
+!/src/clients/cave/cave.txt
 /src/clients/cave/*.xml
 /src/clients/instruo/instruo
 /src/clients/instruo/*.txt
diff --git a/src/clients/cave/Makefile.am b/src/clients/cave/Makefile.am
index 0dfc9e543..b4aada099 100644
--- a/src/clients/cave/Makefile.am
+++ b/src/clients/cave/Makefile.am
@@ -86,9 +86,12 @@ man_MANS = \
 man_MANS_txts = $(man_MANS:.1=.txt)
 man_MANS_xmls = $(man_MANS_txts:.txt=.xml)
 
+command_MANS_txts = $(command_MANS:.1=.txt)
+command_MANS_xmls = $(command_MANS_txts:.txt=.xml)
+
 SUFFIXES = .1 .txt .xml
 
-$(man_MANS_txts) : man-cave
+$(command_MANS_txts) : man-cave
 	if ! env \
 	    CAVE_FORMATS_CONF="/dev/null" \
 	    CAVE_COMMANDS_PATH="" \
@@ -211,6 +214,7 @@ TESTS = \
 	continue_on_failure_TEST
 
 EXTRA_DIST = \
+	cave.txt \
 	$(man_MANS) \
 	$(TESTS) \
 	continue_on_failure_TEST_setup.sh continue_on_failure_TEST_cleanup.sh \
@@ -219,7 +223,7 @@ EXTRA_DIST = \
 DISTCLEANFILES = \
 	$(man_MANS) \
 	$(noinst_DATA) \
-	$(man_MANS_txts) \
+	$(command_MANS_txts) \
 	$(man_MANS_xmls)
 
 lib_LTLIBRARIES =
diff --git a/src/clients/cave/cave.txt b/src/clients/cave/cave.txt
new file mode 100644
index 000000000..05c64a367
--- /dev/null
+++ b/src/clients/cave/cave.txt
@@ -0,0 +1,391 @@
+cave(1)
+=======
+
+
+NAME
+----
+
+cave - A commandline client for the other package mangler.
+
+SYNOPSIS
+--------
+
+*cave [ --environment class:suffix ] [ --log-level level ] COMMAND [ARGS...]*
+
+*cave help [ --all ]*
+
+DESCRIPTION
+-----------
+The front-end to a number of commands.
+
+For the COMMAND argument, see \'cave help' for a list of common commands, or
+\'cave help --all' for all commands. To see documentation for a command named
+\'foo', use \'man cave-foo'.
+
+
+In addition to built-in commands, cave will also look in the directories named
+in the colon-separated CAVE_COMMANDS_PATH environment variable, or, if unset,
+\'/usr/libexec/cave/commands'. Any executables in this path will also be
+available as commands (with any file extension stripped); these executables
+may use the $CAVE environment variable to get access to the main cave program.
+
+
+Arguments specified after the COMMAND are handled by the individual commands.
+Arguments before the COMMAND are global arguments shared by all commands.
+
+
+OPTIONS
+-------
+Global Options
+~~~~~~~~~~~~~~
+Global options, used by every subcommand.
+
+*-E , --environment*::
+        Environment specification (class:suffix, both parts optional)
+
+*-L , --log-level*::
+        Specify the log level
+
+    *debug (d)*;;
+        Show debug output (noisy)
+
+    *qa (q)*;;
+        Show QA messages and warnings only (default)
+
+    *warning (w)*;;
+        Show warnings only
+
+    *silent (s)*;;
+        Suppress all log messages (UNSAFE)
+
+
+*-c , --colour*::
+        Specify whether to use colour
+
+    *auto (a)*;;
+        Yes if stdout is connected to a terminal (default)
+
+    *yes (y)*;;
+        Yes
+
+    *no (n)*;;
+        No
+
+
+*-h , --help*::
+        display help message
+
+*-v , --version*::
+        display version information
+
+CORE COMMANDS
+-------------
+
+config::
+Perform post-install configuration on a package. Note that most packages do
+not provide a post-install configuration script.
+
+contents::
+Display the contents of (files installed by) a given package ID.
+
+fix-linkage::
+Identifies packages with broken linkage that can be fixed by rebuilds. If
+instructed, then executes the relevant install and uninstall actions to do
+said fixing.
+
+help::
+Display help information for a particular command.
+
+import::
+Import a package from a directory containing its image. A named directory is
+treated as holding the contents to install, and a dummy package name is
+provided on the command line. Safe merge, unmerge, upgrade and replace support
+is provided, as is content tracking for installed files.
+
+info::
+Displays a formatted summary of configuration and package information, e.g.
+for use when submitting bug reports. The package names of any relevant
+packages for bug reports should be passed as parameters.
+
+owner::
+Shows package IDs owning a given file.
+
+purge::
+Uninstalls any package that is not either in \'world' or a dependency of a
+package in \'world'.
+
+report::
+Displays a formatted summary of potential problems with installed packages.
+
+resolve::
+Displays how to resolve one or more targets. If instructed, then executes the
+relevant install and uninstall actions to perform that resolution.
+
+resume::
+Resumes a failed resultion from \'cave resolve'. To enable resumes, use \'cave
+resolve --resume-file state --execute', and then if errors occur, use \'cave
+resume --resume-file state [ --retry-failed ] [ --retry-skipped ]' to try
+again.
+
+search::
+Searches for packages with particular characteristics.
+
+show::
+Displays a formatted summary of a given object. If the object is a set, the
+set's contents are listed. If the object is a repository name, information
+about the repository is displayed. If the object is a package dep spec with
+wildcards, possible expansions are shown. If the object is a package dep spec
+without wildcards, information about matching IDs are shown.
+
+sync::
+Syncs repositories. If any repository names are specified, these repositories
+are synced. Otherwise, all syncable repositories are synced.
+
+uninstall::
+Uninstalls one or more packages. Note that \'cave uninstall' simply rewrites
+the supplied dependency specifications and then uses \'cave resolve' to do the
+work; \'cave uninstall foo' is the same as \'cave resolve !foo'.
+
+SUPPLEMENTAL COMMANDS
+---------------------
+
+dump-cave-formats-conf::
+Outputs suitable contents for ~/.cave/formats.conf. This file can be used to
+customise the output format for many cave commands (although not commands
+designed for script use, such as print-*).
+
+executables::
+Display executables belonging to an ID.
+
+fix-cache::
+Fixes on-disk caches. Normally this is handled automatically when needed (e.g.
+after a sync, or when a package is installed), but a forced fix-cache is
+required after a different package manager has been used, or if a repository
+is modified without a sync.
+
+generate-metadata::
+Pregenerates metadata for a set of IDs.
+
+manage-search-index::
+Manages a search index for use by cave search. A search index is only valid
+until a package is installed or uninstalled, or a sync is performed, or
+configuration is changed.
+
+size::
+Shows the size of files installed by a package.
+
+sync-protocol-options::
+Displays options for a given sync protocol.
+
+update-world::
+Adds or removes items from the world set. This command is only for changing
+the contents of the world set; it does not install or uninstall anything.
+
+verify::
+Verify than an installed package's files haven't changed. Note that there are
+legitimate reasons for some files (such as configuration files) to have been
+changed after a merge, and that some packages may install files that are not
+directly tracked by the package manager.
+
+DEVELOPMENT COMMANDS
+--------------------
+
+digest::
+Generates a digest file for a particular package in a particular repository.
+
+mirror::
+Fetches files for a set of IDs.
+
+SCRIPTING COMMANDS
+------------------
+
+has-version::
+Returns success if there is an installed package matching a particular spec.
+Suitable for use in scripts.
+
+print-best-version::
+Prints the best installed version matching a particular spec. No formatting is
+used, making the output suitable for parsing by scripts.
+
+print-categories::
+Prints a list of known categories. No formatting is used, making the output
+suitable for parsing by scripts.
+
+print-commands::
+Prints a list of known cave commands. No formatting is used, making the output
+suitable for parsing by scripts.
+
+print-dependent-ids::
+Prints a list of installed IDs that are dependent upon another installed ID.
+No formatting is used, making the output suitable for parsing by scripts.
+
+print-environment-metadata::
+Prints environment metadata. No formatting is used, making the output suitable
+for parsing by scripts.
+
+print-id-actions::
+Prints ID actions. No formatting is used, making the output suitable for
+parsing by scripts.
+
+print-id-contents::
+Prints a list of the contents of a given ID. No formatting is used, making the
+output suitable for parsing by scripts.
+
+print-id-environment-variable::
+Prints ID environment variables. No formatting is used, making the output
+suitable for parsing by scripts.
+
+print-id-executables::
+Prints a list of executables belonging to an ID. No formating is used, making
+the script suitable for parsing by scripts.
+
+print-id-masks::
+Prints ID masks. No formatting is used, making the output suitable for parsing
+by scripts.
+
+print-id-metadata::
+Prints ID metadata. No formatting is used, making the output suitable for
+parsing by scripts.
+
+print-id-size::
+Prints the size of files installed by a package. No formatting is used, making
+the output suitable for parsing by scripts.
+
+print-ids::
+Prints a list of known IDs. No formatting is used, making the output suitable
+for parsing by scripts.
+
+print-owners::
+Prints a list of package IDs owning a given file. No formatting is used,
+making the output suitable for parsing by scripts.
+
+print-packages::
+Prints a list of package names. No formatting is used, making the output
+suitable for parsing by scripts.
+
+print-repositories::
+Prints a list of repositories. No formatting is used, making the output
+suitable for parsing by scripts.
+
+print-repository-formats::
+Prints a list of available repository formats. No formatting is used, making
+the output suitable for parsing by scripts.
+
+print-repository-metadata::
+Prints repository metadata. No formatting is used, making the output suitable
+for parsing by scripts.
+
+print-set::
+Prints the contents (packages or other sets) of a given set.
+
+print-sets::
+Prints a list of sets. No formatting is used, making the output suitable for
+parsing by scripts.
+
+print-spec::
+Parses a dependency spec and prints it out, possibly after applying certain
+modifications. No formatting is used, making the output suitable for parsing
+by scripts.
+
+print-sync-protocols::
+Prints a list of sync protocols. No formatting is used, making the output
+suitable for parsing by scripts.
+
+print-unused-distfiles::
+Prints all distfiles not used by any installed package. No formatting is used,
+making the output suitable for parsing by scripts.
+
+INTERNAL COMMANDS
+-----------------
+
+display-resolution::
+Displays a dependency resolution created using \'cave resolve'. Mostly for
+internal use; most users will not use this command directly.
+
+execute-resolution::
+Execute a dependency resolution created using \'cave resolve'. Mostly for
+internal use; most users will not use this command directly.
+
+find-candidates::
+Finds a list of candidate packages for a search. Used by \'cave search'; not
+generally called directly by end users. Note that this command will often
+select candidates that do not actually match some of the supplied
+restrictions; use \'cave match' to obtain accurate results.
+
+graph-jobs::
+Creates a Graphviz graph for jobs in a resolution created using \'cave
+resolve'. Mostly for internal use; most users will not use this command
+directly.
+
+match::
+Determines whether a particular package version has certain properties. Mostly
+for use by \'cave search'; not generally for use by end users.
+
+perform::
+Perform an action upon a package. Not suitable for direct use, although it may
+be useful in some more complex scripts.
+
+ENVIRONMENT
+-----------
+CAVE_COMMANDS_PATH::
+Colon-separated paths in which to look for additional commands.
+
+SEE ALSO
+--------
+*cave-config*(1)
+*cave-contents*(1)
+*cave-fix-linkage*(1)
+*cave-help*(1)
+*cave-import*(1)
+*cave-info*(1)
+*cave-owner*(1)
+*cave-purge*(1)
+*cave-report*(1)
+*cave-resolve*(1)
+*cave-resume*(1)
+*cave-search*(1)
+*cave-show*(1)
+*cave-sync*(1)
+*cave-uninstall*(1)
+*cave-dump-cave-formats-conf*(1)
+*cave-executables*(1)
+*cave-fix-cache*(1)
+*cave-generate-metadata*(1)
+*cave-manage-search-index*(1)
+*cave-size*(1)
+*cave-sync-protocol-options*(1)
+*cave-update-world*(1)
+*cave-verify*(1)
+*cave-digest*(1)
+*cave-mirror*(1)
+*cave-has-version*(1)
+*cave-print-best-version*(1)
+*cave-print-categories*(1)
+*cave-print-commands*(1)
+*cave-print-dependent-ids*(1)
+*cave-print-environment-metadata*(1)
+*cave-print-id-actions*(1)
+*cave-print-id-contents*(1)
+*cave-print-id-environment-variable*(1)
+*cave-print-id-executables*(1)
+*cave-print-id-masks*(1)
+*cave-print-id-metadata*(1)
+*cave-print-id-size*(1)
+*cave-print-ids*(1)
+*cave-print-owners*(1)
+*cave-print-packages*(1)
+*cave-print-repositories*(1)
+*cave-print-repository-formats*(1)
+*cave-print-repository-metadata*(1)
+*cave-print-set*(1)
+*cave-print-sets*(1)
+*cave-print-spec*(1)
+*cave-print-sync-protocols*(1)
+*cave-print-unused-distfiles*(1)
+*cave-display-resolution*(1)
+*cave-execute-resolution*(1)
+*cave-find-candidates*(1)
+*cave-graph-jobs*(1)
+*cave-match*(1)
+*cave-perform*(1)
+