man pages: make more friendly for help generation

Also few minor fixups added.

1 files changed, 26 insertions, 10 deletions

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.