man pages: make more friendly for help generation

Also few minor fixups added.

12 files changed, 132 insertions, 74 deletions

diff --git a/doc/apk-add.8.scd b/doc/apk-add.8.scd
index 7959a99..8e0ec0f 100644
--- a/doc/apk-add.8.scd
+++ b/doc/apk-add.8.scd
@@ -13,6 +13,12 @@ apk add - add packages to _world_ and commit changes
 *apk add* adds the requested packages to _world_ and installs (or upgrades)
 them if not already present, ensuring all dependencies are met.
 
+To upgrade individual packages without modifying _world_ use *apk-fix*(8).
+
+By default *apk* tries to select a set of packages so that all dependencies
+are satisfied. This means that some packages can be held back in an older
+version if there is direct or implicit dependencies to the older version.
+
 # OPTIONS
 
 *apk add* supports the commit options described in *apk*(8), as well as the
@@ -22,22 +28,25 @@ following options:
 	Initialize a new package database.
 
 *-l, --latest*
-	Disables normal heuristics for choosing which repository to install a
-	package from, preferring only repositories from which the latest
-	version is available. This has no effect on pinned packages.
+	Always choose the latest package by version. However, the versions
+	considered are based on the package pinning. Primarily this overrides
+	the default heuristic and will cause an error to displayed if all
+	dependencies cannot be satisfied.
 
 *-u, --upgrade*
-	When adding packages which are already installed, upgrade them rather
-	than considering the requirement fulfilled by the current installation.
+	Upgrade _packages_ and it's dependencies. Normally *apk add* will
+	avoid changing installed package unless it is required by the newly
+	added _packages_ or their dependencies. This changes the default
+	preference to upgrading the package to the latest installable version.
 
 *-t, --virtual* _NAME_
-	Instead of adding the specified packages to _world_, create a new
-	virtual package with the listed packages as its dependencies, then add
-	that package to _world_.
+	Create virtual package _NAME_ with given dependencies. This new package
+	will get the _packages_ as dependencies instead of _world_. Finally the
+	_NAME_ is added to _world_.
 
-	The packages requested are added as transitive dependencies of the
-	virtual package, and by deleting that package the *apk add* operation
-	may be easily reverted later.
+	One can use this to ensure that selected set of packages are installed,
+	and later the temporary modification be undone with *apk-del*(8) _NAME_
+	without removing packages that were installed earlier.
 
 *--no-chown*
 	Do not change file owner or group. By default apk will manage the file
diff --git a/doc/apk-audit.8.scd b/doc/apk-audit.8.scd
index 838895b..8b46c32 100644
--- a/doc/apk-audit.8.scd
+++ b/doc/apk-audit.8.scd
@@ -10,10 +10,17 @@ apk audit - audit directories for changes
 
 # DESCRIPTION
 
-*apk audit* audits the specified directories for changes from the package
-database. By default, the output format is one file per line, for each affected
-file. A character is printed indicating the change detected, followed by a
-space, then the affected path. The changes detected are:
+*apk audit* audits the system or specified directories for changes compared to
+the package database.
+
+The audit can be done against configuration files only (--backup) to generate
+list of files needed to be stored in the overlay in run-from-tmps configuration.
+Alternatively, it can audit all installed files (--system) to e.g. detect
+unauthorized modifications of system files.
+
+By default, the output format is one file per line, for each modified file.
+A character is printed indicating the change detected, followed by a space,
+then the affected path. The changes detected are:
 
 |[ A
 :< File added
@@ -34,17 +41,26 @@ space, then the affected path. The changes detected are:
 
 # OPTIONS
 
+*--backup*
+	Audit configuration files only (default). The list of files to be
+	audited is generated from the masks in protected_paths.d.
+
 *--check-permissions*
-	In addition to checking file contents, check the uid, gid, and file
-	mode as well.
+	Check file permissions too. Namely, the uid, gid and file mode will
+	be checked in addition to the file content.
 
 *--packages*
-	Instead of printing each modified file, print the names and versions of
-	the packages which own the affected files.
+	Print only the packages with changed files. Instead of the full output
+	each modification, the set of packages with at least one modified file
+	is printed.
+
+	To repair all packages with modified files, one could use:
+		apk audit --packages -q | xargs apk fix
 
 *--system*
-	List all modified configuration files (in protected_paths.d) that need
-	to be backed up.
+	Audit all system files. All files provided by packages are verified
+	for integrity with the exception of configuration files (listed in
+	protected_paths.d). This is useful detecting unauthorized file changes.
 
 *-r, --recursive*
 	Descend into directories and audit them as well.
diff --git a/doc/apk-cache.8.scd b/doc/apk-cache.8.scd
index 8675b35..baff1e7 100644
--- a/doc/apk-cache.8.scd
+++ b/doc/apk-cache.8.scd
@@ -14,6 +14,9 @@ apk cache - manage a local cache of package files
 
 # DESCRIPTION
 
+Manage local package cache by removing obsolete packages, or downloading
+missing or newer packages from the repositories.
+
 *apk cache download* will fetch package files from the repositories and store
 them in the cache, which must be enabled upfront (see *apk-cache*(5)).
 
@@ -26,14 +29,16 @@ depended on by packages in _world_.
 # OPTIONS
 
 *-l, --latest*
-	Disables normal heuristics for choosing which repository to install a
-	package from, preferring only repositories from which the latest
-	version is available. This has no effect on pinned packages.
+	Always choose the latest package by version. However, the versions
+	considered are based on the package pinning. Primarily this overrides
+	the default heuristic and will cause an error to displayed if all
+	dependencies cannot be satisfied.
 
 *-u, --upgrade*
-	When caching packages which are already installed, prefer their upgrades
-	rather than considering the requirement fulfilled by the current
-	installation.
+	Upgrade _packages_ and it's dependencies. Normally *apk add* will
+	avoid changing installed package unless it is required by the newly
+	added _packages_ or their dependencies. This changes the default
+	preference to upgrading the package to the latest installable version.
 
 # AUTHORS
 
diff --git a/doc/apk-dot.8.scd b/doc/apk-dot.8.scd
index 03c4ca0..3e3b117 100644
--- a/doc/apk-dot.8.scd
+++ b/doc/apk-dot.8.scd
@@ -10,15 +10,16 @@ apk dot - generate graphviz graphs
 
 # DESCRIPTION
 
-*apk dot* generates graphviz dependency graphs for packages matching the masks
-specified, or for every known package if unspecified (this will generate a
-large and unwieldy graph).
+*apk dot* renders package dependencies as graphviz graphs.
+
+The graph is generated for the packages matching the masks given, or for every
+known package if unspecified (this will generate a large and unwieldy graph).
 
 # OPTIONS
 
 *--errors*
-	Graph only relationships considered erroneous, e.g. cycles and missing
-	packages.
+	Consider only packages with errors. This is useful for visually reporting
+	e.g. cyclic dependencies and missing packages.
 
 *--installed*
 	Consider only installed packages.
diff --git a/doc/apk-fetch.8.scd b/doc/apk-fetch.8.scd
index 1fc826e..fea1e41 100644
--- a/doc/apk-fetch.8.scd
+++ b/doc/apk-fetch.8.scd
@@ -35,6 +35,9 @@ specified.
 *--simulate*
 	Simulate the requested operation without making any changes.
 
+	*Note*: this option is unreliable if needed indexes are not up-to-date
+	as this omits refresing or downloading of missing indexes.
+
 # AUTHORS
 
 Natanael Copa <ncopa@alpinelinux.org>++
diff --git a/doc/apk-fix.8.scd b/doc/apk-fix.8.scd
index 98d7345..f7e6b35 100644
--- a/doc/apk-fix.8.scd
+++ b/doc/apk-fix.8.scd
@@ -25,8 +25,8 @@ following options:
 	Reinstall packages (default).
 
 *-u, --upgrade*
-	When fixing packages which are already installed, upgrade them rather
-	than considering the requirement fulfilled by the current installation.
+	Upgrade name _PACKAGE_ if an upgrade exists and does not break
+	dependencies.
 
 *-x, --xattr*
 	Fix packages with broken xattrs.
diff --git a/doc/apk-info.8.scd b/doc/apk-info.8.scd
index 9974449..a4903c9 100644
--- a/doc/apk-info.8.scd
+++ b/doc/apk-info.8.scd
@@ -31,15 +31,16 @@ display the appropriate information, then an empty line terminates that field.
 	Print the package description.
 
 *-e, --installed*
-	Check if the package is installed, printing its name and exiting with
-	status code zero if so, or exiting with a nonzero status code otherwise.
+	Check package installed status. For each installed package, print it's
+	name. The exit status is the number of given packages not installed.
+	Thus, zero (or success) is returned if all named packages are installed.
 
 *-L, --contents*
 	List files included in the package.
 
 *-i, --install-if*
-	List the package's install_if rule, if configured (i.e. the conditions
-	under which this package will be installed automatically).
+	List the package's install_if rule. When the dependencies in this list
+	are satisfied, the package will be installed automatically.
 
 *-I, --rinstall-if*
 	List other packages whose install_if rules refer to this package.
diff --git a/doc/apk-list.8.scd b/doc/apk-list.8.scd
index 99babf2..fbcdb32 100644
--- a/doc/apk-list.8.scd
+++ b/doc/apk-list.8.scd
@@ -11,8 +11,10 @@ apk list - list packages matching a pattern or other criteria
 # DESCRIPTION
 
 *apk list* searches package indicies for packages matching the given patterns
-and prints any matching packages. The patterns are matched with *fnmatch*(3),
-which behaves similarly to shell globbing.
+and prints any matching packages.
+
+The patterns are matched with *fnmatch*(3), which behaves similarly to shell
+globbing.
 
 # OPTIONS
 
diff --git a/doc/apk-update.8.scd b/doc/apk-update.8.scd
index 8045345..a28358d 100644
--- a/doc/apk-update.8.scd
+++ b/doc/apk-update.8.scd
@@ -10,8 +10,12 @@ apk update - update repository indexes
 
 # DESCRIPTION
 
-*apk update* fetches the index from all configured package repositories. See
-*apk-repositories*(5) for more information on configuring package repositories.
+*apk update* forces updating of the indexes from all configured package
+repositories. This command is not needed in normal operation as all applets
+requiring indexes will automatically refresh them after caching time expires.
+
+See *apk-repositories*(5) for more information on configuring package
+repositories.
 
 # OPTIONS
 
diff --git a/doc/apk-upgrade.8.scd b/doc/apk-upgrade.8.scd
index 49b9cb0..8825dc5 100644
--- a/doc/apk-upgrade.8.scd
+++ b/doc/apk-upgrade.8.scd
@@ -19,14 +19,19 @@ configured package repositories (see *apk-repositories*(5)).
 following options:
 
 *-a, --available*
-	Resets version constraints in _world_ (see *apk-world*(5)) and prefers
-	replacing or downgrading packages if the currently installed package is
-	no longer available from any repository (instead of holding them).
+	Reset all packages to versions available from current repositories.
+	This resets all versioned dependencies in _world_ (see *apk-world*(5)).
+	Additionally, packages are selected from active repositories if possible
+	even if it means replacing or downgrading the package.
+
+	This is useful to reset system against new set of packages after updating
+	repositories.
 
 *-l, --latest*
-	Disables normal heuristics for choosing which repository to install a
-	package from, preferring only repositories from which the latest
-	version is available. This has no effect on pinned packages.
+	Always choose the latest package by version. However, the versions
+	considered are based on the package pinning. Primarily this overrides
+	the default heuristic and will cause an error to displayed if all
+	dependencies cannot be satisfied.
 
 *--no-self-upgrade*
 	Do not do an early upgrade of the 'apk-tools' package.
diff --git a/doc/apk-version.8.scd b/doc/apk-version.8.scd
index add4871..1e29b1e 100644
--- a/doc/apk-version.8.scd
+++ b/doc/apk-version.8.scd
@@ -10,18 +10,20 @@ apk version - compare package versions
 
 *apk version* -c _versions_...
 
-*apk version* -t _left_ _right_
+*apk version* -t _version1_ _version2_
 
 *apk version* -I
 
 # DESCRIPTION
 
 *apk version* compares the versions of installed packages against package
-versions available from repositories (see *apk-repositories*(5)). If no
-packages are specified, all installed packages are considered.  Otherwise,
-the comparison is limited to the explicitly listed packages. A summary is
-printed on stdout, with the difference between package versions being
-represented as *>*, *=*, or *<*.
+versions available from repositories (see *apk-repositories*(5)). It can also
+be used to validate and compare version strings.
+
+In default mode, if no packages are specified, all installed packages are
+considered. Otherwise, the comparison is limited to the explicitly listed
+packages. A summary is printed on stdout, with the difference between package
+versions being represented as *>*, *=*, or *<*.
 
 *apk version -c* tests the specified version string(s) for validity and prints
 a list of _invalid_ version strings. If all version strings are valid, nothing
@@ -44,8 +46,8 @@ specified).
 	Consider packages from all repository tags.
 
 *-l* _operand_
-	Limit output to packages whose comparison is among the given operands,
-	specified as any combination of *>*, *=*, and *<*.
+	Limit to packages with output matching given _operand_. The _operand_
+	can be specified as any combination of *>*, *=*, and *<*.
 
 # AUTHORS
 
diff --git a/doc/apk.8.scd b/doc/apk.8.scd
index 5fdc16d..7c94409 100644
--- a/doc/apk.8.scd
+++ b/doc/apk.8.scd
@@ -10,9 +10,10 @@ apk - Alpine Package Keeper
 
 # DESCRIPTION
 
-*apk* manages packages installed on the system. The set of installed packages
-is called the _world_ (see *apk-world*(5)). *apk* supports various sub-commands
-to query and manipulate _world_ and local & remote package repositories.
+*apk* manages packages installed on the system. The set of top level packages
+to install is called the _world_ (see *apk-world*(5)). *apk* supports various
+sub-commands to query and manipulate _world_ and local & remote package
+repositories.
 
 # COMMANDS
 
@@ -28,13 +29,13 @@ Each command is documented in detail on its manual page.
 ## SYSTEM MAINTENANCE
 
 |[ *apk-fix*(8)
-:< Check _world_ against the system and ensure consistency
+:< Fix, reinstall or upgrade packages without modifying _world_
 |  *apk-update*(8)
 :  Update repository indexes
 |  *apk-upgrade*(8)
 :  Install upgrades available from repositories
 |  *apk-cache*(8)
-:  Commands related to the management of an offline package cache
+:  Manage the local package cache
 
 ## QUERYING PACKAGE INFORMATION
 
@@ -43,7 +44,7 @@ Each command is documented in detail on its manual page.
 |  *apk-list*(8)
 :  List packages matching a pattern or other criteria
 |  *apk-dot*(8)
-:  Generate graphviz graphs
+:  Render dependencies as graphviz graphs
 |  *apk-policy*(8)
 :  Show repository policy for packages
 
@@ -61,7 +62,7 @@ Each command is documented in detail on its manual page.
 ## MISCELLANEOUS
 
 |[ *apk-audit*(8)
-:< Audit directories for changes
+:< Audit system for changes
 |  *apk-stats*(8)
 :  Show statistics about repositories and installations
 |  *apk-version*(8)
@@ -77,8 +78,8 @@ The following options are available for all commands.
 *-i, --interactive*
 	Ask confirmation before performing certain operations.
 
-*-p, --root* <_DIR_>
-	Install packages to _DIR_.
+*-p, --root* <_ROOT_>
+	Manage file system at _ROOT_.
 
 *-q, --quiet*
 	Print less information.
@@ -93,7 +94,8 @@ The following options are available for all commands.
 	Print program version and exit.
 
 *-X, --repository* <_REPO_>
-	Use packages only from the specified repository.
+	Specify additional package repository. This option can be specified
+	multiple times.
 
 *--allow-untrusted*
 	Install packages with untrusted signature or no signature.
@@ -102,10 +104,11 @@ The following options are available for all commands.
 	Temporarily override architecture, to be combined with --root.
 
 *--cache-dir* _CACHEDIR_
-	Temporarily override the cache directory.
+	Temporarily override the cache directory. _CACHEDIR_ is treated relative
+	to the _ROOT_.
 
 *--cache-max-age* _AGE_
-	Maximum AGE (in minutes) for index in cache before it's refresh.
+	Maximum AGE (in minutes) for index in cache before it's refreshed.
 
 *--force-binary-stdout*
 	Continue even if binary data will be printed to the terminal.
@@ -114,7 +117,8 @@ The following options are available for all commands.
 	Continue even if _world_ cannot be satisfied.
 
 *--force-non-repository*
-	Continue even if packages may be lost on reboot.
+	Continue even if packages may be lost on reboot. This can happen when
+	running in run-from-tmpfs mode, and installing non-repository package.
 
 *--force-old-apk*
 	Continue even if packages use unsupported features.
@@ -126,7 +130,7 @@ The following options are available for all commands.
 	Do not use cached files (local or from proxy).
 
 *--keys-dir* _KEYSDIR_
-	Override directory of trusted keys.
+	Override directory of trusted keys. This is treated relative to _ROOT_.
 
 *--no-cache*
 	Do not use any local cache path.
@@ -151,7 +155,9 @@ The following options are available for all commands.
 	packages from cache on cache clean.
 
 *--repositories-file* _REPOFILE_
-	Override repositories file, see *apk-repositories*(8).
+	Override repositories file, see *apk-repositories*(8). This directory
+	is relative to _ROOT_. This can be used to override normal system
+	repositories.
 
 *--wait* _TIME_
 	Wait for TIME seconds to get an exclusive repository lock before
@@ -168,16 +174,20 @@ The following options are available for all commands which commit the database.
 	Do not create .apk-new files in configuration directories.
 
 *--overlay-from-stdin*
-	Read list of overlay files from stdin.
+	Read list of overlay files from stdin. Normally this is used only during
+	initramfs when booting run-from-tmpfs installation.
 
 *--no-scripts*
-	Do not execute any scripts.
+	Do not execute any scripts. Useful for extracting a system image for
+	different architecture on alternative _ROOT_.
 
 *--no-commit-hooks*
 	Skip pre/post hook scripts (but not other scripts).
 
 *--initramfs-diskless-boot*
-	Enables options for diskless initramfs boot (e.g. skip hooks).
+	Used by initramfs when it's recreating root tmpfs. This enables selected
+	force options to minimize failure, and disables commit hooks, among
+	other features.
 
 # NOTES