man-page: add a few references and another example

correct misspellings and inaccuracies

fix formatting

doc/prt-get.8

@@ -91,63 +91,59 @@ Basically a synonym for install (without the --nodeps flag).
 Basically a synonym for install. Earlier versions of \fBprt\-get\fP did not 
 adjust the \fBpkgadd(8)\fP arguments on a package-by-package basis, but
 applied "install mode" or "update mode" to the entire transaction. This 
-latest \fBprt\-get\fP interprets the install command less rigidly, and tries 
+version of \fBprt\-get\fP interprets the install command less rigidly, and tries 
-to sync your installed ports with their repository versions unless instructed 
+to sync all affected ports with their repository versions unless instructed 
 otherwise (using \fBprt\-get lock\fP, the --prefer-higher option, or the 
-\fIprt-get.aliases\fP file).
+prt-get.aliases file).
 
 .TP 
 .B remove <package1> [<package2> ...]
 Remove packages listed in this order
 
 .TP 
-.B sysup [\-\-softdeps] [\-\-nodeps]
+.B sysup [\-\-softdeps] [\-\-nodeps] [\-\-prefer\-higher] [\-\-strict\-diff]
 Update all installed packages which are outdated. Sorts by hard dependencies
 by default. Passing the --softdeps switch tells \fBprt\-get\fP to also consider
 optional dependencies when sorting. Passing the --nodeps switch tells prt-get 
 not to sort by dependencies at all.
 
-.B Breaking Change:
+.B Note:
 If a port has acquired new dependencies since its last successful build,
-those new dependencies will be injected into the transaction. This feature
+those new dependencies \fIwill\fP be injected into the transaction. An elegant
-lingered many years on the TODO list, and its absence was the motivation for
+description of this new behaviour is "prt-get no more silently assumes that
-many clever workarounds (documented in the \fBEXAMPLES\fP section below).
+the user didn't want a particular dependency" [1]. You can still disable the
+automatic dependency injection by passing the --nodeps switch. Other
+ways to fine-tune the selection of ports that are included in a \fBsysup\fP are the
+commands \fBlock\fP and \fBunlock\fP, the prt-get.aliases file, and the
+mutually exclusive switches --prefer-higher, --strict-diff (documented below).
 
-You can use the
+[1] https://lists.crux.nu/pipermail/crux/2008-June/001784.html
-.B lock
-and
-.B unlock
-commands to keep the currently installed versions, even if there are
-changes in the ports tree. If you want to update only diffs which have
-a lower version installed than the one in the ports tree, use the
---prefer-higher option.
 
 .TP 
 .B lock <package1> [<package2>...]
-Do not update these packages in a
+Exclude these packages from being updated in a
 .B sysup
-operation
+operation.
 
 .TP 
 .B unlock <package1> [<package2>...] 
 Remove lock from these packages
 
 .TP 
-.B listlocked [-v|-vv]
+.B listlocked [\-v|\-vv]
 List names of packages which are locked. As always,
-.B -v
+.B \-v
 will additionally show the version, and
-.B -vv
+.B \-vv
 also includes the description from the Pkgfile. Note that the
-.B -vv
+.B \-vv
 switch will slow down the operation remarkably.
 
 .TP 
 .B diff [\-\-all] [\-\-prefer\-higher] [<package1> <package2> ...]
 Show differences between installed packages and ports in the ports
-tree. If arguments are given, shows only differences for these
+tree. Package names passed as argument will truncate the output to 
-packages, otherwise all differences are shown. It's also possible to use
+show only those packages. It's also possible to use shell-like
-shell-like
 .B wildcards
 for the diff command. Make sure you escape where needed. Locked
 packages are only displayed if you use the --all switch. If you want
@@ -155,7 +151,7 @@ to see only diffs which have a lower version installed than the one in
 the ports tree, use the --prefer-higher option.
 
 .TP 
-.B quickdiff
+.B quickdiff [\-\-prefer\-higher]
 Print a simple list of packages which have a different version in the
 ports tree than what is installed. The output is sorted alphabetically, 
 but you can generate a (larger) list sorted by dependencies using
@@ -185,10 +181,9 @@ read every Pkgfile when the ports tree is updated.
 Search the ports tree for
 .B pattern
 as file name in their footprint. When called without '--full', strips
-the directories from the file names before matching; this behaviour
+the directories from the file names before matching. Pattern can be a 
-will change in prt-get 0.6, where full path search will be the
+shell-like wildcard pattern (e.g. prt-get fsearch "*.h") or a regular
-default. Pattern can be a shell-like wildcard pattern (e.g. prt-get
+expression (e.g. prt-get fsearch --regex 'liblz(o2|ma).*')
-fsearch "*.h") or a regular expression (e.g. prt-get fsearch --regex 'liblz(o2|ma).*')
 
 .TP 
 .B info <port>
@@ -231,16 +226,17 @@ for successful builds.
 .B deptree [\-\-softdeps] <package>
 Print a tree of the dependencies of the package
 .B <package>. 
-Pass the --softdeps flag to also show the installed packages that mention
+Pass the --softdeps flag to also show the installed packages that might have been
+eagerly linked when
 .B <package>
-as an optional dependency.
+or its dependencies were compiled.
 Subtrees already shown are marked with '-->' to save some space. In
 order to show them all, add the --all switch.
 
 .SH ""
 
 .TP 
-.B dependent [\-\-softdeps] <package>
+.B dependent [\-\-softdeps] [\-\-all] <package>
 Print a list of ports which have
 .B <package>
 in their "Depends on:" line. Use the --softdeps flag to also search the
@@ -253,10 +249,15 @@ dependencies, add the --all switch; use --recursive to get a recursive list
 .TP 
 .B dup [-v] [format]
 List ports which can be found in multiple directories configured in
-.B /etc/prt-get.conf
+\fB/etc/prt\-get.conf\fP.
-Use the verbose switch to simulate the output of version 5.12 and older (likely
+Use the \fB\-v\fP switch to see a verbose report, which will show for each
-to go away in the future). The format string can be used to create user
+dup the port that takes precedence, and the port that is hidden (including
-specified formats. The following symbols are currently replaced:
+full path and version info). The verbose switch is basically an alias for a
+particular combination of the recognized format symbols, namely
+
+.B '* %n\en   %p1 %v1 precedes over\en  %p2 %v2\en'.
+
+You can customize the output by combining these symbols in other ways.
 
 .TP 
 \ \ \ \(bu
@@ -264,19 +265,19 @@ specified formats. The following symbols are currently replaced:
 
 .TP 
 \ \ \ \(bu
-%p1 \-> Full path (including name) to port taking precendence
+%p1 \-> full path (including name) to port taking precedence
 
 .TP 
 \ \ \ \(bu
-%p2 \-> Full path (including name) to port being hidden
+%p2 \-> full path (including name) to port being hidden
 
 .TP 
 \ \ \ \(bu
-%v1 \-> Version of port taking precendence
+%v1 \-> version of port taking precedence
 
 .TP
 \ \ \ \(bu
-%v2 \-> Version of port being hidden
+%v2 \-> version of port being hidden
 
 
 .TP 
@@ -327,11 +328,11 @@ are replaced like this:
 
 .TP 
 \ \ \ \(bu
-%M -> Maintainer
+%M -> maintainer
 
 .TP 
 \ \ \ \(bu
-%R -> Readme ("yes"/"no")
+%R -> readme ("yes"/"no")
 
 .TP 
 \ \ \ \(bu
@@ -351,7 +352,7 @@ are replaced like this:
 up to date and "diff" if it's installed and a new version is in the
 ports tree.
 
-Use "\\n" and "\\t" to format your output (no additional format codes
+Use "\en" and "\et" to format your output (no additional format codes
 supported). The optional format string2 can contain the same variables
 as format string1 and is used to sort the output. You can specify a
 .B wildcard filter
@@ -500,7 +501,7 @@ or injecting missing dependencies.
 .TP
 .B \-\-softdeps
 Consider optional dependencies when determining the order in which to build
-the packages passed as arguments (in a \fBdepinst\fP or \fBsysup\fP operation).
+the packages passed as arguments (in \fBinstall\fP or \fBsysup\fP operations).
 Also affects the output of \fBdeptree\fP, \fBdependent\fP, and \fBlistorphans\fP.
 
 .TP 
@@ -513,19 +514,19 @@ Dry run, don't actually install anything, mostly interesting for
 .B prt\-get install, prt\-get update, prt\-get sysup
 
 .TP 
-.B \-\-pre-install
+.B \-\-pre\-install
 Execute pre-install script if it's there
 
 .TP 
-.B \-\-post-install
+.B \-\-post\-install
 Execute post-install script if it's there
 
 .TP 
-.B \-\-install-scripts
+.B \-\-install\-scripts
 Execute pre-install and post-install script if they're there
 
 .TP
-.B \-\-install-root=<dir>
+.B \-\-install\-root=<dir>
 Use <dir> as root directory for your installation; allows you to install 
 the requested packages onto a different directory than '/'. In daily usage, 
 this option is not required; it's primarily interesting if you're developing 
@@ -534,10 +535,8 @@ an independent installation.
 Pre- and post-install scripts will not be executed if the requested 
 root directory lacks a copy of the ports tree. So if you're maintaining an
 installation mounted somewhere different than '/', it's not enough to put
-the line
+the line 'runscripts yes' in your prt-get.conf; you also have to ensure that the
-.B runscripts yes
+pre- and post-install scripts can be found in the same location relative to <dir>.
-in your prt-get.conf; you also have to ensure that the pre- and post-install
-scripts can be found in the same location relative to <dir>.
 
 The setting for --install-root determines which package database is used for 
 reading/writing (so <dir>/var/lib/pkg/db must exist), and where the pkg.tar.?z 
@@ -639,6 +638,12 @@ and \fBrevdep openssh\fP indicates a broken package. :-)
 (adapted from a script by ppetrov^) Check for the presence of the runtime libraries needed by mpv.
 If any are absent, search the footprints to determine which ports provide the missing libraries.
 
+.TP
+.B prt\-get isinst $(ls /usr/pkgmk/packages | sed 's/.*\e///' | tr '\en' ' ') | grep 'not installed'
+Determine whether there are any packages (in a shared output directory) that
+have since been uninstalled, or were never installed after a successful run
+of \fBpkgmk\fP.
+
 .TP
 .B prt\-get printf '%i:%p:%n\en' | awk -v FS=: '/^diff:\e/usr\e/ports\e/core/ { print $3 }' | xargs prt\-get update
 Basically a \fBsysup\fP operation, but restricted to the core collection.