prt-get.8: corrected some inaccuracies and revised the examples

man8/prt-get.8

@@ -14,9 +14,9 @@ pkgutils from CRUX (see http://www.crux.nu)
 .br 
 .SH "DESCRIPTION"
 prt\-get is a package management tool which provides additional
-functionality to crux' package management system. It works with the
+functionality to the CRUX package management system. It works with the
 local ports tree and is therefore fully compatible with ports(8) and
-pkgmk(8)/pkgadd(8). It offers the following features:
+pkgmk(8)/pkgadd(8)/pkgrm(8). It offers the following features:
 
 .PP
 .TP 
@@ -59,15 +59,15 @@ requirement for crux packages and therefore not always accurate.
 .PP 
 
 prt\-get has a test mode so you can see what effect an install/update
-operation would have. Use the \-\-test switch for this (see also:
+operation would have. Use the \-\-test switch for this (more details in
-OPTIONS)
+the \fBOPTIONS\fP section below).
 
 .SH "RETURN VALUE"
 prt\-get returns 0 on success and a non-zero value otherwise (exact
 value -> meaning mapping to be determined...)
 
 .SH "COMMANDS"
-prt\-get uses so called commands, which always have to be the first 
+prt\-get uses so\-called commands, which always have to be the first 
 non-option argument passed. This is very similar to
 .B cvs(1).
 [command] can be one of the following:
@@ -81,7 +81,10 @@ from any directory.
 .TP 
 .B depinst [\-\-margs] [\-\-aargs] [\-\-log] <package1> [<package2> ...]
 install all packages in the listed order including their dependencies.
-Note that outdated packages won't be updated.
+Note that already-installed packages will be left at their current version,
+even if out of date. prt\-get depinst behaves this way because all of its
+child pkgadd processes will \fBlack\fP the \-u flag, which is needed when
+updating an already-installed package.
 
 .TP 
 .B grpinst [\-\-margs] [\-\-aargs]  [\-\-log] <package1> [<package2> ...]
@@ -95,14 +98,12 @@ update all packages listed in this order. Note: if the latest version of
 a package has acquired dependencies that were not needed by the currently-installed
 version and are not present on the system, the update command will not attempt to
 resolve this omission. prt\-get update behaves this way because pkgadd invocations
-inherit the flag \-u for every package in the transaction (which if applied
+inherit the flag \-u for every package in the transaction, causing an error if the package
-to packages not currently installed, would result in an error). You can follow the CRUX mailing
+is not already installed. You can follow the CRUX mailing list or the IRC channels to stay informed
-list or the IRC channels to stay informed of the situations where an update will require
+of the situations where an update will require manual intervention, or filter the output of
-manual intervention, or parse the output of
+.B prt\-get quickdep $(prt\-get quickdiff)
-.B prt\-get isinst $(prt\-get quickdep $(prt\-get quickdiff))
+through \fBprt\-get isinst\fP to get a list of packages suitable for an \fBinstall\fP or
-as described in the
+\fBupdate\fP command. See the \fBEXAMPLES\fP section below for details.
-.B EXAMPLES
-section below.
 
 .TP 
 .B remove <package1> [<package2> ...]
@@ -114,6 +115,10 @@ Update all installed packages which are outdated. Sorts by dependencies
 by default. Passing the --nodeps switch tells prt\-get not to sort by dependencies,
 for approximately the same effect as
 .B prt\-get update $(prt\-get quickdiff).
+As with an \fBupdate\fP command, the child \fBpkgadd\fP processes will inherit the
+\-u flag, so any dependencies that have been added since the currently-installed version
+of a port are omitted from the transaction (unless they happen to be installed for some other
+reason). See the \fBEXAMPLES\fP section for a way to automate the resolution of such omissions.
 Also see the
 .B lock
 and
@@ -238,9 +243,11 @@ print a tree of the dependencies of the package
 Subtrees already shown are marked with '-->' to save some space. In
 order to show them all, add the --all switch.
 
-Note that soft (optional) dependencies are NOT
+.SH ""
-considered when running prt\-get depends, prt\-get quickdep, or prt\-get deptree. The port
+
-maintainer often provides a README if significant loss of functionality might result from
+Note that soft (optional) dependencies are NOT considered when running
+prt\-get depends, prt\-get quickdep, or prt\-get deptree. The port maintainer
+often provides a README if significant loss of functionality might result from
 not having an optional dependency present when building, so be sure to interpret the output of
 .B prt\-get <depends|quickdep|deptree>
 in light of the information provided in such a README.
@@ -251,14 +258,14 @@ print a list of ports which have
 .B package
 in their "Depends on:" line. As with
 .B depends, quickdep, deptree,
-the Pkgfile line for soft (optional) dependencies is NOT parsed during this operation, so the output
+the Pkgfile line for soft (optional) dependencies is NOT parsed during this operation,
-might omit some of the ports that were linked against
+so the output might omit some of the ports that were linked against
 .B package
 during compilation.
  
-By default, output is restricted to ports that are installed.
+By default, output is restricted to ports that are installed. To see all hard dependencies,
-To see all hard dependencies, add the --all switch; use --recursive to get a recursive
+add the --all switch; use --recursive to get a recursive list (without duplication),
-list (without duplication), and --tree to get a nicely indented one.
+and --tree to get a nicely indented one.
 
 .TP 
 .B dup [-v] [format]
@@ -410,7 +417,7 @@ but does not print the version information. This command has a return value of 0
 Shows the currently-installed version of <package>, or a message
 that <package> is not installed. Unlike
 .B prt\-get isinst package1 package2,
-this command does not accept more than one package as argument. Use
+this command does \fBnot\fP accept more than one package as argument. Use
 .B pkginfo \-i| grep \-E '^(package1|package2|...)'
 to work around this limitation.
 
@@ -423,7 +430,7 @@ Prints out a listing of the port's directory
 Prints out the file to stdout. If <file> is not specified, 'Pkgfile' is used. If set, uses $PAGER.
 
 .TP
-.B edit <package> <file>
+.B edit <package> [<file>]
 Edit the file using the editor specified in the $EDITOR environment variable.
 If <file> is not specified, 'Pkgfile' is used.
 
@@ -537,14 +544,12 @@ onto a different directory than '/'. In daily usage, this option is not required
 interesting if you're developing an independent installation.
 
 Most of the commands fully respect the setting for --install-root, and behave as if you chrooted to
-<dir> before running the command (except that the binaries
+<dir> before running the command (except that the programs \fBprt\-get, pkgmk, pkgadd, pkgrm\fP
-.B prt\-get, pkgmk, pkgadd, pkgrm
 are those on the parent filesystem, not those under <dir>). This can lead to surprising side effects
 if, for example, /etc/pkgadd.conf has different directives than <dir>/etc/pkgadd.conf. In order to
-preserve the pkgadd.conf settings from the host system, append the option --aargs='-c
+preserve the \fBpkgadd.conf(5)\fP settings from the host system, append the option --aargs='-c
-/etc/pkgadd.conf' to your 
+/etc/pkgadd.conf' to your \fBprt-get install\fP command, or just copy the desired directives into
-.B prt-get install
+<dir>/etc/pkgadd.conf .
-command, or just copy the desired directives into <dir>/etc/pkgadd.conf .
 
 .TP 
 .B \-\-log
@@ -611,20 +616,28 @@ Download, build and install irssi, with one simple command
 
 .TP 
 .B prt\-get install paper yasm
-Install paper and yasm
+Install paper and yasm. Abort with an informative error message if either package is already
+installed, allowing you to issue a revised command.
+
+.TP
+.B prt\-get update bmake cmake
+Update bmake and cmake. Abort with an informative error message if either package is not yet
+installed, allowing you to issue a revised command.
 
 .TP 
 .B prt\-get update -fr openssh
-Update your current version of openssh, forcing a rebuild even if no version difference is detected :\-)
+Update your current version of openssh, forcing a rebuild even if no version difference is detected.
+Useful if there was a major version change in one of its dependencies, and \fBrevdep openssh\fP
+indicates a broken package. :\-)
 
 .TP 
 .B prt\-get info glib-networking
 Show info about glib-networking
 
 .TP
-.B MISSLIBS=$(revdep -vvv mpv | awk -F ':' '/(missing library)/ {print $3}'); [ -n \(dq${MISSLIBS[@]}\(dq ] && for i in \(dq${MISSLIBS[@]}\(dq; do prt\-get fsearch $i; done
+.B MISSLIBS=$(revdep -vvv mpv | awk -F ':' '/(missing library)/ {print $3}'); [ -n \(dq${MISSLIBS[@]}\(dq ] && for i in ${MISSLIBS[@]}; do prt\-get fsearch $i; done
-Check for the presence of the runtime libraries needed by mpv. If any are absent, search the
+(adapted from a script by ppetrov^) Check for the presence of the runtime libraries needed by mpv.
-footprints to determine which ports provide the missing libraries.
+If any are absent, search the footprints to determine which ports provide the missing libraries.
 
 .TP 
 .B prt\-get search --regex '^(m|n|p)c.*'
@@ -636,13 +649,26 @@ Return a list of all ports having "irc" in their name or description
 
 .TP
 .B comm -13 <(ls /usr/ports/core) <(prt-get listorphans)
-Filter out the core ports from the list of orphans, in shells (like bash)
+(based on comments from Romster and jue) Filter out the core ports from the list of orphans, in
-that support process substitution
+shells (like bash) that support process substitution
+
+.TP
+.B comm -13 <(cat ~/.keepers <(ls /usr/ports/core) | sort) <(prt\-get listorphans) | xargs prt\-get remove
+(system-hosing extension of the above) A one-liner inspired by \fBpkg\-clean\fP
+and \fBpkgfoster\fP, but without the safeguard of interactivity. \fBDo not try this on a
+mission-critical system.\fP
 
 .TP
 .B prt\-get isinst $(prt\-get quickdep $(prt\-get quickdiff)) | awk '/not installed/ {print $2}'
-After updating your ports tree, print out a list of dependencies that were not needed the last time
+(adapted from a comment by Fun) After updating your ports tree, print out a list of dependencies
-you built your currently-installed ports, but are needed now by the newer versions of these ports.
+that were not needed the last time you built your currently-installed ports, but are needed now by
+the newer versions of these ports. The output of this command is sorted by dependencies, therefore
+suitable for piping to \fBxargs prt\-get install\fP or \fBxargs prt\-get grpinst\fP.
+
+.TP
+.B prt\-get isinst $(prt\-get quickdep $(prt\-get quickdiff)) | awk '/is installed/ {print $2}'
+Same as above, but only print the dependencies that are already installed. The output of this
+command is suitable for piping to \fBxargs prt\-get update\fP.
 
 .TP 
 .B prt\-get grpinst \-\-test `prt\-get quickdep graphviz`
@@ -664,11 +690,7 @@ pkgadd.conf that you want applied to this operation, either copy it to
 Show the ports whose names begin with xorg, but which appear outside the xorg port collection.
 (At the time of writing, this command returned at least two font ports.)
 
-.TP 
-.B prt\-get update `prt\-get quickdiff`
-Update all packages where a different version is in the ports tree
-
 .SH "AUTHORS"
-Johannes Winkelmann <jw@tks6.net>
+Johannes Winkelmann <jw@tks6.net>, and others cited inline
 .SH "SEE ALSO"
 prt\-get.conf(5), prt\-cache(8), Pkgfile(5), pkgmk(8), pkgadd(8), ports(8)