bring on more tildes hopefully

api/recently-updated/README.md

@@ -1,40 +1,46 @@
-# Recently-Updated Page Shell Scripts
+# Recently updated pages: retained implementations
 
-As soon as [~ford](http://tilde.club/~ford) granted me entrance to tilde.Club, I knew that I wanted to keep tabs on what cool things folks were doing there. And thinking back to the mid-90s, what was the best way to know what was new on a site? A recently-updated page! So I set about making one for tilde.club.
+These scripts are kept so existing users do not lose the programs or old paths.
+They are historical implementations, not a tested production installation
+recipe. The maintained deployment source must be chosen and reviewed separately;
+there is also [tildeclub/recently-updated](https://github.com/tildeclub/recently-updated).
 
-There's no question at all that this is a rudimentary hack, but it's the *exact* sort of hack that was The Way To Do Things on the mid-90s Internet. (Note that that's the mid-90s-capital-I-Internet, not the [21st-century-lowercase-i-internet](http://www.nytimes.com/2002/12/29/weekinreview/29SCHW.html).) And I'm using tried-and-true command-line Unix filesystem commands to grab, parse, and sort the list of pages, so I feel like I'm treading in the footsteps of thousands before me. The result is [the list of all tilde.club pages updated in the last 24 hours](http://tilde.club/~delfuego/tilde.24h.html), which is generated from the ```findmod.sh``` shell script once a minute from a crontab job.
+## Files and interfaces
 
-Of course, while the HTML version of the recently-updated list is firmly mid-90s (well, if you view source you'll see that it's 21st-century HTML5, but still), enabling cooler 21st-century functionality required making the same list available in a more easily-parsed format. Enter JSON, and the [API version of the recently-updated list](http://tilde.club/~delfuego/tilde.24h.json), generated by the ```findmod-json.sh``` shell script once a minute via crontab as well.
+| File | Behavior |
+| --- | --- |
+| `findmod.sh` | Writes HTML to stdout for recently changed top-level `index.html` files. |
+| `findmod-json.sh` | Writes a JSON-like `pagelist` response to stdout for the same index scan. |
+| `findmod2.pl` | Scans each public subtree and writes both HTML and JSON output files. |
+| `header.tpl`, `footer.tpl` | HTML fragments used by the original shell implementation's external template paths. |
 
-Hope these are useful to someone!
+The original shell script hard-codes template paths in another user's home and
+an HTTP domain. Configure a reviewed copy for your own domain and deployment
+path rather than creating that person's home layout on a new host.
 
-Jason Levine, aka [~delfuego](http://tilde.club/~delfuego)
+The Perl program accepts `--domain`, `--root`, `--since-hours`, `--destdir`,
+`--update-every`, `--verbose`, and `--help`. Its default window is 24 hours and
+its output names are `tilde.24h.html` and `tilde.24h.json` (with the chosen hour
+count substituted). A positive update period makes it keep rescanning.
 
+## Limitations to fix before deployment
 
-# Recently-Updated Page Perl Script
+The retained implementations concatenate strings instead of safely serializing
+all output. The Perl JSON writer includes a trailing comma, so its nonempty JSON
+output is invalid. HTML escaping and URL encoding also need review. Filesystem
+names must not be trusted as markup, and timestamps labeled UTC must actually
+be generated in UTC. The shell regex also restricts which usernames it finds.
 
-`findmod2.pl` is a pure-Perl5 reimplementation of ~delfuego's scripts.
-It's self-contained, readable, well-documented and will search a
-user's entire `public_html` subtree for the most recent file rather
-than just using the date of the `index.html` file.
+The tree scanner can traverse large user-controlled public trees. Define bounds,
+symlink handling, public-file eligibility, error handling, and exclusion policy.
+Run with read access only to intended public content; running it as root can
+publish information about files the web server itself cannot read.
 
-It accepts the following command-lines options:
+For a deployment, validate JSON with `python3 -m json.tool`, check HTML and URLs,
+write to a private temporary file on the destination filesystem, and rename the
+validated output into place. Do not truncate the live page at the start of a
+scan or repeatedly publish partial files from overlapping jobs.
 
-* --domain *name*           -- Domain name for the site.  Guesses if omitted.
-* --root *url*              -- Root URL to use in links.  Derived from domain by default.
-* --since-hours *hours*     -- Number of hours considered recent. Default = 24.
-* --destdir *path*          -- Destination directory for output files.
-* --update-every *seconds*  -- Regenerate the lists every *seconds*.
-* --verbose                 -- Print more information as the program runs.
-* --help                    -- Print a simple help message and exit.
-
-If `--update-every` is given with a positive number, `findmod2.pl`
-will loop forever, waiting the given number of seconds before
-rescanning and regenerating the list.  Otherwise, it will scan once
-and exit.
-
-The output files are named `tilde.XXh.json` and `tilde.XXh.html`,
-where *XX* is replaced by number of hours considered recent (24 or the
-argument given with `--since-hours`).
-
-Chris Reuter, [~suetanvil](http://totallynuclear.club/~suetanvil).
+The original scripts were contributed by Jason Levine (~delfuego) and Chris
+Reuter (~suetanvil). Their interfaces and code are preserved by this docs update;
+no claim is made that they have been repaired or replaced here.