prt-auf.8: moved the discussion of 'dup' closer to related commands

man8/prt-auf.8

@@ -54,10 +54,10 @@ offers an essentially identical user experience.
 
 .PP 
 
-prt\-auf lets you search for ports by name, find information about ports
+prt\-auf automates the process of tracking down dependencies of the ports you
-(without installing them of course), or print the dependencies of a port (as
+want to install. The result of these recursive calculations can be printed as
 a space- or newline-separated list, or with indentation to represent the
-tree structure). Note that prt\-auf trusts the port maintainer to provide an
+tree structure. Note that prt\-auf trusts the port maintainer to provide an
 accurate list of dependencies; if this list is incomplete for any of the
 ports in your collections, the build might fail.
 
@@ -88,6 +88,12 @@ line, in which case prt-auf will bring it up to date. If there have been major
 version changes in shared libraries since your last update, it might be advisable to
 run 'prt-auf update' instead.
 
+.TP 
+.B depinst [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
+essentially a synonym for \fBinstall\fP. This subcommand is provided for the
+convenience of long-time \fBprt\-get\fP users, who might find it
+counterintuitive to see automatic dependency resolution with \fBinstall\fP.
+
 .TP 
 .B update [\-\-margs=] [\-\-aargs=] <package1> [<package2> ...]
 bring all the listed packages and their dependencies up to date. Among 'install', 'update',
@@ -116,20 +122,13 @@ and \fBprt\-auf\fP will clean up the -r switch so that \fBpkgrm\fP(8) does what
 
 .TP 
 .B sysup
-Update all installed packages which are outdated.
+Update all installed packages which are outdated and not locked.
-
-.TP
-.B lock
-and
-.B unlock
-These commands allow you to keep the currently installed versions, even if there are
-changes in the ports tree.
 
 .TP 
 .B lock <package1> [<package2>...]
-Do not update these packages in a
+Exempt these packages from any subsequent
 .B sysup
-operation
+operation (i.e., keep them at their currently-installed version)
 
 .TP 
 .B unlock <package1> [<package2>...] 
@@ -141,12 +140,12 @@ List names of packages which are locked.
 
 .TP 
 .B diff [--all]
-show differences between installed packages and ports in the ports
+Show differences between installed packages and ports in the ports
 tree. Locked packages are only displayed if you use the --all switch.
 
 .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.
 
 .TP 
@@ -188,6 +187,14 @@ Print the path of a port
 .B readme <port>
 Print the port's README file if it exists
 
+.SH ""
+
+The subcommands 'info', 'path', and 'readme' expect as their argument an exact match for one of the
+ports in the active repositories. If you are not sure that a port by that name exists, you should
+first use 'search', 'dsearch', or 'fsearch' to generate a list of possible arguments. The info or
+readme will come from the highest-priority port in the active repositories (the same port that would
+be built by an 'install' command).
+
 .TP 
 .B depends <package1> [<package2> ...]
 print a recursive list of dependencies needed to install the packages passed
@@ -211,7 +218,7 @@ builds.
 
 .TP 
 .B deptree <package>
-print a tree of the dependencies of the package
+print a tree of the dependencies of 
 .B package. 
 
 .SH ""
@@ -239,6 +246,27 @@ add the --all switch; use --recursive to get a recursive list (without duplicati
 and --tree to get a nicely indented one (note that --tree implies
 --recursive).
 
+.TP
+.B ls [--path] <port>
+Prints out a listing of the port's directory
+
+.TP
+.B cat <port> [<file>]
+Prints out the file to stdout. If <file> is not specified, 'Pkgfile' is used.
+
+.TP
+.B edit <port> [<file>]
+Edit the file using the editor specified in the $EDITOR environment variable.
+If <file> is not specified, 'Pkgfile' is used.
+
+.SH ""
+Similar to 'info', 'path', and 'readme', a non-exhaustive search is performed to satisfy
+an 'edit', 'cat', or 'ls' command. This behaviour ensures that your edits or directory listings
+pertain to the port that would be built by a 'prt-auf install' command. Meanwhile, 'prt-auf dup'
+will let you know if any port in the active repositories is hidden by another port of the same name,
+but the 'dup' command offers convenient access to only some of the fields that 'info' or 'readme'
+would print.
+
 .TP 
 .B dup [format string]
 List ports which can be found in multiple directories configured in
@@ -333,10 +361,8 @@ 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 (note that "\\n" is appended to your
+Use "\\n" and "\\t" to format your output. To restrict the list to package names
-format specifier automatically). To restrict the list to package names
+matching a desired pattern, you can specify \fB<filter>\fP.
-matching a desired pattern, you can specify
-.B filter
 Metacharacters in the filter are only respected if you pass the --regex option,
 in which case your filter should be a Perl-compatible regular expression.
 
@@ -369,34 +395,21 @@ all packages given as argument are installed, otherwise a return value greater t
 
 .TP
 .B current <package1> [<package2> ...]
-Shows the currently-installed version of <package1>, or a message
+Show the currently-installed version of <package1>, or a message
 that <package1> is not installed. Also takes more than one package as
 argument.
 
-.TP
-.B ls [--path] <port>
-Prints out a listing of the port's directory
-
-.TP
-.B cat <port> [<file>]
-Prints out the file to stdout. If <file> is not specified, 'Pkgfile' is used. If set, uses $PAGER.
-
-.TP
-.B edit <port> [<file>]
-Edit the file using the editor specified in the $EDITOR environment variable.
-If <file> is not specified, 'Pkgfile' is used.
-
 .TP 
 .B help
-Shows a help screen
+Show a help screen
 
 .TP 
 .B version 
-Shows the current version of prt\-auf
+Show the current version of prt\-auf
 
 .TP 
 .B cache
-create a cache file from the ports tree, which will be used whenever \fBprt\-auf\fP
+Create a cache file from the ports tree, which will be used whenever \fBprt\-auf\fP
 is invoked with the --cache option. Remember to run \fBprt\-auf cache\fP each time
 you update the ports tree, or automate this step by appending a line to the
 \fBports\fP(8) script. If you invoke \fBprt\-auf\fP from a symbolic link that ends
@@ -410,45 +423,49 @@ fully compatible with those generated by \fBprt\-get\fP(8).
 The following options are primarily useful for install/update transactions.
 
 .TP
-.B -fr
+.B \-\-test
+Do not actually run pkgmk/pkgadd/pkgrm, just print the commands that would have run
+
+.TP
+.B \-fr
 Force rebuild, Implies 'pkgmk -f'; same as --margs=-f
 
 .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 
 .B \-\-margs="...", e.g. \-\-margs="\-im"
-additional arguments to be passed to pkgmk;
+Pass these additional arguments to pkgmk;
-note that \-d is already passed to pkgmk anyway
+note that \-d is already passed to pkgmk anyway.
 
 .TP 
 .B \-\-aargs="...", e.g. \-\-aargs="\-f"
-additional arguments to be passed to pkgadd
+Pass these additional arguments to pkgadd
 
 .TP 
 .B \-\-cache
-Use cache file for this command.
+Use cache file for this command
 
 .SH ""
 
@@ -472,12 +489,16 @@ Interpret filter and search pattern as regular expression
 
 Most of the directives available in prt\-get.conf(5) are also recognized and
 respected by \fBprt\-auf\fP. Notably, you can specify the active port
-collections by ensuring that they appear on lines beginning with 'prtdir '.
+collections by ensuring that they appear on lines beginning with 'prtdir '. 
 You can also toggle the running of pre-/post-install scripts by editing the
 line that contains 'runscripts'. You can specify alternatives to the
 default pkgutils programs ( /usr/bin/pkgmk, /usr/bin/pkgadd, and
 /usr/bin/pkgrm )
 by editing the lines for 'makecommand', 'addcommand', and 'removecommand', respectively.
+Lastly, you can control whether the pkgmk output is saved in a log file, using the directives 'writelog
+<enabled|disabled>', 'logmode <append|overwrite>', and 'logfile <path>'. The <path> in a 'logfile'
+directive can contain any of the variables "%n", "%v", "%r", and "%p", which are automatically
+replaced by the port's name, version, release, and full path in the ports tree, respectively.
 
 .SH "TECHNICAL DETAILS"
 
@@ -497,8 +518,8 @@ Some of these variables are initialized right away, but other variables are only
 initialized once the program knows the requested action.
 
 After all the arguments are parsed (and screened for validity), the hash maps \fI%opkg\fP,
-\fI%odepends\fP, and \fI%osearch\fP will retain in memory the user's desired settings. Then the
+\fI%odepends\fP, \fI%osearch\fP, and \fI%olog\fP will retain in memory the user's desired settings.
-relevant data structures are populated from the files on disk (the cache, if
+Then the relevant data structures are populated from the files on disk (the cache, if
 \-\-cache was passed on the command line, the database of installed packages in /var/lib/pkg,
 the list of locked ports, the list of aliases, or each \fBPkgfile\fP(5) found in the ports tree).
 
@@ -521,52 +542,49 @@ which can easily be incorporated at a later date. Long-time users of \fBprt\-get
 observe the following differences:
 .PP
 .TP 
-\ \ \ \(bu mixed install/update mode. Packages given on the command line can be present or not, and
+.B mixed install/update mode.
+Packages given on the command line can be present or not, and
 \fBprt\-auf\fP will figure out the right way to call \fBpkgadd\fP(8) for each one. The key
 distinction is that 'install' mode will not try to update an out-of-date package found in the
 dependency chain unless that package also appears on the command line.
 
 .TP 
-\ \ \ \(bu merged update and depinst. Both of these now resolve dependencies by default, as does
+.B merged install and depinst.
- 'install'. The original behaviour of \fBprt\-get install\fP can be approximated by the
+For the convenience of new users who might find it surprising to have an 'install' command fail due
- 'grpinst' action of \fBprt\-auf\fP, except that a 'grpinst' action will not proceed to the next
+to missing dependencies, the 'install' subcommand now does exactly what 'depinst' used to do in
+\fBprt\-get\fP. The original behaviour of \fBprt\-get install\fP can be approximated by
+the 'grpinst' action of \fBprt\-auf\fP, except that a 'grpinst' action will not proceed to the next
 package if a build fails.
 
-.TP 
+.TP
-\ \ \ \(bu no internal handling of build/install logs. This omission will be sorely missed by
+.B no version comparator.
-administrators of remote CRUX installations, who are unlikely to want to write their own
+One of the main reasons to run CRUX is to stay current with the latest stable versions endorsed by
-non-interactive script for cleaning up the redirected stdout of \fBprt\-auf\fP and organizing the
+the port maintainers. (They subscribe to the upstream mailing lists so you don't have to.) If you
-build logs that way. Once \fBprt\-auf\fP sees wider adoption beyond the handful of early testers who
+want to keep a particular piece of software at a different version than the one chosen by its
-find value in its approach to package management, the internal handling of build logs will be added.
+original maintainer, you can maintain a shadow port in your own overlay (and put that overlay higher
+in the config file).
 
 .TP
-\ \ \ \(bu no version comparator. One of the main reasons to run CRUX is to stay current with the
+.B no wildcards or shell globbing in the search commands.
-latest stable versions endorsed by the port maintainers. (They subscribe to the upstream mailing
+Being written in Perl, \fBprt\-auf\fP automatically inherits a rich set of routines for dealing with
-lists so you don't have to.) If you want to keep a particular piece of software at a different
+regular expressions. When paired with the case-insensitive pattern matching of purely-alphanumeric
-version than the one chosen by its original maintainer, you can maintain a shadow port in your own
+queries, the Perl regexp engine offers CRUX users enough flexibility to find any port they're
-overlay (and put that overlay higher in the config file).
+looking for, without needing to clutter the code base by reimplementing shell wildcards.
 
 .TP
-\ \ \ \(bu no wildcards or shell globbing in the search commands. Being written in Perl,
+.B no "--ignore" switch.
-\fBprt\-auf\fP automatically inherits a rich set of routines for dealing with regular expressions.
+This feature is easy enough to add at a later date, but a newcomer to CRUX will likely be confused
-When paired with the case-insensitive pattern matching of purely-alphanumeric queries, the Perl regexp
+at having such fine-grained control over the automatic dependency resolution. The two main reasons
-engine offers CRUX users enough flexibility to find any port they're looking for, without needing to
+to use "--ignore" (an erroneous "Depends on" line, or a satisfaction of the dependency by manual
-clutter the code base by reimplementing shell wildcards.
+installations that pkgutils is not aware of), are both more properly addressed by a long-term
+solution rather than a one-time fix. If the "Depends on" line is truly in error, the CRUX user
+should contact the port maintainer and get it fixed for everybody, rather than passing the
+"--ignore" option and letting the error go uncorrected. If the dependency was satisfied by a manual
+installation outside of pkgutils, a better response is to make a dummy port and create an entry in
+the aliases file. That way prt-auf will treat the dependency as satisfied for any subsequent
+installations on the same machine, and passing the "--ignore" option will be unnecessary for all
+future ports with the same dependency. The canonical example of a line in the aliases file is
 
-.TP
-\ \ \ \(bu no "--ignore" switch. This feature is easy enough to add at a later date, but a newcomer
-to CRUX will likely be confused at having such fine-grained control over the automatic dependency
-resolution. The two main reasons to use "--ignore" (an erroneous "Depends on" line, or a
-satisfaction of the dependency by manual installations that pkgutils is not aware of), are both more
-properly addressed by a long-term solution rather than a one-time fix. If the "Depends on" line is
-truly in error, the CRUX user should contact the port maintainer and get it fixed for everybody,
-rather than passing the "--ignore" option and letting the error go uncorrected. If the dependency
-was satisfied by a manual installation outside of pkgutils, a better response is to make a dummy
-port and create an entry in the aliases file. That way prt-auf will treat the dependency as
-satisfied for any subsequent installations on the same machine, and passing the "--ignore" option
-will be unnecessary for all future ports with the same dependency. The canonical example of a line
-in the aliases file is
-.TP
 \ \ \ \ \ rust-bin: rust
 
 which tells \fBprt\-auf\fP that an installed copy of rust-bin is sufficient to proceed with the