X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/agedu/blobdiff_plain/16139d213e135c0eeca149af4d425cfcef9d7bd4..a8a4d6d837f5029124d26483e4b3a390de69823e:/agedu.but diff --git a/agedu.but b/agedu.but index 3fc1a23..4e90a14 100644 --- a/agedu.but +++ b/agedu.but @@ -166,10 +166,11 @@ default it invents its own URL and prints it out. \lcont{ -The web server runs until \cw{agedu} receives an end-of-file event -on its standard input. (The expected usage is that you run it from -the command line, immediately browse web pages until you're -satisfied, and then press Ctrl-D.) +The web server runs until \cw{agedu} receives an end-of-file event on +its standard input. (The expected usage is that you run it from the +command line, immediately browse web pages until you're satisfied, and +then press Ctrl-D.) To disable the EOF behaviour, use the +\cw{--no-eof} option. In case the index file contains any confidential information about your file system, the web server protects the pages it serves from @@ -190,10 +191,10 @@ completely) and a username and password of your choice. \dd In this mode, \cw{agedu} generates a textual report on standard output, listing the disk usage in the specified directory and all -its subdirectories down to a fixed depth. By default that depth is +its subdirectories down to a given depth. By default that depth is 1, so that you see a report for \e{directory} itself and all of its -immediate subdirectories. You can configure a different depth using -\cw{-d}, described in the next section. +immediate subdirectories. You can configure a different depth (or no +depth limit) using \cw{-d}, described in the next section. \lcont{ @@ -257,9 +258,37 @@ for further detail.) \dd In this mode, \cw{agedu} will generate an HTML report of the disk usage in the specified directory and its immediate subdirectories, in the same form that it serves from its web server -in \cw{-w} mode. However, this time, a single HTML report will be -generated and simply written to standard output, with no hyperlinks -pointing to other similar pages. +in \cw{-w} mode. + +\lcont{ + +By default, a single HTML report will be generated and simply +written to standard output, with no hyperlinks pointing to other +similar pages. If you also specify the \cw{-d} option (see below), +\cw{agedu} will instead write out a collection of HTML files with +hyperlinks between them, and call the top-level file +\cw{index.html}. + +} + +\dt \cw{--cgi} + +\dd In this mode, \cw{agedu} will run as the bulk of a CGI script +which provides the same set of web pages as the built-in web server +would. It will read the usual CGI environment variables, and write +CGI-style data to its standard output. + +\lcont{ + +The actual CGI program itself should be a tiny wrapper around +\cw{agedu} which passes it the \cw{--cgi} option, and also +(probably) \cw{-f} to locate the index file. \cw{agedu} will do +everything else. + +No access control is performed in this mode: restricting access to +CGI scripts is assumed to be the job of the web server. + +} \U OPTIONS @@ -467,6 +496,42 @@ 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 options affect the stand-alone HTML generation mode +\cw{-H} and the text report mode \cw{-t}. + +\dt \cw{-d} \e{depth} or \cw{--depth} \e{depth} + +\dd This option controls the maximum depth to which \cw{agedu} +recurses when generating a text or HTML report. + +\lcont{ + +In text mode, the default is 1, meaning that the report will include +the directory given on the command line and all of its immediate +subdirectories. A depth of two includes another level below that, +and so on; a depth of zero means \e{only} the directory on the +command line. + +In HTML mode, specifying this option switches \cw{agedu} from +writing out a single HTML file to writing out multiple files which +link to each other. A depth of 1 means \cw{agedu} will write out an +HTML file for the given directory and also one for each of its +immediate subdirectories. + +If you want \cw{agedu} to recurse as deeply as possible, give the +special word \cq{max} as an argument to \cw{-d}. + +} + +\dt \cw{-o} \e{filename} or \cw{--output} \e{filename} + +\dd This option is used to specify an output file for \cw{agedu} to +write its report to. In text mode or single-file HTML mode, the +argument is treated as the name of a file. In multiple-file HTML +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}: @@ -574,6 +639,11 @@ 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{--no-eof} + +\dd Stop \cw{agedu} in web server mode from looking for end-of-file on +standard input and treating it as a signal to terminate. + \U LIMITATIONS The data file is pretty large. The core of \cw{agedu} is the @@ -596,6 +666,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