X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/agedu/blobdiff_plain/19199555f89d30bc913539850089ecafe64af043..HEAD:/agedu.but

diff --git a/agedu.but b/agedu.but
index 37cfdbf..eebb174 100644
--- a/agedu.but
+++ b/agedu.but
@@ -290,6 +290,16 @@ CGI scripts is assumed to be the job of the web server.
 
 }
 
+\dt \cw{-h} or \cw{--help}
+
+\dd Causes \cw{agedu} to print some help text and terminate
+immediately.
+
+\dt \cw{-V} or \cw{--version}
+
+\dd Causes \cw{agedu} to print its version number and terminate
+immediately.
+
 \U OPTIONS
 
 This section describes the various configuration options that affect
@@ -508,6 +518,17 @@ the web server mode \cw{-w}, the stand-alone HTML generation mode
 files in each directory, instead of just giving a combined report
 for everything that's not in a subdirectory.
 
+The following option affects the text report mode \cw{-t}.
+
+\dt \cw{-a} \e{age} or \cw{--age} \e{age}
+
+\dd This option tells \cw{agedu} to report only files of at least the
+specified age. An age is specified as a number, followed by one of
+\cq{y} (years), \cq{m} (months), \cq{w} (weeks) or \cq{d} (days).
+(This syntax is also used by the \cw{-r} option.) For example, \cw{-a
+6m} will produce a text report which includes only files at least six
+months old.
+
 The following options affect the stand-alone HTML generation mode
 \cw{-H} and the text report mode \cw{-t}.
 
@@ -544,8 +565,8 @@ mode, the argument is treated as the name of a directory: the
 directory will be created if it does not already exist, and the
 output HTML files will be created inside it.
 
-The following options affect the web server mode \cw{-w}, and in one
-case also the stand-alone HTML generation mode \cw{-H}:
+The following options affect the web server mode \cw{-w}, and in some
+cases also the stand-alone HTML generation mode \cw{-H}:
 
 \dt \cw{-r} \e{age range} or \cw{--age-range} \e{age range}
 
@@ -562,11 +583,11 @@ limits, and you can do this using \cw{-r}.
 The argument to \cw{-r} consists of a single age, or two ages
 separated by a minus sign. An age is a number, followed by one of
 \cq{y} (years), \cq{m} (months), \cq{w} (weeks) or \cq{d} (days).
-The first age in the range represents the oldest data, and will be
-coloured red in the HTML; the second age represents the newest,
-coloured green. If the second age is not specified, it will default
-to zero (so that green means data which has been accessed \e{just
-now}).
+(This syntax is also used by the \cw{-a} option.) The first age in the
+range represents the oldest data, and will be coloured red in the
+HTML; the second age represents the newest, coloured green. If the
+second age is not specified, it will default to zero (so that green
+means data which has been accessed \e{just now}).
 
 For example, \cw{-r 2y} will mark data in red if it has been unused
 for two years or more, and green if it has been accessed just now.
@@ -578,12 +599,11 @@ three months ago or later.
 
 \dt \cw{--address} \e{addr}[\cw{:}\e{port}]
 
-\dd Specifies the network address and port number on which
-\cw{agedu} should listen when running its web server. If you want
-\cw{agedu} to listen for connections coming in from any source, you
-should probably specify the special IP address \cw{0.0.0.0}. If the
-port number is omitted, an arbitrary unused port will be chosen for
-you and displayed.
+\dd Specifies the network address and port number on which \cw{agedu}
+should listen when running its web server. If you want \cw{agedu} to
+listen for connections coming in from any source, specify the address
+as the special value \cw{ANY}. If the port number is omitted, an
+arbitrary unused port will be chosen for you and displayed.
 
 \lcont{
 
@@ -651,6 +671,15 @@ consist of the username, followed by a colon, followed by the
 password, followed \e{immediately} by end of file (no trailing
 newline, or else it will be considered part of the password).
 
+\dt \cw{--title} \e{title}
+
+\dd Specify the string that appears at the start of the \cw{<title>}
+section of the output HTML pages. The default is \cq{agedu}. This
+title is followed by a colon and then the path you're viewing within
+the index file. You might use this option if you were serving
+\cw{agedu} reports for several different servers and wanted to make it
+clearer which one a user was looking at.
+
 \dt \cw{--no-eof}
 
 \dd Stop \cw{agedu} in web server mode from looking for end-of-file on
@@ -688,7 +717,18 @@ bothers re-reading it if it has; programs which do this include
 \cw{rsync}(\e{1}) and \cw{make}(\e{1}). Such programs will fail to
 update the atime of unmodified files despite depending on their
 continued existence; a directory full of such files will be reported
-as disused by \cw{agedu} but deleting them will cause trouble.
+as disused by \cw{agedu} even in situations where deleting them will
+cause trouble.
+
+Finally, of course, \cw{agedu}'s normal usage mode depends critically
+on the OS providing last-access times which are at least approximately
+right. So a file system mounted with Linux's \cq{noatime} option, or
+the equivalent on any other OS, will not give useful results!
+(However, the Linux mount option \cq{relatime}, which distributions
+now tend to use by default, should be fine for all but specialist
+purposes: it reduces the accuracy of last-access times so that they
+might be wrong by up to 24 hours, but if you're looking for files that
+have been unused for months or years, that's not a problem.)
 
 \U LICENCE