From: david-sarah Date: Sun, 12 Dec 2010 05:14:59 +0000 (-0800) Subject: Update hyperlinks between docs, and linkify some external references. refs #1225 X-Git-Url: https://git.rkrishnan.org/specifications/%5B/%5D%20/flags/something?a=commitdiff_plain;h=5d612c87abe71fdd3a1f281aeb2f312da7ab004c;p=tahoe-lafs%2Ftahoe-lafs.git Update hyperlinks between docs, and linkify some external references. refs #1225 --- diff --git a/docs/architecture.rst b/docs/architecture.rst index cea67cad..f9216dcc 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -18,7 +18,7 @@ Tahoe-LAFS Architecture Overview ======== -(See the docs/specifications directory for more details.) +(See the `docs/specifications directory `_ 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 ``_ 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 ``_ for further information, and for how to +configure garbage collection. File Repairer diff --git a/docs/configuration.rst b/docs/configuration.rst index 737d9924..977250b1 100644 --- a/docs/configuration.rst +++ b/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 - 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 + `_. 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 ``_ 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 ``_ 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 ``_ for more details. private/root_dir.cap (optional) The command-line tools will read a directory cap out of this file and use diff --git a/docs/frontends/CLI.rst b/docs/frontends/CLI.rst index 743b8871..38b93885 100644 --- a/docs/frontends/CLI.rst +++ b/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 -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 diff --git a/docs/frontends/FTP-and-SFTP.rst b/docs/frontends/FTP-and-SFTP.rst index 230dca31..138c78d8 100644 --- a/docs/frontends/FTP-and-SFTP.rst +++ b/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 -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 diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst index 31924bcc..eeeb1da6 100644 --- a/docs/frontends/webapi.rst +++ b/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 -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 +`_-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 `_ + (dated 1997): suggests that the following might work, and + `some developers have reported `_ + 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 `_ + (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" diff --git a/docs/helper.rst b/docs/helper.rst index 8d0283a2..19e210e5 100644 --- a/docs/helper.rst +++ b/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 +``_, 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 diff --git a/docs/historical/historical_known_issues.txt b/docs/historical/historical_known_issues.txt index 31be84e4..69809ef5 100644 --- a/docs/historical/historical_known_issues.txt +++ b/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 == diff --git a/docs/historical/peer-selection-tahoe2.txt b/docs/historical/peer-selection-tahoe2.txt index 1e9a2684..fd7640e0 100644 --- a/docs/historical/peer-selection-tahoe2.txt +++ b/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. diff --git a/docs/historical/peer-selection.txt b/docs/historical/peer-selection.txt index c5c80c02..52eba8f0 100644 --- a/docs/historical/peer-selection.txt +++ b/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 -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.) diff --git a/docs/how_to_make_a_tahoe-lafs_release.rst b/docs/how_to_make_a_tahoe-lafs_release.rst index a9a3235c..a5593be3 100644 --- a/docs/how_to_make_a_tahoe-lafs_release.rst +++ b/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>`_, ``_, `<../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 ``_ 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 ``_ [ ] 16 make an "announcement of new release" on freshmeat diff --git a/docs/known_issues.rst b/docs/known_issues.rst index 521a4306..6728662e 100644 --- a/docs/known_issues.rst +++ b/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 +``_. 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 +`_. -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 -. Firefox +``_. Firefox and Chrome both use Google's "safe browsing API" which is documented -at and -. +at ``_ and +``_. 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 +``_). 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 `_ +and at ``_. Traffic analysis based on sizes of files/directories, storage indices, and timing diff --git a/docs/proposed/GridID.txt b/docs/proposed/GridID.txt index 9a6d2c2d..5510079d 100644 --- a/docs/proposed/GridID.txt +++ b/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. diff --git a/docs/proposed/mutable-DSA.txt b/docs/proposed/mutable-DSA.txt index c36dc8a0..e700388f 100644 --- a/docs/proposed/mutable-DSA.txt +++ b/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 -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 == diff --git a/docs/specifications/uri.rst b/docs/specifications/uri.rst index 91f8cc28..d3628ddb 100644 --- a/docs/specifications/uri.rst +++ b/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 -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 ``_. 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 diff --git a/docs/stats.rst b/docs/stats.rst index 47f6b04b..681c7687 100644 --- a/docs/stats.rst +++ b/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 `_. Once running, the stats gatherer will create a standard python "pickle" file in $BASEDIR/stats.pickle . Once a minute, the gatherer will pull stats