Corrections: put trailing slash on URL, and adjust svn:ignore.

[sgt/agedu] / agedu.but

diff --git a/agedu.but b/agedu.but
index f4fdb1d..1494140 100644 (file)
--- a/agedu.but
+++ b/agedu.but
@@ -6,8 +6,8 @@
 
 \U NAME
 
-\cw{agedu} - correlate disk usage with last-access times to identify
-large and disused data
+\cw{agedu} \dash correlate disk usage with last-access times to
+identify large and disused data
 
 \U SYNOPSIS
 
@@ -65,7 +65,7 @@ mode:
 which will print (among other messages) a URL on its standard output
 along the lines of
 
-\c URL: http://127.164.152.163:48638/
+\c URL: http://127.0.0.1:48638/
 
 (That URL will always begin with \cq{127.}, meaning that it's in the
 \cw{localhost} address space. So only processes running on the same
@@ -457,8 +457,18 @@ things as disused when they're not, so you will have more candidates
 to go through by hand looking for data you don't need), but may be
 better than nothing if your last-access times are unhelpful.
 
+The following option affects all the modes that generate reports:
+the web server mode \cw{-w}, the stand-alone HTML generation mode
+\cw{-H} and the text report mode \cw{-t}.
+
+\dt \cw{--files}
+
+\dd This option causes \cw{agedu}'s reports to list the individual
+files in each directory, instead of just giving a combined report
+for everything that's not in a subdirectory.
+
 The following options affect the web server mode \cw{-w}, and in one
-case also the stand-along HTML generation mode \cw{-H}:
+case also the stand-alone HTML generation mode \cw{-H}:
 
 \dt \cw{-r} \e{age range} or \cw{--age-range} \e{age range}
 
@@ -574,7 +584,7 @@ expect; a scan of my own home directory, containing half a million
 files and directories and about 20Gb of data, produced an index file
 over 60Mb in size. Furthermore, since the data file must be
 memory-mapped during most processing, it can never grow larger than
-available address space, so a \em{really} big filesystem may need to
+available address space, so a \e{really} big filesystem may need to
 be indexed on a 64-bit computer. (This is one reason for the
 existence of the \cw{-D} and \cw{-L} options: you can do the
 scanning on the machine with access to the filesystem, and the
@@ -586,6 +596,18 @@ willingness to do additional coding \dash to run a system-wide
 \cw{agedu} scan on a \cw{cron} job and serve the right subset of
 reports to each user.
 
+In certain circumstances, \cw{agedu} can report false positives
+(reporting files as disused which are in fact in use) as well as the
+more benign false negatives (reporting files as in use which are
+not). This arises when a file is, semantically speaking, \q{read}
+without actually being physically \e{read}. Typically this occurs
+when a program checks whether the file's mtime has changed and only
+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.
+
 \U LICENCE
 
 \cw{agedu} is free software, distributed under the MIT licence. Type