Re: [9fans] Creating new documents on KFS, Fossil,

[geoff@collyer.net]

There is a third possibility: the person who updates the code updates
the corresponding paper, if any.  This seems to be part of 1127's
tradition that the person who writes the code writes the
documentation.  It makes sense, the programmer knows better than
anyone the details of the program.  Having someone else do it can
lead, in the extreme, to such hilarious fiction as the HISTORY
sections of the BSD manual pages.

To take a timely example, I've just made /sys/src/fs use 64-bit
integers internally and on disk to hold metadata (e.g., file offsets,
block numbers, sizes, made file name components longer, made it
possible to compile the same source to get a kernel that is precisely
compatible with current on-disk file systems, upgraded the IDE code
(it now uses DMA and RWM), and fixed it and the boot code to cope with
faster than 2⁳ⁱHz Pentium IVs (and some other lesser fixes).  It was
annoying and embarrassing that one couldn't create a tar archive, even
in an `other' file system, larger than 2GB.  These changes are almost
entirely internal, so I think that fs(8) and fsconfig(8) are still
correct, but I have updated /sys/doc/fs to reflect the changes in
implementation (and fix a few obvious formatting errors).  Some
sections are unchanged, other needed changes to an astonishing number
of details.  (I will be feeding the changes back to jmk.)

Note that I'm not opposed to fossil (nor venti) but I do like
automatic backup to optical jukeboxes, and there are tricky
bootstrapping issues of how to recover a combined venti/fossil server
if fossil damages its write buffer.  I should probably beat on fossil
and see how robust it is these days.