Update hyperlinks between docs, and linkify some external references. refs #1225

docs/architecture.rst

@@ -18,7 +18,7 @@ Tahoe-LAFS Architecture
 Overview
 ========
 
-(See the docs/specifications directory for more details.)
+(See the `docs/specifications directory <specifications>`_ for more details.)
 
 There are three layers: the key-value store, the filesystem, and the
 application.
@@ -312,7 +312,7 @@ commercially-run grid for which all of the storage servers are in a colo
 facility with high interconnect bandwidth. In this case, the helper is placed
 in the same facility, so the helper-to-storage-server bandwidth is huge.
 
-See "helper.txt" for details about the upload helper.
+See `<helper.rst>`_ for details about the upload helper.
 
 
 The Filesystem Layer
@@ -364,8 +364,8 @@ clients are responsible for renewing their leases on a periodic basis at
 least frequently enough to prevent any of the leases from expiring before the
 next renewal pass.
 
-See docs/garbage-collection.txt for further information, and how to configure
+See `<garbage-collection.rst>`_ for further information, and for how to
-garbage collection.
+configure garbage collection.
 
 
 File Repairer

docs/configuration.rst

@@ -73,13 +73,13 @@ set the tub.location option described below.
   web.port = (strports string, optional)
 
     This controls where the node's webserver should listen, providing
-    filesystem access and node status as defined in webapi.txt . This file
+    filesystem access and node status as defined in `webapi.rst
-    contains a Twisted "strports" specification such as "3456" or
+    <frontends/webapi.rst>`_. This file contains a Twisted "strports"
-    "tcp:3456:interface=127.0.0.1". The 'tahoe create-node' or 'tahoe
+    specification such as "3456" or "tcp:3456:interface=127.0.0.1".
-    create-client' commands set the web.port to
+    The 'tahoe create-node' or 'tahoe create-client' commands set the
-    "tcp:3456:interface=127.0.0.1" by default; this is overridable by the
+    web.port to "tcp:3456:interface=127.0.0.1" by default; this is
-    "--webport" option. You can make it use SSL by writing
+    overridable by the "--webport" option. You can make it use SSL by
-    "ssl:3456:privateKey=mykey.pem:certKey=cert.pem" instead.
+    writing "ssl:3456:privateKey=mykey.pem:certKey=cert.pem" instead.
 
     If this is not provided, the node will not run a web server.
 
@@ -263,7 +263,7 @@ Client Configuration
   helper.furl = (FURL string, optional)
 
     If provided, the node will attempt to connect to and use the given helper
-    for uploads. See docs/helper.txt for details.
+    for uploads. See `<helper.rst>`_ for details.
 
   key_generator.furl = (FURL string, optional)
 
@@ -379,7 +379,7 @@ service.
   [helper]
   enabled = (boolean, optional)
 
-    If True, the node will run a helper (see docs/helper.txt for details).
+    If True, the node will run a helper (see `<helper.rst>`_ for details).
     The helper's contact FURL will be placed in private/helper.furl, from
     which it can be copied to any clients which wish to use it. Clearly nodes
     should not both run a helper and attempt to use one: do not create both
@@ -451,7 +451,7 @@ private/logport.furl
 
 private/helper.furl
   if the node is running a helper (for use by other clients), its contact
-  FURL will be placed here. See docs/helper.txt for more details.
+  FURL will be placed here. See `<helper.rst>`_ for more details.
 
 private/root_dir.cap (optional)
   The command-line tools will read a directory cap out of this file and use

docs/frontends/CLI.rst

@@ -125,12 +125,13 @@ character encoding specified by the current locale.
 Starting Directories
 --------------------
 
-As described in architecture.txt, the Tahoe distributed filesystem consists
+As described in `docs/architecture.rst <../architecture.rst>`_, the
-of a collection of directories and files, each of which has a "read-cap" or a
+Tahoe-LAFS distributed filesystem consists of a collection of directories
-"write-cap" (also known as a URI). Each directory is simply a table that maps
+and files, each of which has a "read-cap" or a "write-cap" (also known as
-a name to a child file or directory, and this table is turned into a string
+a URI). Each directory is simply a table that maps a name to a child file
-and stored in a mutable file. The whole set of directory and file "nodes" are
+or directory, and this table is turned into a string and stored in a
-connected together into a directed graph.
+mutable file. The whole set of directory and file "nodes" are connected
+together into a directed graph.
 
 To use this collection of files and directories, you need to choose a
 starting point: some specific directory that we will refer to as a

docs/frontends/FTP-and-SFTP.rst

@@ -196,8 +196,9 @@ entry to be relinked to a different file. Normally, when the path of an
 immutable file is opened for writing by SFTP, the directory entry is
 relinked to another file with the newly written contents when the file
 handle is closed. The old file is still present on the grid, and any other
-caps to it will remain valid. (See docs/garbage-collection.txt for how to
+caps to it will remain valid. (See `docs/garbage-collection.rst
-reclaim the space used by files that are no longer needed.)
+<../garbage-collection.rst>`_ for how to reclaim the space used by files
+that are no longer needed.)
 
 The 'no-write' metadata field of a directory entry can override this
 behaviour. If the 'no-write' field holds a true value, then a permission

docs/frontends/webapi.rst

@@ -64,14 +64,14 @@ port 3456, on the loopback (127.0.0.1) interface.
 Basic Concepts: GET, PUT, DELETE, POST
 ======================================
 
-As described in `architecture.rst`_, each file and directory in a Tahoe virtual
+As described in `docs/architecture.rst <../architecture.rst>`_, each file
-filesystem is referenced by an identifier that combines the designation of
+and directory in a Tahoe virtual filesystem is referenced by an identifier
-the object with the authority to do something with it (such as read or modify
+that combines the designation of the object with the authority to do something
-the contents). This identifier is called a "read-cap" or "write-cap",
+with it (such as read or modify the contents). This identifier is called a
-depending upon whether it enables read-only or read-write access. These
+"read-cap" or "write-cap", depending upon whether it enables read-only or
-"caps" are also referred to as URIs.
+read-write access. These "caps" are also referred to as URIs (which may be
-
+confusing because they are not currently `RFC3986
-.. _architecture.rst: http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/architecture.rst
+<http://tools.ietf.org/html/rfc3986>`_-compliant URIs).
 
 The Tahoe web-based API is "REST-ful", meaning it implements the concepts of
 "REpresentational State Transfer": the original scheme by which the World
@@ -200,7 +200,7 @@ that file with::
 
 Multiple levels of subdirectories can be handled this way::
 
- http://127.0.0.1:3456/uri/$DIRCAP/tahoe-source/docs/webapi.txt
+ http://127.0.0.1:3456/uri/$DIRCAP/tahoe-source/docs/architecture.rst
 
 In this document, when we need to refer to a URL that references a file using
 this child-of-some-directory format, we'll use the following string::
@@ -1904,8 +1904,7 @@ Tahoe-1.1; back with Tahoe-1.0 the web client was responsible for serializing
 web requests themselves).
 
 For more details, please see the "Consistency vs Availability" and "The Prime
-Coordination Directive" sections of mutable.txt, in the same directory as
+Coordination Directive" sections of `mutable.rst <../specifications/mutable.rst>`_.
-this file.
 
 
 .. [1] URLs and HTTP and UTF-8, Oh My
@@ -1937,16 +1936,17 @@ this file.
     (note, the last four bytes of that line, not including the newline, are
     0xC3 0xA9 0x65 0x22)
 
- RFC2231#4 (dated 1997): suggests that the following might work, and some
+ `RFC2231#4 <http://tools.ietf.org/html/rfc2231#section-4>`_
- developers (http://markmail.org/message/dsjyokgl7hv64ig3) have reported that
+ (dated 1997): suggests that the following might work, and
- it is supported by firefox (but not IE7)::
+ `some developers have reported <http://markmail.org/message/dsjyokgl7hv64ig3>`_
+ that it is supported by firefox (but not IE7)::
 
   #2: Content-Disposition: attachment; filename*=utf-8''fianc%C3%A9e
 
- My reading of RFC2616#19.5.1 (which defines Content-Disposition) says that
+ My reading of `RFC2616#19.5.1 <http://tools.ietf.org/html/rfc2616#section-19.5.1>`_
- the filename= parameter is defined to be wrapped in quotes (presumeably to
+ (which defines Content-Disposition) says that the filename= parameter is
- allow spaces without breaking the parsing of subsequent parameters), which
+ defined to be wrapped in quotes (presumably to allow spaces without breaking
- would give us::
+ the parsing of subsequent parameters), which would give us::
 
   #3: Content-Disposition: attachment; filename*=utf-8''"fianc%C3%A9e"
 

docs/helper.rst

@@ -11,7 +11,7 @@ Overview
 ========
 
 As described in the "SWARMING DOWNLOAD, TRICKLING UPLOAD" section of
-architecture.txt, Tahoe uploads require more bandwidth than downloads: you
+`<architecture.rst>`_, Tahoe uploads require more bandwidth than downloads: you
 must push the redundant shares during upload, but you do not need to retrieve
 them during download. With the default 3-of-10 encoding parameters, this
 means that an upload will require about 3.3x the traffic as a download of the

docs/historical/historical_known_issues.txt

@@ -7,7 +7,8 @@ http://tahoe-lafs.org/source/tahoe/trunk/docs/historical/historical_known_issues
 
 Issues in newer releases of Tahoe-LAFS can be found at:
 
-http://tahoe-lafs.org/source/tahoe/trunk/docs/known_issues.txt
+http://tahoe-lafs.org/source/tahoe/trunk/docs/known_issues.rst
+
 
 == issues in Tahoe v1.1.0, released 2008-06-11 ==
 

docs/historical/peer-selection-tahoe2.txt

@@ -1,4 +1,4 @@
-= THIS PAGE DESCRIBES HISTORICAL DESIGN CHOICES. SEE docs/architecture.txt FOR CURRENT DOCUMENTATION =
+= THIS PAGE DESCRIBES HISTORICAL DESIGN CHOICES. SEE docs/architecture.rst FOR CURRENT DOCUMENTATION =
 
 When a file is uploaded, the encoded shares are sent to other peers. But to
 which ones? The PeerSelection algorithm is used to make this choice.

docs/historical/peer-selection.txt

@@ -10,8 +10,8 @@ nodes were parts of which cabals.
 
 When we release 0.2.0, we used the "tahoe3" algorithm (see
 peer-selection-tahoe3.txt), but in v0.6 (ticket #132) we switched back to
-"tahoe2" (see the peer-selection-tahoe2.txt, and the PEER SELECTION section
+"tahoe2" (see peer-selection-tahoe2.txt, and the PEER SELECTION section
-of docs/architecture.txt), which uses a permuted peerid list and packs the
+of docs/architecture.rst), which uses a permuted peerid list and packs the
 shares into the first 10 or so members of this list. (It is named "tahoe2"
 because it was designed before "tahoe3" was.)
 

docs/how_to_make_a_tahoe-lafs_release.rst

@@ -1,6 +1,6 @@
-[ ]  1 update doc files: relnotes.txt, CREDITS, docs/known_issues.rst, NEWS. Add release name and date to top-most item in NEWS.
+[ ]  1 update doc files: `<../relnotes.txt>`_, `<../CREDITS>`_, `<known_issues.rst>`_, `<../NEWS>`_. Add release name and date to top-most item in NEWS.
 
-[ ]  2 change docs/quickstart.html to point to just the current allmydata-tahoe-X.Y.Z.zip source code file, or else to point to a directory which contains only allmydata-tahoe-X.Y.Z.* source code files
+[ ]  2 change `<quickstart.html>`_ to point to just the current allmydata-tahoe-X.Y.Z.zip source code file, or else to point to a directory which contains only allmydata-tahoe-X.Y.Z.* source code files
 
 [ ]  3 darcs pull
 
@@ -26,7 +26,7 @@
 
 [ ] 14 send out relnotes.txt: [ ] tahoe-announce@tahoe-lafs.org, [ ] tahoe-dev@tahoe-lafs.org, [ ] p2p-hackers@lists.zooko.com, [ ] lwn@lwn.net, [ ] cap-talk@mail.eros-os.org, [ ] cryptography@metzdown.com, [ ] cryptography@randombit.net, [ ] twisted-python@twistedmatrix.com, [ ] owncloud@kde.org, [ ] liberationtech@lists.stanford.edu, [ ] the "decentralization" group on groups.yahoo.com, [ ] pycrypto mailing list, -> fuse-devel@lists.sourceforge.net, -> fuse-sshfs@lists.sourceforge.net, [ ] duplicity-talk@nongnu.org, [ ] news@phoronix.com, [ ] python-list@python.org, -> cygwin@cygwin.com, [ ] The Boulder Linux Users' Group, [ ] The Boulder Hackerspace mailing list, [ ] cryptopp-users@googlegroups.com, [ ] tiddlywiki, [ ] hdfs-dev@hadoop.apache.org, [ ] bzr, [ ] mercurial, [ ] http://listcultures.org/pipermail/p2presearch_listcultures.org/ , deltacloud, libcloud, [ ] swift@lists.launchpad.net, cleversafe.org, [ ] stephen@fosketts.net, [ ] Chris Mellor of The Register, [ ] nosql@mypopescu.com
 
-[ ] 15 update hacktahoe.org
+[ ] 15 update `<http://tahoe-lafs.org/hacktahoelafs/>`_
 
 [ ] 16 make an "announcement of new release" on freshmeat
 

docs/known_issues.rst

@@ -16,14 +16,13 @@ Overview
 
 Below is a list of known issues in recent releases of Tahoe-LAFS, and how to
 manage them.  The current version of this file can be found at
-
+`<http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/known_issues.rst>`_.
-http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/known_issues.rst
 
 If you've been using Tahoe-LAFS since v1.1 (released 2008-06-11) or if you're
 just curious about what sort of mistakes we've made in the past, then you might
-want to read the "historical known issues" document:
+want to read `the "historical known issues" document
+<historical/historical_known_issues.txt>`_.
 
-http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/historical/historical_known_issues.txt
 
 Issues in Tahoe-LAFS v1.8.1, released 2010-11-28
 ================================================
@@ -121,16 +120,16 @@ Firefox, Internet Explorer, and Chrome include a "phishing filter" or
 any URLs that it deems suspicious to a central server.
 
 Microsoft gives a brief description of their filter's operation at
-<http://blogs.msdn.com/ie/archive/2005/09/09/463204.aspx>. Firefox
+`<http://blogs.msdn.com/ie/archive/2005/09/09/463204.aspx>`_. Firefox
 and Chrome both use Google's "safe browsing API" which is documented
-at <http://code.google.com/apis/safebrowsing/> and
+at `<http://code.google.com/apis/safebrowsing/>`_ and
-<http://code.google.com/p/google-safe-browsing/wiki/Protocolv2Spec>.
+`<http://code.google.com/p/google-safe-browsing/wiki/Protocolv2Spec>`_.
 
 This of course has implications for the privacy of general web browsing
 (especially in the cases of Firefox and Chrome, which send your main
 personally identifying Google cookie along with these requests without
-your explicit consent, as described for Firefox in
+your explicit consent, as described in `Firefox bugzilla ticket #368255
-<https://bugzilla.mozilla.org/show_bug.cgi?id=368255>).
+`<https://bugzilla.mozilla.org/show_bug.cgi?id=368255>`_).
 
 The reason for documenting this issue here, though, is that when using the
 Tahoe-LAFS web user interface, it could also affect confidentiality and integrity
@@ -198,8 +197,8 @@ To disable the filter in Chrome:
 Known issues in the FTP and SFTP frontends
 ------------------------------------------
 
-These are documented in docs/frontends/FTP-and-SFTP.txt and at
+These are documented in `docs/frontends/FTP-and-SFTP.rst <frontends/FTP-and-SFTP.rst>`_
-<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>.
+and at `<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>`_.
 
 
 Traffic analysis based on sizes of files/directories, storage indices, and timing

docs/proposed/GridID.txt

@@ -180,7 +180,7 @@ some credentials to the storage server to convince it that the client
 deserves the space. When storage servers are in this mode, they will have a
 certificate that names a public key, and any credentials that can demonstrate
 a path from that key will be accepted. This scheme is described in
-docs/accounts-pubkey.txt .
+docs/proposed/old-accounts-pubkey.txt .
 
 The second limitation is unexplored. The read-cap does not currently contain
 any notion of who must pay for the bandwidth incurred.

docs/proposed/mutable-DSA.txt

@@ -7,8 +7,8 @@ been implemented. Please see mutable-DSA.svg for a quick picture of the
 crypto scheme described herein)
 
 This file shows only the differences from RSA-based mutable files to
-(EC)DSA-based mutable files.  You have to read and understand mutable.txt before
+(EC)DSA-based mutable files.  You have to read and understand
-reading this file (mutable-DSA.txt).
+docs/specifications/mutable.rst before reading this file (mutable-DSA.txt).
 
 == new design criteria ==
 

docs/specifications/uri.rst

@@ -82,8 +82,8 @@ of the total number of shares created, and (size) is an ascii decimal
 representation of the size of the data represented by this URI. All base32
 encodings are expressed in lower-case, with the trailing '=' signs removed.
 
-For example, the following is a CHK URI, generated from the contents of the
+For example, the following is a CHK URI, generated from a previous version of
-architecture.txt document that lives next to this one in the source tree::
+the contents of `<../architecture.rst>`_::
 
  URI:CHK:ihrbeov7lbvoduupd4qblysj7a:bg5agsdt62jb34hxvxmdsbza6do64f4fg5anxxod2buttbo6udzq:3:10:28733
 
@@ -141,7 +141,7 @@ The format of the write-cap for mutable files is::
 Where (writekey) is the base32 encoding of the 16-byte AES encryption key
 that is used to encrypt the RSA private key, and (fingerprint) is the base32
 encoded 32-byte SHA-256 hash of the RSA public key. For more details about
-the way these keys are used, please see docs/mutable.txt .
+the way these keys are used, please see `<mutable.rst>`_.
 
 The format for mutable read-caps is::
 
@@ -163,7 +163,7 @@ Directory URIs
 The grid layer provides a mapping from URI to data. To turn this into a graph
 of directories and files, the "vdrive" layer (which sits on top of the grid
 layer) needs to keep track of "directory nodes", or "dirnodes" for short.
-docs/dirnodes.txt describes how these work.
+`docs/dirnodes.rst <../dirnodes.rst>`_ describes how these work.
 
 Dirnodes are contained inside mutable files, and are thus simply a particular
 way to interpret the contents of these files. As a result, a directory

docs/stats.rst

@@ -297,7 +297,7 @@ keep its FURL consistent). To explicitly control which port it uses, write
 the desired portnumber into a file named "portnum" (i.e. $BASEDIR/portnum),
 and the next time the gatherer is started, it will start listening on the
 given port. The portnum file is actually a "strports specification string",
-as described in docs/configuration.txt .
+as described in `docs/configuration.rst <configuration.rst>`_.
 
 Once running, the stats gatherer will create a standard python "pickle" file
 in $BASEDIR/stats.pickle . Once a minute, the gatherer will pull stats