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

[sgt/agedu] / agedu.but

diff --git a/agedu.but b/agedu.but
index 3eb481a..1494140 100644 (file)
--- a/agedu.but
+++ b/agedu.but
@@ -6,8 +6,8 @@
 
 \U NAME
 
 
 \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
 
 
 \U SYNOPSIS
 


@@ -65,7 +65,7 @@ mode:
 which will print (among other messages) a URL on its standard output
 along the lines of
 
 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
 
 (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


@@ -443,8 +443,32 @@ complexity.)
 
 }
 
 
 }
 

+\dt \cw{--mtime}
+
+\dd This option causes \cw{agedu} to index files by their last
+modification time instead of their last access time. You might want
+to use this if your last access times were completely useless for
+some reason: for example, if you had recently searched every file on
+your system, the system would have lost all the information about
+what files you hadn't recently accessed before then. Using this
+option is liable to be less effective at finding genuinely wasted
+space than the normal mode (that is, it will be more likely to flag
+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
 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}
 
 
 \dt \cw{-r} \e{age range} or \cw{--age-range} \e{age range}
 


@@ -481,8 +505,8 @@ three months ago or later.
 \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
 \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, it will be assumed to be 80 (for which
-\cw{agedu} will probably need to be running as a privileged user).
+port number is omitted, an arbitrary unused port will be chosen for
+you and displayed.

 
 \lcont{
 
 
 \lcont{
 


@@ -558,11 +582,13 @@ efficiently perform the queries it needs; this data structure
 requires \cw{O(N log N)} storage. This is larger than you might
 expect; a scan of my own home directory, containing half a million
 files and directories and about 20Gb of data, produced an index file
 requires \cw{O(N log N)} storage. This is larger than you might
 expect; a scan of my own home directory, containing half a million
 files and directories and about 20Gb of data, produced an index file

-nearly a third of a Gb in size. Furthermore, since the data file
-must be memory-mapped during most processing, it can never grow
-larger than available address space, which means that any use of
-\cw{agedu} on a file system more than about ten times the above size
-is probably going to have to be done on a 64-bit computer.
+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 \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
+indexing on a machine big enough to handle it.)

 
 The data structure also does not usefully permit access control
 within the data file, so it would be difficult \dash even given the
 
 The data structure also does not usefully permit access control
 within the data file, so it would be difficult \dash even given the


@@ -570,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.
 
 \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
 \U LICENCE
 
 \cw{agedu} is free software, distributed under the MIT licence. Type