docs: more cleanup of known_issues.rst -- now it passes "rst2html --verbose" without...
authorZooko O'Whielacronx <zooko@zooko.com>
Wed, 14 Sep 2011 05:54:19 +0000 (22:54 -0700)
committerZooko O'Whielacronx <zooko@zooko.com>
Wed, 14 Sep 2011 05:54:19 +0000 (22:54 -0700)
docs/known_issues.rst

index 30f55734e970fe82a7837f3e366d8f1a4f1bbd3d..1008a45aa9f1590a8371ab57e2fca484984521e3 100644 (file)
@@ -1,15 +1,19 @@
-==============
- Known Issues
-==============
+.. -*- coding: utf-8 -*-
+
+============
+Known Issues
+============
 
 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
-<historical/historical_known_issues.txt>`_.
+want to read `the "historical known issues" document`_.
+
+.. _the "historical known issues" document: historical/historical_known_issues.txt
+
 
 Issues in Tahoe-LAFS v1.8.2, released 2011-01-30
 
@@ -21,6 +25,8 @@ Issues in Tahoe-LAFS v1.8.2, released 2011-01-30
   *  `Known issues in the FTP and SFTP frontends`_
   *  `Traffic analysis based on sizes of files/directories, storage indices, and timing`_
 
+----
+
 Unauthorized deletion of an immutable file by its storage index
 ---------------------------------------------------------------
 
@@ -59,8 +65,7 @@ A person could learn the storage index of a file in several ways:
    gaining the ability to inspect the local filesystem of an existing storage
    server.
 
-how to manage it
-~~~~~~~~~~~~~~~~
+*how to manage it*
 
 Tahoe-LAFS version v1.8.3 or newer (except v1.9a1) no longer has this flaw;
 if you upgrade a storage server to a fixed release then that server is no
@@ -97,10 +102,13 @@ when it first connected to that storage server, and when it most recently
 connected to that storage server. These lists are stored in memory and are
 reset to empty when the process is restarted.
 
-See ticket `#1528 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1528>`_ for
-technical details.
+See ticket `#1528`_ for technical details.
+
+.. _#1528: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1528
 
 
+----
+
 Potential unauthorized access by JavaScript in unrelated files
 --------------------------------------------------------------
 
@@ -112,18 +120,21 @@ those other files or directories to the author of the script, and if you
 have the ability to modify the contents of those files or directories,
 then that script could modify or delete those files or directories.
 
-how to manage it
-~~~~~~~~~~~~~~~~
+*how to manage it*
 
 For future versions of Tahoe-LAFS, we are considering ways to close off
 this leakage of authority while preserving ease of use -- the discussion
-of this issue is ticket `#615 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/615>`_.
+of this issue is ticket `#615`_.
 
 For the present, either do not view files stored in Tahoe-LAFS through a
 web user interface, or turn off JavaScript in your web browser before
 doing so, or limit your viewing to files which you know don't contain
 malicious JavaScript.
 
+.. _#615: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/615
+
+
+----
 
 Potential disclosure of file through embedded hyperlinks or JavaScript in that file
 -----------------------------------------------------------------------------------
@@ -142,12 +153,11 @@ file. Note that IMG tags are typically followed automatically by web
 browsers, so being careful which hyperlinks you click on is not
 sufficient to prevent this from happening.
 
-how to manage it
-~~~~~~~~~~~~~~~~
+*how to manage it*
 
 For future versions of Tahoe-LAFS, we are considering ways to close off
 this leakage of authority while preserving ease of use -- the discussion
-of this issue is ticket `#127 <http://tahoe-lafs.org/trac/tahoe-lafs/ticket/127>`_.
+of this issue is ticket `#127`_.
 
 For the present, a good work-around is that if you want to store and
 view a file on Tahoe-LAFS and you want that file to remain private, then
@@ -155,6 +165,10 @@ remove from that file any hyperlinks pointing to other people's servers
 and remove any JavaScript unless you are sure that the JavaScript is not
 written to maliciously leak access.
 
+.. _#127: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/127
+
+
+----
 
 Command-line arguments are leaked to other local users
 ------------------------------------------------------
@@ -166,8 +180,7 @@ be able to see (and copy) any caps that you pass as command-line
 arguments.  This includes directory caps that you set up with the "tahoe
 add-alias" command.
 
-how to manage it
-~~~~~~~~~~~~~~~~
+*how to manage it*
 
 As of Tahoe-LAFS v1.3.0 there is a "tahoe create-alias" command that does
 the following technique for you.
@@ -186,6 +199,8 @@ arguments you type there, but not the caps that Tahoe-LAFS uses to permit
 access to your files and directories.
 
 
+----
+
 Capabilities may be leaked to web browser phishing filter / "safe browsing" servers
 -----------------------------------------------------------------------------------
 
@@ -193,17 +208,13 @@ Firefox, Internet Explorer, and Chrome include a "phishing filter" or
 "safe browing" component, which is turned on by default, and which sends
 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
-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>`_.
+Microsoft gives `a brief description of their filter's operation`_. Firefox
+and Chrome both use Google's `"safe browsing API"`_ (`specification`_).
 
 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 in `Firefox bugzilla ticket #368255
-<https://bugzilla.mozilla.org/show_bug.cgi?id=368255>`_).
+personally identifying Google cookie along with these requests without 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
@@ -219,14 +230,20 @@ Opera also has a similar facility that is disabled by default. A previous
 version of this file stated that Firefox had abandoned their phishing
 filter; this was incorrect.
 
-how to manage it
-~~~~~~~~~~~~~~~~
+.. _a brief description of their filter's operation: http://blogs.msdn.com/ie/archive/2005/09/09/463204.aspx
+.. _"safe browsing API": http://code.google.com/apis/safebrowsing/
+.. _specification: http://code.google.com/p/google-safe-browsing/wiki/Protocolv2Spec
+.. _Firefox bugzilla ticket #368255: https://bugzilla.mozilla.org/show_bug.cgi?id=368255
+
+
+*how to manage it*
 
 If you use any phishing filter or "safe browsing" feature, consider either
 disabling it, or not using the WUI via that browser. Phishing filters have
-very limited effectiveness (see
-`<http://lorrie.cranor.org/pubs/ndss-phish-tools-final.pdf>`_), and phishing
-or malware attackers have learnt how to bypass them.
+`very limited effectiveness`_ , and phishing or malware attackers have learnt
+how to bypass them.
+
+.. _very limited effectiveness: http://lorrie.cranor.org/pubs/ndss-phish-tools-final.pdf
 
 To disable the filter in IE7 or IE8:
 ++++++++++++++++++++++++++++++++++++
@@ -268,12 +285,18 @@ To disable the filter in Chrome:
 - Click Close.
 
 
+----
+
 Known issues in the FTP and SFTP frontends
 ------------------------------------------
 
-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>`_.
+These are documented in `docs/frontends/FTP-and-SFTP.rst`_ and on `the SftpFrontend page`_ on the wiki. 
+
+.. _docs/frontends/FTP-and-SFTP.rst: frontends/FTP-and-SFTP.rst
+.. _the SftpFrontend page: http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend
+
 
+----
 
 Traffic analysis based on sizes of files/directories, storage indices, and timing
 ---------------------------------------------------------------------------------