--- portsnap.8.orig	2006-05-26 23:21:29 UTC
+++ portsnap.8
@@ -23,9 +23,9 @@
 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.\" $FreeBSD: src/usr.sbin/portsnap/portsnap/portsnap.8,v 1.9 2006/05/13 18:04:48 cperciva Exp $
+.\" $FreeBSD$
 .\"
-.Dd August 13, 2005
+.Dd July 1, 2018
 .Dt PORTSNAP 8
 .Os FreeBSD
 .Sh NAME
@@ -50,20 +50,25 @@ of the
 .Fx
 ports tree, and extract and update an
 uncompressed ports tree.
+.Pp
+In a normal update operation,
+.Nm
+will routinely restore modified files to their unmodified state and
+delete unrecognized local files.
 .Sh OPTIONS
 The following options are supported:
 .Bl -tag -width "-f conffile"
 .It Fl d Ar workdir
-Store working files (e.g. downloaded updates) in
+Store working files (e.g.\& downloaded updates) in
 .Ar workdir .
 (default:
-.Pa $PREFIX/portsnap ,
+.Pa /var/db/portsnap ,
 or as given in the configuration file.)
 .It Fl f Ar conffile
-Read the configuration from from
+Read the configuration from
 .Ar conffile .
 (default:
-.Pa $PREFIX/etc/portsnap.conf )
+.Pa %%PREFIX%%/etc/portsnap.conf )
 .It Fl I
 For the
 .Cm update
@@ -72,7 +77,7 @@ command, update INDEX files, but not the rest of the p
 Expect a public key with given SHA256 hash.
 (default: read value from configuration file.)
 .It Fl l Ar descfile
-Merge the specified local describes file into the INDEX files being 
+Merge the specified local describes file into the INDEX files being
 built.
 The
 .Ar descfile
@@ -88,25 +93,30 @@ operate on the directory
 or as given in the configuration file.)
 .It Fl s Ar server
 Fetch files from the specified server or server pool.
-(default: portsnap.FreeBSD.org , or as given in the
+(default: portsnap.FreeBSD.org, or as given in the
 configuration file.)
 .It path
 For
 .Cm extract
 command only, operate only on parts of the ports tree starting with
 .Ar path .
-(e.g.
+(e.g.\&
 .Nm
-.cm extract
+.Cm extract
 .Ar sysutils/port
 would extract sysutils/portsman, sysutils/portsnap,
 sysutils/portupgrade, etc.)
+.It Fl Fl interactive
+override auto-detection of calling process.
+Only use this when calling portsnap from an
+.Sy interactive, non-terminal application.
+(Cron jobs are particularly bad since they cause
+load spikes on the Portsnap mirrors.)
 .El
 .Sh COMMANDS
 The
 .Cm command
 can be any one of the following:
-.Pp
 .Bl -tag -width "-f conffile"
 .It fetch
 Fetch a compressed snapshot of the ports tree, or update
@@ -151,21 +161,52 @@ or
 commands.
 Again, note that in the parts of the ports tree which are being
 updated, any local changes or additions will be removed.
+.It auto
+Run
+.Cm fetch
+or
+.Cm cron
+depending on whether stdin is a terminal; then run
+.Cm update
+or
+.Cm extract
+depending on whether
+.Ar portsdir
+exists.
 .El
 .Sh TIPS
 .Bl -bullet
 .It
 If your clock is set to local time, adding the line
 .Pp
-.Dl 0 3 * * * root /usr/local/sbin/portsnap cron
+.Dl 0 3 * * * root %%PREFIX%%/sbin/portsnap cron
 .Pp
-to /etc/crontab is a good way to make sure you always have
+to
+.Pa /etc/crontab
+is a good way to make sure you always have
 an up-to-date snapshot of the ports tree available which
 can quickly be extracted into
 .Pa /usr/ports .
 If your clock is set to UTC, please pick a random time other
 than 3AM, to avoid overly imposing an uneven load on the
 server(s) hosting the snapshots.
+.Pp
+Note that running
+.Nm
+.Cm cron
+or
+.Nm
+.Cm fetch
+does not apply the changes that were received: they only download
+them.
+To apply the changes, you must follow these commands with
+.Nm
+.Cm update .
+The
+.Nm
+.Cm update
+command is normally run by hand at a time when you are sure that
+no one is manually working in the ports tree.
 .It
 Running
 .Nm
@@ -183,7 +224,7 @@ However, running
 .Fl I
 .Cm update
 is probably safe, and can be used together with
-.Xr portversion 1
+.Xr pkg-version 8
 to identify installed software which is out of date.
 .It
 If you wish to use
@@ -206,22 +247,22 @@ of files are not needed by any particular client.
 .Sh PRIVACY NOTICE
 As an unavoidable part of its operation, a machine running
 .Nm
-will make its public IP address and the list of files it fetches 
+will make its public IP address and the list of files it fetches
 available to the server from which it fetches updates.
-Using these it may be possible to recognize a machine over an extended 
-period of time, determine when it is updated, and identify which 
-portions of the FreeBSD ports tree, if any, are being ignored using 
+Using these it may be possible to recognize a machine over an extended
+period of time, determine when it is updated, and identify which
+portions of the FreeBSD ports tree, if any, are being ignored using
 "REFUSE" directives in
 .Pa portsnap.conf .
 .Pp
-Statistical data generated from information collected in this manner 
+Statistical data generated from information collected in this manner
 may be published, but only in aggregate and after anonymizing the
 individual systems.
 .Sh FILES
-.Bl -tag -width "$PREFIX/etc/portsnap.conf"
-.It $PREFIX/etc/portsnap.conf
+.Bl -tag -width "%%PREFIX%%/etc/portsnap.conf"
+.It %%PREFIX%%/etc/portsnap.conf
 Default location of the portsnap configuration file.
-.It $PREFIX/portsnap
+.It /var/db//portsnap
 Default location where compressed snapshots are stored.
 .It /usr/ports
 Default location where the ports tree is extracted.