stale doc files

[zooko]

I've been noticing stale doc files or wiki pages. Here is a partial list. I'd like to go through these and either delete them, update them, or replace them with a reference to the new replacement doc.

• FileEncoding? on the Doc page
• ShareEncoding? on the Doc page
• PeerSelection on the Doc page
• ChangingFilesWhileCopyingThem? on the Doc page
• docs/install-details.html and README.w32 has lots of carefully gathered notes about building and installing on various platforms, but some of it may be obsolete, and all of it is very badly formatted and organized
• roadmap.txt

[warner]

I will remove the first four docs (FileEncoding?, ShareEncoding?, PeerSelection, and ChangingFilesWhileCopyingThem?) from the wiki pages, and put their contents (whatever remains accurate and relevant) into the source tree in source:docs

We're going to try to put long-term docs in the source tree, and use the mailing list for discussions (rather than using wiki pages for discussions).

[warner]

docs/install-details.html and README.w32 are now covered by #194, and are removed from this ticket.

[warner]

I will make sure there is a ticket present for everything in roadmap.txt, and then delete roadmap.txt

[warner]

Hm, it's actually kind of nice to have the HTML docs for this stuff, because then the pictures and the text are on the same page.

Having the docs in source:docs/ makes them more likely to be updated, though. I'll start by updating the docs in the wiki.

What needs updating:

• FileEncoding?: we no longer use a fileid. When CHK is used, the encryption key is computed with a convergence secret, and we use SHA-256d. The encryption key can also be random instead of using CHK. The "verifierid" is actually the flat ciphertext hash, which is a small (and optional) component of the UEB block. Encoding and share merkle trees work as described.
• ShareEncoding?: this is actually just a placeholder for a link to a FEC page, and should be moved to the [Bibliography Bibliography]
• PeerSelection: this page is still accurate. The PeerSelection/TahoeTwo? page that it points to needs small updates (but should be moved to source:docs/): replace "verifierid" with "storage index".
• ChangingFilesWhileCopyingThem?: this just captures some early design discussion. I'll turn this into a ticket.
• roadmap.txt: this should be split into individual tickets, and the file then removed from the source tree

[warner]

ShareEncoding?: removed ChangingFilesWhileCopyingThem?: turned into ticket #427

PeerSelection: actually, this could be useful from a historical perspective: it explains paths we didn't go down. Should such things be put into source:docs ? Or on a wiki page?

[warner]

ok, PeerSelection is gone, and moved into the source tree in source:docs/historical/

[warner]

and FileEncoding? is gone. The only thing left to this ticket is roadmap.txt .

[warner]

..and roadmap.txt is gone, split into a bunch of separate tickets (mostly in the #444 to #451 range). This ticket is now done.