prt-get.8: revise the examples section

man8/prt-get.8

@@ -1,7 +1,7 @@
 .\" man page for prt-get
 .\" original work by Johannes Winkelmann, jw at tks6 dot net
 .\" 
-.\" revised 2022 by John McQuah, jmcquah at disroot dot org
+.\" extended in 2023 by John McQuah, jmcquah at disroot dot org
 .\" 
 .\" .PU
 .TH "prt-get" "8" "" "" ""
@@ -75,12 +75,12 @@ non-option argument passed. This is very similar to
 
 .TP 
 .B install [\-\-margs] [\-\-aargs] [\-\-log] <package1> [<package2> ...]
-install all packages in the listed order. Note that you can do this
+Install all packages in the listed order. Note that you can do this
 from any directory.
 
 .TP 
 .B depinst [\-\-margs] [\-\-aargs] [\-\-log] <package1> [<package2> ...]
-install all packages in the listed order including their dependencies.
+Install all packages given on the command line, including their dependencies.
 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
@@ -88,38 +88,42 @@ updating an already-installed package.
 
 .TP 
 .B grpinst [\-\-margs] [\-\-aargs]  [\-\-log] <package1> [<package2> ...]
-install all packages in the listed order, but stop if installation of
+Install all packages in the listed order, but stop if installation of
 one package fails. This can be used to install packages where package2
 depends on package1.
 
 .TP 
 .B update [\-\-margs] [\-\-aargs]  [\-\-log] <package1> [<package2> ...]
-update all packages listed in this order. Note: if the latest version of
+Update all packages listed in this order. Note: if the latest version of a
-a package has acquired dependencies that were not needed by the currently-installed
+package has acquired dependencies that were not needed by the
-version and are not present on the system, the update command will not attempt to
+currently-installed version and are not present on the system, the update
-resolve this omission. prt\-get update behaves this way because pkgadd invocations
+command will not attempt to resolve this omission. prt-get update behaves
-inherit the flag \-u for every package in the transaction, causing an error if the package
+this way because pkgadd invocations inherit the flag -u for every package in
-is not already installed. You can follow the CRUX mailing list or the IRC channels to stay informed
+the transaction, causing an error if the package is not already installed.
-of the situations where an update will require manual intervention, or filter the output of
+You can follow the CRUX mailing list or the IRC channels to stay informed of
+the situations where an update will require manual intervention, or filter
+the output of
 .B prt\-get quickdep $(prt\-get quickdiff)
-through \fBprt\-get isinst\fP to get a list of packages suitable for an \fBinstall\fP or
+through \fBprt\-get isinst\fP to get a list of packages suitable for an 
-\fBupdate\fP command. See the \fBEXAMPLES\fP section below for details.
+\fBinstall\fP or \fBupdate\fP command.
+See the \fBEXAMPLES\fP section below for details.
 
 .TP 
 .B remove <package1> [<package2> ...]
-remove packages listed in this order
+Remove packages listed in this order
 
 .TP 
 .B sysup [\-\-nodeps]
-Update all installed packages which are outdated. Sorts by dependencies
+Update all installed packages which are outdated. Sorts by hard dependencies
-by default. Passing the --nodeps switch tells prt\-get not to sort by dependencies,
+by default. Passing the --nodeps switch tells prt-get not to sort by
-for approximately the same effect as
+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
+As with an \fBupdate\fP command, the child \fBpkgadd\fP processes will 
-\-u flag, so any dependencies that have been added since the currently-installed version
+inherit the \-u flag, so if a port has acquired new dependencies since 
-of a port are omitted from the transaction (unless they happen to be installed for some other
+its last successful build, those new dependencies will be omitted from 
-reason). See the \fBEXAMPLES\fP section for a way to automate the resolution of such omissions.
+the transaction (unless they happen to be installed for some other reason and
-Also see the
+are also in need of an update). See the \fBEXAMPLES\fP section for a way to
+automate the resolution of such omissions. Also see the
 .B lock
 and
 .B unlock
@@ -150,7 +154,7 @@ 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
+Show differences between installed packages and ports in the ports
 tree. If arguments are given, shows only differences for these
 packages, otherwise all differences are shown. It's also possible to use
 shell-like
@@ -162,12 +166,12 @@ the ports tree, use the --prefer-higher option.
 
 .TP 
 .B quickdiff
-prints a simple list of packages which have a different version in the
+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
 .B prt\-get quickdep $(prt\-get quickdiff).
-Note that the resulting list is usually a mix of installed and not-installed packages,
+Note that the resulting list is usually a mix of installed and 
-so it must be filtered by
+not-installed packages, so it must be filtered by
 .B prt\-get isinst
 before being passed as argument to prt\-get install or prt\-get update. See the
 .B EXAMPLES
@@ -188,19 +192,18 @@ Search the ports tree (both name and description) for the pattern
 .B expr
 (which can be a shell-like wildcard pattern or a regexp). The search in
 the description is not case sensitive. Note that this requires prt\-get
-to read every Pkgfile, which makes it rather slow; if you like this,
+to read every Pkgfile, which makes it rather slow. If you like searching by
-consider using the cache functionality, so you only have to spend this
+description, consider using the cache functionality, so you only have to
-time once after updating the ports tree has been updated.
+read all the Pkgfiles after each update of the ports tree.
 
 .TP 
 .B fsearch [\-\-full] [\-\-regex] <pattern>
 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. 
-will change in prt-get 0.6, where full path search will be the
+Pattern can be a shell-like wildcard pattern (e.g. prt-get fsearch "*.h") 
-default. Pattern can be a shell-like wildcard pattern (e.g. prt-get
+or a regular 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 
@@ -217,71 +220,67 @@ Print the port's README file if it exists; if set, uses $PAGER
 
 .TP 
 .B depends <package1> [<package2> ...]
-print a recursive list of dependencies needed to install the packages passed
+Print a recursive list of dependencies needed to install the packages
-as argument. It shows a list of the dependencies that were found in the ports tree,
+passed as argument. It shows a list of the dependencies that were found in
-plus a list of the dependencies that could not be found.
+the ports tree, plus a list of the dependencies that could not be found.
 
 .TP 
 .B quickdep <package1> [<package2> ...]
-print a simple list of recursive dependencies for all the packages passed
+Same output as \fBdepends\fP, but separated by spaces rather than newlines,
-as argument. The output is formatted to be useful in command substitution, e.g. instead of
+and stripped of any dependencies that could not be found in the ports tree.
-running
+Useful in case the list of dependencies is too large to fit on one screen,
+or if you don't want to filter out manually the ports that are invalid
+targets for installation. For example, instead of
 .B prt\-get depinst xorg-server
-you might obfuscate your intentions with a gratuitous loop:
+you might micromanage the process as follows:
-.B for i in $(prt\-get quickdep xorg-server); do prt\-get isinst $i || prt\-get install $i; done
+.B for i in $(prt\-get quickdep xorg-server); do if prt\-get isinst $i 2>/dev/null; then prt\-get update \-fr $i; else prt\-get install $i; fi; done
+which ensures that the latest version of each dependency is built.
 
-Note: output is restricted to those dependencies that can be found in the ports tree. It might be
+Note: It might be useful to run
-useful to run
 .B prt\-get depends <package1> | grep \(dq\-\- missing packages\(dq
-as a first step, in order to ensure that your ports tree has everything needed for successful
+as a first step, in order to ensure that your ports tree has everything needed 
-builds.
+for successful builds.
 
 .TP 
 .B deptree <package>
-print a tree of the dependencies of the package
+Print a tree of the dependencies of the package
-.B package. 
+.B <package>. 
 Subtrees already shown are marked with '-->' to save some space. In
 order to show them all, add the --all switch.
 
 .SH ""
 
-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.
-
 .TP 
-.B dependent <package>
+.B dependent [\-\-recursive] [\-\-all] [\-\-tree] <package>
-print a list of ports which have
+Print a list of ports whose "Depends on:" line contains
-.B package
+.B <package>
-in their "Depends on:" line. As with
+(or its dependents, if --recursive was passed).
-.B depends, quickdep, deptree,
-the Pkgfile line for soft (optional) dependencies is NOT parsed during this operation,
-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. To see all hard dependencies,
+By default, output is restricted to ports that are installed. To see all
-add the --all switch; use --recursive to get a recursive list (without duplication),
+the dependencies, use the --all switch. Use --tree to get a nicely indented
-and --tree to get a nicely indented one.
+list.
 
 .TP 
 .B dup [-v] [format]
 List ports which can be found in multiple directories configured in
 .B /etc/prt-get.conf
-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 passing a different format string, whose 
+symbols will be replaced as follows.
 
 .TP 
 \ \ \ \(bu
-%n \-> name of the port
+%n \-> Name of the port
 
 .TP 
 \ \ \ \(bu
-%p1 \-> Full path (including name) to port taking precendence
+%p1 \-> Full path (including name) to port taking precedence
 
 .TP 
 \ \ \ \(bu
@@ -289,13 +288,12 @@ specified formats. The following symbols are currently replaced:
 
 .TP 
 \ \ \ \(bu
-%v1 \-> Version of port taking precendence
+%v1 \-> Version of port taking precedence
 
 .TP
 \ \ \ \(bu
 %v2 \-> Version of port being hidden
 
-
 .TP 
 .B list [\-v|\-vv] [\-\-path] [\-\-regex] [filter]
 List ports available in the ports tree. It's basically the same as
@@ -304,11 +302,11 @@ but looks in all directories specified in
 .B /etc/prt\-get.conf.
 It's also possible to use shell-like
 .B wildcards
-for the list command. Make sure you escape where needed
+for the list command. Make sure you escape where needed.
 
 .TP 
 .B printf <format string1> [\-\-sort=<format string2>] [\-\-filter=<filter>]
-Print formatted port list format string can contain variables, which
+Print formatted port list. Format string can contain variables, which
 are replaced like this:
 .TP 
 \ \ \ \(bu
@@ -336,11 +334,11 @@ are replaced like this:
 
 .TP 
 \ \ \ \(bu
-%u \-> URL
+%P -> Packager
 
 .TP 
 \ \ \ \(bu
-%P -> Packager
+%u \-> URL
 
 .TP 
 \ \ \ \(bu
@@ -368,7 +366,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 specified
+Use "\\n" and "\\t" to format your output (no additional format symbols
 suported). 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
@@ -379,42 +377,42 @@ to filter by package name.
 .B listinst [\-v|\-vv] [\-\-regex] [\-\-depsort] [filter]
 List installed ports. It's basically the same as
 .B pkginfo \-i,
-but omits version when called without verbose (\-v, \-vv) switch. Plus
+but omits version when called without verbose (-v, -vv) switch. Plus
-it is notably faster in my tests. \-v adds version information, \-vv
+it is notably faster in my tests. -v adds version information, -vv
 adds version and description.
 .B Warning:
-\-vv will slow down the process because it requires prt\-get to scan
+-vv will slow down the process because it requires prt-get to scan
 both the ports database and the ports tree.
 It's also possible to use shell-like
 .B wildcards
 for the listinst command. Make sure you escape where needed. By default
-it's sorted alphabetically; use the \-\-depsort switch to sort by
+it's sorted alphabetically; use the --depsort switch to sort by
 dependencies.
 
 .TP 
 .B listorphans [\-v|\-vv]
 List installed ports which do not appear in the "Depends on:" line of
-any other port currently installed. Output appears alphabetically separated by newlines, making it
+any other port currently installed. 
-suitable for process substitution as shown in the
+Output appears alphabetically separated by newlines, making it suitable for 
+process substitution as shown in the
 .B EXAMPLES
 section below. Note that some core ports might be runtime
 dependencies despite their absence in the "Depends on:" line; see \fBPkgfile(5)\fP
-for an explanation of this practice. Also remember that this operation does NOT account for soft
+for an explanation of this practice. 
-(optional) dependencies. Removing a non-core package returned by this command might require a
-rebuild of other packages; use revdep(1) to locate such breakage.
-
 
 .TP 
 .B isinst <package1> [<package2> ...]
-Check whether each package given on the command line is installed. Output in the case of multiple
+Check whether each package given on the command line is installed. Output in 
-arguments is separated by newlines, suitable for processing by awk or grep. Similar to
+the case of multiple arguments is separated by newlines, suitable for 
+processing by awk or grep. Similar to
 .B pkginfo \-i|grep \-E '^(package1|package2|...)'
-but does not print the version information. This command has a return value of 0 if
+but does not print the version information. This command has a return value of 
-all packages given as argument are installed, otherwise a return value greater than 0.
+0 if all packages given as argument are installed, otherwise a return value 
+greater than 0.
 
 .TP
 .B current <package>
-Shows the currently-installed version of <package>, or a message
+Show the currently-installed version of <package>, or a message
 that <package> is not installed. Unlike
 .B prt\-get isinst package1 package2,
 this command does \fBnot\fP accept more than one package as argument. Use
@@ -422,12 +420,12 @@ this command does \fBnot\fP accept more than one package as argument. Use
 to work around this limitation.
 
 .TP
-.B ls [--path] <package>
+.B ls [\-\-path] <package>
-Prints out a listing of the port's directory
+List the contents of the port's directory
 
 .TP
 .B cat <package> [<file>]
-Prints out the file to stdout. If <file> is not specified, 'Pkgfile' is used. If set, uses $PAGER.
+Print the file to stdout. If <file> is not specified, 'Pkgfile' is used. If set, uses $PAGER.
 
 .TP
 .B edit <package> [<file>]
@@ -437,7 +435,7 @@ If <file> is not specified, 'Pkgfile' is used.
 
 .TP 
 .B help
-Shows a help screen
+Show a help screen
 
 .TP 
 .B dumpconfig
@@ -445,12 +443,12 @@ Dump the configuration to the current terminal
 
 .TP 
 .B version 
-Shows the current version of prt\-get
+Show the current version of prt-get
 
 .TP 
 .B cache
-create a cache file from the ports tree to be used by prt\-get using the
+Create a cache file from the ports tree to be used by prt-get using the
-\-\-cache option. Remember to run prt\-get cache each time you update the
+--cache option. Remember to run prt-get cache each time you update the
 ports tree.
 
 .SH "OPTIONS"
@@ -458,43 +456,43 @@ ports tree.
 The following options are primarily useful for install/update transactions.
 
 .TP
-.B -f, -i
+.B \-f, \-fi
 Force install; Implies 'pkgadd -f'; same as --aargs=-f
 
 .TP
-.B -fr
+.B \-fr
 Force rebuild, Implies 'pkgmk -f'; same as --margs=-f
 
 .TP
-.B -um
+.B \-um
 Update md5sum, implies 'pkgmk -um'; same as --margs=-um
 
 .TP
-.B -im
+.B \-im
 Ignore md5sum, implies 'pkgmk -im'; same as --margs=-im
 
 .TP
-.B -us
+.B \-us
 Update signature, implies 'pkgmk -us'; same as --margs=-us
 
 .TP
-.B -is
+.B \-is
 Ignore signature, implies 'pkgmk -is'; same as --margs=-is
 
 .TP
-.B -uf
+.B \-uf
 Update footprint, implies 'pkgmk -uf'; same as --margs=-uf
 
 .TP
-.B -if
+.B \-if
 Ignore footprint, implies 'pkgmk -if'; same as --margs=-if
 
 .TP
-.B -ns
+.B \-ns
 No stripping, implies 'pkgmk -ns'; same as --margs=-ns
 
 .TP
-.B -kw
+.B \-kw
 Keep working directory, implies 'pkgmk -kw'; same as --margs=-kw
 
 .TP 
@@ -512,10 +510,9 @@ arguments to be passed to pkgrm; currently not used, implemented for
 future uses and consistency reasons
 
 .TP
-.B --ignore=<package1,package2,...>
+.B \-\-ignore=<package1,package2,...>
 Don't install these packages, even if they're listed as dependencies
 
-
 .TP 
 .B \-\-cache
 Use cache file for this command
@@ -523,7 +520,7 @@ Use cache file for this command
 .TP 
 .B \-\-test
 Dry run, don't actually install anything, mostly interesting for
-.B prt\-get install, prt\-get grpinst, prt\-get update, prt\-get sysup
+.B prt\-get install, prt\-get update, prt\-get sysup
 
 .TP 
 .B \-\-pre-install
@@ -537,24 +534,48 @@ Execute post-install script if it's there
 .B \-\-install-scripts
 Execute pre-install and post-install script if they're there
 
+The options --pre-install, --post-install, and --install-scripts offer a
+convenient way to temporarily override the prt-get.conf directive 'runscripts
+no', which was the historical default. Starting with CRUX 3.7, prt-get.conf is
+being shipped with 'runscripts yes'. To override this default at the command
+line, you have to pass the more cumbersome option --config-set=\(dqrunscripts
+no\(dq, or point prt-get to an alternative configuration file using
+--config=<file>. (see below for the documentation of these options)
+
 .TP
 .B \-\-install-root=<dir>
-Use <dir> as root directory for your installation; allows you to install the requested packages
+Use <dir> as root directory for your installation; allows you to install 
-onto a different directory than '/'. In daily usage, this option is not required; it's primarily
+the requested packages onto a different directory than '/'. In daily usage, 
-interesting if you're developing an independent installation.
+this option is not required; it's primarily interesting if you're developing 
+an independent installation.
 
-The setting for --install-root determines which package database is used for reading/writing (so
+The setting for --install-root determines which package database is used for 
-<dir>/var/lib/pkg/db must exist), and where the pkg.tar.?z archives get unpacked, but the
+reading/writing (so <dir>/var/lib/pkg/db must exist), and where the pkg.tar.?z 
-relevant prt\-get.conf and ports tree are those on the parent filesystem. Therefore it is not
+archives get unpacked, but the relevant prt-get.conf and ports tree are those 
-necessary for <dir> to contain its own copy of the ports tree, or even a copy of prt-get.conf.
+on the parent filesystem. Therefore it is not necessary for <dir> to contain 
-However, if <dir>/etc/pkgadd.conf exists and is different from /etc/pkgadd.conf, then install or
+its own copy of the ports tree. But each \fBpkgmk(8)\fP process will take place
-update commands might behave unexpectedly. In order to preserve the \fBpkgadd.conf(5)\fP settings
+on the parent filesystem, inspecting \fIthe parent filesystem\fP's environment
-from the host system, append the option --aargs='-c /etc/pkgadd.conf' to your \fBprt-get install\fP
+for information about installed ports and available shared libraries. The
-command, or just copy the desired directives into <dir>/etc/pkgadd.conf .
+\fBpkgmk(8)\fP process might therefore draw the wrong conclusions about what
+functionality should be enabled for an installation to <dir>. If the parent
+filesystem is more richly populated than <dir>, with respect to installed
+packages, then the built package might exhibit breakage when \fBpkgadd\fP
+unpacks it into <dir>.
+
+When setting --install-root=<dir>, install or update commands might behave
+unexpectedly if <dir>/etc/pkgadd.conf exists and is different from
+/etc/pkgadd.conf . In order to preserve the \fBpkgadd.conf(5)\fP settings from
+the host system, append the option --aargs='-c /etc/pkgadd.conf' to your
+\fBprt-get install\fP command, or just copy the desired directives into
+<dir>/etc/pkgadd.conf .
 
 .TP 
 .B \-\-log
-Write build output to log file
+Write build output to log file. Basically a convenient alias for
+\fB\-\-config\-set=\(dqwritelog enabled\(dq\fP. Note that there is no similar
+alias allowing you to temporarily override the one configuration directive
+\(dqwritelog enabled\(dq; you have to resort to \fB\-\-config\-set=\(dqwritelog
+disabled\(dq\fP if that is your intention.
 
 .TP 
 .B \-\-no-std-config
@@ -574,12 +595,13 @@ Set <string> in configuration, overriding configuration file
 
 .TP 
 .B \-\-config=<file>
-Use alternative configuration file to read ports directories from
+Use <file> to read configuration directives, rather than /etc/prt-get.conf.
 
 .SH ""
 
-The following options are primarily useful for non-install (information-seeking) transactions,
+The following options are primarily useful for non-install (information-seeking) 
-although some of them affect the behaviour of install/upgrade transactions as well.
+transactions, although some of them affect the behaviour of install/upgrade 
+transactions as well.
 
 .TP 
 .B \-v, \-vv
@@ -602,7 +624,8 @@ a sysup operation.
 
 .TP
 .B \-\-strict\-diff, \-sd
-Override the 'preferhigher' configuration option
+Override the 'preferhigher' configuration option. Equivalent to
+.B \-\-config\-set=\(dqpreferhigher no\(dq
 
 
 
@@ -617,13 +640,8 @@ Download, build and install irssi, with one simple command
 
 .TP 
 .B prt\-get install paper yasm
-Install paper and yasm. Abort with an informative error message if either package is already
+Install paper and yasm. Abort with an informative error message if either
-installed, allowing you to issue a revised command.
+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
@@ -632,12 +650,24 @@ Useful if there was a major version change in one of its dependencies, and \fBre
 indicates a broken package. :\-)
 
 .TP
-.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
+.B MISSLIBS=$(revdep -vvv mpv | awk -v FS=: '/(missing library)/ {print $3}'); [ -n \(dq${MISSLIBS[@]}\(dq ] && for i in ${MISSLIBS[@]}; do prt\-get fsearch $i; done
 (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 search --regex '^(m|n|p)c.*'
+.B prt\-get isinst $(prt\-get info ffmpeg | awk \-v FS=: '/^Optional/ {gsub(/,/,\(dq \(dq,$2); print $2}') | awk -v FS=\(dq \(dq '/not installed/ {print $2}'
+Show all the optional dependencies of ffmpeg that are not currently installed.
+
+.TP
+.B cd /usr/pkgmk/packages && comm -23 <(ls *.pkg.tar.gz) <(prt-get printf '%i,%n#%v-%r.pkg.tar.gz\en' | awk \-v FS=, '/^(yes|diff)/ {print $2}') | xargs rm
+A one-liner that uses similar logic as \fBoldfiles(1)\fP to find
+all the out-of-date packages in a central directory, and delete them. 
+Note that \fBoldfiles(1)\fP performs other cleanup jobs that cannot be
+accomplished with such a concise one-liner; those jobs that rely on descending
+into the port collections and reading each manifest of sources.
+
+.TP 
+.B prt\-get search \-\-regex '^(m|n|p)c.*'
 Return a list of all ports whose names start with "mc", "nc", or "pc"
 
 .TP
@@ -660,7 +690,7 @@ mission-critical system.\fP
 (adapted from a comment by Fun) After updating your ports tree, print out a list of dependencies
 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.
+suitable for piping to \fBxargs prt\-get install\fP.
 
 .TP
 .B prt\-get isinst $(prt\-get quickdep $(prt\-get quickdiff)) | awk '/is installed/ {print $2}'
@@ -668,12 +698,21 @@ Same as above, but only print the dependencies that are already installed. The o
 command is suitable for piping to \fBxargs prt\-get update\fP.
 
 .TP
-.B prt\-get printf \(dq%p\et%u\en\(dq | grep myrepo | cut -f 2
+.B comm -3 <(prt\-get printf \(dq%i:%n %v-%r\en\(dq | grep -v ^no | cut -d: -f2 | sort) <(pkginfo -i | sort)
-Print the upstream URL for each port in the collection \(dqmyrepo\(dq, perhaps as the first step in
+(inspired by a bug report from teodor) an alternative to \fBprt\-get diff\fP.
-keeping your personal overlay up to date.
+In the output, left-justified lines show the version available in the
+repositories, while indented lines show the version installed. On a
+reasonably up-to-date system, the two processes in the above command will
+return many identical lines; these are suppressed by the -3 flag to
+\fBcomm(1)\fP.
 
 .TP
-.B prt\-get printf \(dq%M\et%n\en\(dq | grep ^Tim | wc -l
+.B prt\-get printf \(dq%p\et%u\en\(dq | awk '($1 ~ /\e/myrepo$/) { print $2 }'
+Print the upstream URL for each port in the collection \(dqmyrepo\(dq, perhaps 
+as the first step in keeping your personal overlay up to date.
+
+.TP
+.B prt\-get printf \(dq%M\et%n\en\(dq | grep -c ^Tim
 Count how many ports our most-overworked core team member claims responsibility for.
 
 .TP 
@@ -682,15 +721,15 @@ Find the build-time dependencies of firefox. Runtime dependencies would also app
 the first process substitution, and \fBcomm -13\fP will suppress what the two lists have in common.
 
 .TP
-.B prt-get listinst \-\-depsort | xargs prt-get grpinst \-\-install\-root=/mnt
+.B prt-get listinst \-\-depsort | xargs prt-get install \-\-install\-root=/mnt
 Sort the list of installed packages by dependencies, and then install all
 those packages onto a backup filesystem (mounted at /mnt). If you have a customized
 pkgadd.conf that you want applied to this operation, either copy it to 
 /mnt/etc where pkgadd will be looking for it, or pass the additional option \-\-aargs=\(dq\-c
-/etc/pkgadd.conf\(dq to the grpinst command.
+/etc/pkgadd.conf\(dq to the install command.
 
 .TP
-.B  prt-get list --path --regex '^xorg.*' | grep -v "/usr/ports/xorg"
+.B  prt-get list --path --regex '^xorg.*' | grep -v \(dq/usr/ports/xorg\(dq
 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.)
 

scripts/prt-auf

@@ -136,8 +136,8 @@ if (($action =~ /^(listinst|listorphans|dependent)/)
 		next if (! $dep);
 		if ($action ne "quickdep") {
 			$ind = (grep { $_ eq $dep } keys %V_INST) ? "[i]" : "[ ]";
-			$dep .= " $V_REPO{$dep}" if ($osearch{verbose}==1);
+			$dep .= " $V_REPO{$dep}" if (($osearch{verbose}==1) and ($V_REPO{$dep}));
-			$dep .= " $V_REPO{$dep}\n$DESC{$dep}" if ($osearch{verbose}>1);
+			$dep .= " $V_REPO{$dep}\n$DESC{$dep}" if (($osearch{verbose}>1) and ($V_REPO{$dep}) and ($DESC{$dep}));
 		}
 		printf $strf, $ind, $dep unless ($action eq "quickdep");
 		printf "%s ", $dep if ($action eq "quickdep");
@@ -534,7 +534,7 @@ sub port_unlock {
   open (LL, '>', $prtlocker."-tmp");
   foreach my $nl (@newlocks) { print LL "$nl\n" unless $nl =~ /^\s*$/; }
   close (LL);
-  system ("mv",$prtlocker."-tmp",$prtlocker);
+  rename ($prtlocker."-tmp",$prtlocker);
 }
 
 sub list_ports {
@@ -572,7 +572,7 @@ sub list_ports {
         my %not_orphans = map { $_ => 0 } @searchspace;
         foreach my $port (@searchspace) {
             map { $not_orphans{$_} = 1 } split(/[ ,]+/, $DEPENDS{$port});
-            if ($odepends{soft} == 1) {
+            if (($odepends{soft} == 1) and ($SOFTDEPS{$port})) {
                 map { $not_orphans{$_} = 1 } split(/[ ,]+/, $SOFTDEPS{$port});
             }
         }
@@ -595,16 +595,20 @@ sub list_ports {
         ($odepends{tree} == 0) or print "$header\n";
 
         our $indent="  "; our $height=0;
-        our $ind; our %seen; our @lineage; my @fosters=();
+        our $ind; our %seen; our @lineage; my @fosters=(); my @children=();
         $ind = ($V_INST{$seed}) ? "[i]" : "[ ]";
         print "$ind $seed\n" if ($odepends{tree}==1);
         $seen{$seed} = 1;
-        my @children = ($direction eq "fwd") ? split /[ ,]+/, $DEPENDS{$sseed}:
+	if ($direction eq "rev") {
-        grep { " $DEPENDS{$_} " =~ / $sseed / } @searchspace;
+		@children = grep { " $DEPENDS{$_} " =~ / $sseed / } @searchspace;
-        if ($odepends{soft}==1) {
+	} elsif ($DEPENDS{$sseed}) {
-            @fosters = ($direction eq "fwd") ?
+		@children = split /[ ,]+/, $DEPENDS{$sseed};
-            grep { ($V_INST{$_}) } split /[ ,]+/, $SOFTDEPS{$sseed}:
+	}
-            grep { " $SOFTDEPS{$_} " =~ / $sseed / } @searchspace;
+        
+        if (($odepends{soft}==1) and ($direction eq "rev")) {
+            @fosters = grep { " $SOFTDEPS{$_} " =~ / $sseed / } @searchspace;
+        } elsif (($odepends{soft}==1) and ($SOFTDEPS{$sseed})) {
+            @fosters = grep { ($V_INST{$_}) } split /[ ,]+/, $SOFTDEPS{$sseed};
     	}
 
         foreach my $sd (@children) { recurse_tree(0,$sd,$direction); }
@@ -612,21 +616,24 @@ sub list_ports {
 
         sub recurse_tree {
             my $greedy = shift; my $s = shift; my $direction=shift;
+	    my %curdeps=(); my @optionals=();
             my $ps = (($seen{$s}) and ($odepends{all} !=1)) ? "-->\n" : "\n";
             $ind = ($V_INST{$s}) ? "[i]" : "[ ]";
             $ind = (($ind eq "[i]") and ($greedy)) ? "[s]" : $ind;
             print $ind.(${indent}x(1+$height))."$s".$ps if ($odepends{tree}==1);
             return if (($seen{$s}) and ($odepends{all} !=1));
             $seen{$s} = 1;
-            my %curdeps = ($direction eq "fwd") ?
+	    if ($direction eq "rev") {
-            map {$_ => 0} split /[ ,]+/, $DEPENDS{$s} :
+	        %curdeps = map {$_ => 0} grep { " $DEPENDS{$_} " =~ / $s / } @searchspace;
-            map {$_ => 0} grep { " $DEPENDS{$_} " =~ / $s / } @searchspace;
+    	    } elsif ($DEPENDS{$s}) {
-            if ($odepends{soft} == 1) {
+	        %curdeps = map {$_ => 0} split /[ ,]+/, $DEPENDS{$s};
-                my @optionals = ($direction eq "fwd") ?
-                   grep { ($V_INST{$_}) } split /[ ,]+/, $SOFTDEPS{$s} :
-                   grep { " $SOFTDEPS{$_} " =~ / $s / } @searchspace;
-                map {$curdeps{$_} = 1} @optionals;
 	    }
+            if (($odepends{soft}==1) and ($direction eq "rev")) {
+	        @optionals = grep { " $SOFTDEPS{$_} " =~ / $s / } @searchspace;
+	    } elsif (($odepends{soft}==1) and ($SOFTDEPS{$s})) {
+                @optionals = grep { ($V_INST{$_}) } split /[ ,]+/, $SOFTDEPS{$s};
+            }
+            map {$curdeps{$_} = 1} @optionals;
 
             foreach my $dc (keys %curdeps) {
                 if (grep /^$dc$/, @lineage) {
@@ -717,11 +724,11 @@ sub deporder { # returns a sorted list of packages required.
       push(@treewalk, $s); $imark{$s}=1;
 
       # assemble the list of dependencies that must be visited next
-      %curdeps = map { $_ => $greedy } split /[ ,]+/, $DEPENDS{$s};
+      (! $DEPENDS{$s}) or %curdeps = map { $_ => $greedy } split /[ ,]+/, $DEPENDS{$s};
 
       # if the user toggles --softdeps, consider the optional dependencies 
       # that are already installed or are given on the command line
-      if ($odepends{soft} == 1)  {
+      if (($odepends{soft} == 1) and ($SOFTDEPS{$s}))  {
           foreach (grep { ($V_INST{$_}) or ($given{$_}) } 
           split /[ ,]+/, $SOFTDEPS{$s}) { $curdeps{$_} = 1; }
       }