From 87ddf54ed8d81ed79b2f559a358297a4f12c8de9 Mon Sep 17 00:00:00 2001
From: david-sarah <david-sarah@jacaranda.org>
Date: Wed, 2 Jun 2010 22:44:58 -0700
Subject: [PATCH] Minor documentation tweaks.

---
 docs/architecture.txt           | 38 ++++++++++++++++++++++-----------
 docs/frontends/FTP-and-SFTP.txt |  8 ++++++-
 2 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/docs/architecture.txt b/docs/architecture.txt
index c0eb8611..aa0101d1 100644
--- a/docs/architecture.txt
+++ b/docs/architecture.txt
@@ -1,9 +1,21 @@
+= Tahoe-LAFS Architecture =
 
-   Tahoe-LAFS Architecture
+1.  Overview
+2.  The Key-Value Store
+3.  File Encoding
+4.  Capabilities
+5.  Server Selection
+6.  Swarming Download, Trickling Upload
+7.  The Filesystem Layer
+8.  Leases, Refreshing, Garbage Collection
+9.  File Repairer
+10. Security
+11. Reliability
 
-(See the docs/specifications directory for more details.)
 
-OVERVIEW
+== Overview  ==
+
+(See the docs/specifications directory for more details.)
 
 There are three layers: the key-value store, the filesystem, and the
 application.
@@ -31,7 +43,7 @@ There are several other applications built on top of the Tahoe-LAFS
 filesystem (see the RelatedProjects page of the wiki for a list).
 
 
-THE KEY-VALUE STORE
+== The Key-Value Store ==
 
 The key-value store is implemented by a grid of Tahoe-LAFS storage servers --
 user-space processes. Tahoe-LAFS storage clients communicate with the storage
@@ -64,7 +76,7 @@ For future releases, we have plans to decentralize introduction, allowing any
 server to tell a new client about all the others.
 
 
-FILE ENCODING
+== File Encoding ==
 
 When a client stores a file on the grid, it first encrypts the file. It then
 breaks the encrypted file into small segments, in order to reduce the memory
@@ -105,7 +117,7 @@ turn them into segments of ciphertext, use the decryption key to convert that
 into plaintext, then emit the plaintext bytes to the output target.
 
 
-CAPABILITIES
+== Capabilities ==
 
 Capabilities to immutable files represent a specific set of bytes. Think of
 it like a hash function: you feed in a bunch of bytes, and you get out a
@@ -137,7 +149,7 @@ filesystem layer (described below) adds human-meaningful names atop the
 key-value layer.
 
 
-SERVER SELECTION
+== Server Selection ==
 
 When a file is uploaded, the encoded shares are sent to some servers. But to
 which ones? The "server selection" algorithm is used to make this choice.
@@ -238,7 +250,7 @@ servers.)
   long-term connections, at the expense of complexity and latency.
 
 
-SWARMING DOWNLOAD, TRICKLING UPLOAD
+== Swarming Download, Trickling Upload ==
 
 Because the shares being downloaded are distributed across a large number of
 nodes, the download process will pull from many of them at the same time. The
@@ -269,7 +281,7 @@ in the same facility, so the helper-to-storage-server bandwidth is huge.
 See "helper.txt" for details about the upload helper.
 
 
-THE FILESYSTEM LAYER
+== The Filesystem Layer ==
 
 The "filesystem" layer is responsible for mapping human-meaningful pathnames
 (directories and filenames) to pieces of data. The actual bytes inside these
@@ -299,7 +311,7 @@ links to spaces that are shared with specific other users, and other spaces
 that are globally visible.
 
 
-LEASES, REFRESHING, GARBAGE COLLECTION
+== Leases, Refreshing, Garbage Collection ==
 
 When a file or directory in the virtual filesystem is no longer referenced,
 the space that its shares occupied on each storage server can be freed,
@@ -320,7 +332,7 @@ See docs/garbage-collection.txt for further information, and how to configure
 garbage collection.
 
 
-FILE REPAIRER
+== File Repairer ==
 
 Shares may go away because the storage server hosting them has suffered a
 failure: either temporary downtime (affecting availability of the file), or a
@@ -377,7 +389,7 @@ to other nodes.
   in client behavior.
 
 
-SECURITY
+== Security ==
 
 The design goal for this project is that an attacker may be able to deny
 service (i.e. prevent you from recovering a file that was uploaded earlier)
@@ -441,7 +453,7 @@ normal web site, using username and password to give a user access to her
 capabilities).
 
 
-RELIABILITY
+== Reliability ==
 
 File encoding and peer-node selection parameters can be adjusted to achieve
 different goals. Each choice results in a number of properties; there are
diff --git a/docs/frontends/FTP-and-SFTP.txt b/docs/frontends/FTP-and-SFTP.txt
index 49b6eea7..5e994bd8 100644
--- a/docs/frontends/FTP-and-SFTP.txt
+++ b/docs/frontends/FTP-and-SFTP.txt
@@ -1,4 +1,4 @@
-= Tahoe FTP/SFTP Frontend =
+= Tahoe FTP and SFTP Frontends =
 
 1.  FTP/SFTP Background
 2.  Tahoe Support
@@ -6,6 +6,8 @@
 4.  Configuring FTP Access
 5.  Configuring SFTP Access
 6.  Dependencies
+7.  Immutable and mutable files
+
 
 == FTP/SFTP Background ==
 
@@ -24,6 +26,7 @@ Both FTP and SFTP were developed assuming a UNIX-like server, with accounts
 and passwords, octal file modes (user/group/other, read/write/execute), and
 ctime/mtime timestamps.
 
+
 == Tahoe Support ==
 
 All Tahoe client nodes can run a frontend FTP server, allowing regular FTP
@@ -49,6 +52,7 @@ HTTP-based login mechanism, backed by simple PHP script and a database. The
 latter form is used by allmydata.com to provide secure access to customer
 rootcaps.
 
+
 == Creating an Account File ==
 
 To use the first form, create a file (probably in
@@ -72,6 +76,7 @@ either of these strings.
 Then add an 'accounts.file' directive to your tahoe.cfg file, as described
 in the next sections.
 
+
 == Configuring FTP Access ==
 
 To enable the FTP server with an accounts file, add the following lines to
@@ -96,6 +101,7 @@ that server in an "accounts.url" directive:
 You can provide both accounts.file and accounts.url, although it probably
 isn't very useful except for testing.
 
+
 == Configuring SFTP Access ==
 
 The Tahoe SFTP server requires a host keypair, just like the regular SSH
-- 
2.45.2