Update hyperlinks between docs, and linkify some external references. refs #1225
authordavid-sarah <david-sarah@jacaranda.org>
Sun, 12 Dec 2010 05:14:59 +0000 (21:14 -0800)
committerdavid-sarah <david-sarah@jacaranda.org>
Sun, 12 Dec 2010 05:14:59 +0000 (21:14 -0800)
15 files changed:
docs/architecture.rst
docs/configuration.rst
docs/frontends/CLI.rst
docs/frontends/FTP-and-SFTP.rst
docs/frontends/webapi.rst
docs/helper.rst
docs/historical/historical_known_issues.txt
docs/historical/peer-selection-tahoe2.txt
docs/historical/peer-selection.txt
docs/how_to_make_a_tahoe-lafs_release.rst
docs/known_issues.rst
docs/proposed/GridID.txt
docs/proposed/mutable-DSA.txt
docs/specifications/uri.rst
docs/stats.rst

index cea67cadcb208d5eb4339e301555ee5f4a1f91d4..f9216dcc29ce84b4b3591399b76e36adca73a75a 100644 (file)
@@ -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
-garbage collection.
+See `<garbage-collection.rst>`_ for further information, and for how to
+configure garbage collection.
 
 
 File Repairer
index 737d992492cbce6ef50478a87a3922790b45d982..977250b18a8dfb06eb5ccb557b08d1013950a2d1 100644 (file)
@@ -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
-    contains a Twisted "strports" specification such as "3456" or
-    "tcp:3456:interface=127.0.0.1". The 'tahoe create-node' or 'tahoe
-    create-client' commands set the web.port to
-    "tcp:3456:interface=127.0.0.1" by default; this is overridable by the
-    "--webport" option. You can make it use SSL by writing
-    "ssl:3456:privateKey=mykey.pem:certKey=cert.pem" instead.
+    filesystem access and node status as defined in `webapi.rst
+    <frontends/webapi.rst>`_. This file contains a Twisted "strports"
+    specification such as "3456" or "tcp:3456:interface=127.0.0.1".
+    The 'tahoe create-node' or 'tahoe create-client' commands set the
+    web.port to "tcp:3456:interface=127.0.0.1" by default; this is
+    overridable by the "--webport" option. You can make it use SSL by
+    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
index 743b887173ee81440d3c9cf6e6bffb8de77a8521..38b9388555f994ada41017733d4568343eabe11b 100644 (file)
@@ -125,12 +125,13 @@ character encoding specified by the current locale.
 Starting Directories
 --------------------
 
-As described in architecture.txt, the Tahoe distributed filesystem consists
-of a collection of directories and files, each of which has a "read-cap" or a
-"write-cap" (also known as a URI). Each directory is simply a table that maps
-a name to a child file or directory, and this table is turned into a string
-and stored in a mutable file. The whole set of directory and file "nodes" are
-connected together into a directed graph.
+As described in `docs/architecture.rst <../architecture.rst>`_, the
+Tahoe-LAFS distributed filesystem consists of a collection of directories
+and files, each of which has a "read-cap" or a "write-cap" (also known as
+a URI). Each directory is simply a table that maps a name to a child file
+or directory, and this table is turned into a string and stored in a
+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
index 230dca31cd4c4f6aec0646a71a168db348175ee1..138c78d8bf188872074450d6aab468e1a697cb4f 100644 (file)
@@ -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
-reclaim the space used by files that are no longer needed.)
+caps to it will remain valid. (See `docs/garbage-collection.rst
+<../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
index 31924bcc7261558f4b85839525ef047b72a91c5c..eeeb1da6d7b1a7e8575358b5c7da92c3c45f84f5 100644 (file)
@@ -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
-filesystem is referenced by an identifier that combines the designation of
-the object with the authority to do something with it (such as read or modify
-the contents). This identifier is called a "read-cap" or "write-cap",
-depending upon whether it enables read-only or read-write access. These
-"caps" are also referred to as URIs.
-
-.. _architecture.rst: http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/architecture.rst
+As described in `docs/architecture.rst <../architecture.rst>`_, each file
+and directory in a Tahoe virtual filesystem is referenced by an identifier
+that combines the designation of the object with the authority to do something
+with it (such as read or modify the contents). This identifier is called a
+"read-cap" or "write-cap", depending upon whether it enables read-only or
+read-write access. These "caps" are also referred to as URIs (which may be
+confusing because they are not currently `RFC3986
+<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
-this file.
+Coordination Directive" sections of `mutable.rst <../specifications/mutable.rst>`_.
 
 
 .. [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
- developers (http://markmail.org/message/dsjyokgl7hv64ig3) have reported that
- it is supported by firefox (but not IE7)::
+ `RFC2231#4 <http://tools.ietf.org/html/rfc2231#section-4>`_
+ (dated 1997): suggests that the following might work, and
+ `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
- the filename= parameter is defined to be wrapped in quotes (presumeably to
- allow spaces without breaking the parsing of subsequent parameters), which
- would give us::
+ My reading of `RFC2616#19.5.1 <http://tools.ietf.org/html/rfc2616#section-19.5.1>`_
+ (which defines Content-Disposition) says that the filename= parameter is
+ defined to be wrapped in quotes (presumably to allow spaces without breaking
the parsing of subsequent parameters), which would give us::
 
   #3: Content-Disposition: attachment; filename*=utf-8''"fianc%C3%A9e"
 
index 8d0283a2dddde06663c4b2514162cb8e3ec7acb1..19e210e5e4d209698b44508df88ade6816f9459d 100644 (file)
@@ -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
index 31be84e463a796387a0ff31e750e094bd0f85b12..69809ef5f46bd5b1a91a50ed05dcddc6f257deff 100644 (file)
@@ -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 ==
 
index 1e9a26842e5164663d13c9fd18f6de8260a0b68c..fd7640e0030f4a2177a22fc88669774252de60e0 100644 (file)
@@ -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.
index c5c80c02e3df9291946f3d9031f297dd543df403..52eba8f04b94a42dbe146ecefd77c997778bd80d 100644 (file)
@@ -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
-of docs/architecture.txt), which uses a permuted peerid list and packs the
+"tahoe2" (see peer-selection-tahoe2.txt, and the PEER SELECTION section
+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.)
 
index a9a3235c4be6992862c2be32a24b9ea7126ed5a5..a5593be3ba0e8f0bb97db03d792fdfb3c48d5ab8 100644 (file)
@@ -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
 
index 521a4306fb32fcac4340a0cf670a9e482f580791..6728662e7a960609942569dbc88df18c86504944 100644 (file)
@@ -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
-<http://code.google.com/p/google-safe-browsing/wiki/Protocolv2Spec>.
+at `<http://code.google.com/apis/safebrowsing/>`_ and
+`<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
-<https://bugzilla.mozilla.org/show_bug.cgi?id=368255>).
+your explicit consent, as described in `Firefox bugzilla ticket #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
-<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>.
+These are documented in `docs/frontends/FTP-and-SFTP.rst <frontends/FTP-and-SFTP.rst>`_
+and at `<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>`_.
 
 
 Traffic analysis based on sizes of files/directories, storage indices, and timing
index 9a6d2c2d2ae1fe50d6fdf3f957980c5dd963cb11..5510079d80bd741f6a153fd8dda01137983591c1 100644 (file)
@@ -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.
index c36dc8a0119ed487a79fa22e6fc72981d65ef37f..e700388f0bb1f061b4e6bb61e7f8b7150751f6ec 100644 (file)
@@ -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
-reading this file (mutable-DSA.txt).
+(EC)DSA-based mutable files.  You have to read and understand
+docs/specifications/mutable.rst before reading this file (mutable-DSA.txt).
 
 == new design criteria ==
 
index 91f8cc28c90983804ae938a1b25945e663e1cdf3..d3628ddb8b00523412553d142ee34f2a02df0ee7 100644 (file)
@@ -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
-architecture.txt document that lives next to this one in the source tree::
+For example, the following is a CHK URI, generated from a previous version of
+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
index 47f6b04b78888a2fe29c8801d6576ec3f85dbb73..681c7687ed47a29b768464a8a124d7059d236341 100644 (file)
@@ -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