From: Brian Warner Date: Tue, 9 Apr 2013 19:19:58 +0000 (+0100) Subject: docs: replace emdash characters with plain ASCII X-Git-Tag: allmydata-tahoe-1.10b1~11 X-Git-Url: https://git.rkrishnan.org/specifications/%5B/%5D%20/flags/quickstart.html?a=commitdiff_plain;h=17fcafbb3f2136e17e937b61a2b266bbff20f2a0;p=tahoe-lafs%2Ftahoe-lafs.git docs: replace emdash characters with plain ASCII --- diff --git a/docs/about.rst b/docs/about.rst index d93f9878..3a23a055 100644 --- a/docs/about.rst +++ b/docs/about.rst @@ -27,7 +27,7 @@ these service providers spend considerable effort and expense trying to mitigate these risks. What we mean by "security" is something different. *The service provider -never has the ability to read or modify your data in the first place—never.* +never has the ability to read or modify your data in the first place: never.* If you use Tahoe-LAFS, then all of the threats described above are non-issues to you. Not only is it easy and inexpensive for the service provider to maintain the security of your data, but in fact they couldn't violate its @@ -38,7 +38,7 @@ This guarantee is integrated naturally into the Tahoe-LAFS storage system and doesn't require you to perform a manual pre-encryption step or cumbersome key management. (After all, having to do cumbersome manual operations when storing or accessing your data would nullify one of the primary benefits of -using cloud storage in the first place—convenience.) +using cloud storage in the first place: convenience.) Here's how it works: diff --git a/docs/backdoors.rst b/docs/backdoors.rst index a89b379b..031c8715 100644 --- a/docs/backdoors.rst +++ b/docs/backdoors.rst @@ -22,13 +22,13 @@ Reason`_, `Julian Sanchez / Cato Institute`_. The core Tahoe developers promise never to change Tahoe-LAFS to facilitate government access to data stored or transmitted by it. Even if it were -desirable to facilitate such access—which it is not—we believe it would not -be technically feasible to do so without severely compromising Tahoe-LAFS' -security against other attackers. There have been many examples in which -backdoors intended for use by government have introduced vulnerabilities -exploitable by other parties (a notable example being the Greek cellphone -eavesdropping scandal in 2004/5). RFCs `1984`_ and `2804`_ elaborate on the -security case against such backdoors. +desirable to facilitate such access -- which it is not -- we believe it would +not be technically feasible to do so without severely compromising +Tahoe-LAFS' security against other attackers. There have been many examples +in which backdoors intended for use by government have introduced +vulnerabilities exploitable by other parties (a notable example being the +Greek cellphone eavesdropping scandal in 2004/5). RFCs `1984`_ and `2804`_ +elaborate on the security case against such backdoors. .. _1984: https://tools.ietf.org/html/rfc1984 .. _2804: https://tools.ietf.org/html/rfc2804 diff --git a/docs/convergence-secret.rst b/docs/convergence-secret.rst index 01e30811..90b56e30 100644 --- a/docs/convergence-secret.rst +++ b/docs/convergence-secret.rst @@ -11,10 +11,10 @@ up, then stored in the client's base directory (/private/convergence) and re-used after that. So the same file content uploaded from the same client will always have the same cap. Uploading the file from a different client with a different convergence secret would result -in a different cap—and in a second copy of the file's contents stored on the -grid. If you want files you upload to converge (also known as "deduplicate") -with files uploaded by someone else, just make sure you're using the same -convergence secret when you upload files as they +in a different cap -- and in a second copy of the file's contents stored on +the grid. If you want files you upload to converge (also known as +"deduplicate") with files uploaded by someone else, just make sure you're +using the same convergence secret when you upload files as they The advantages of deduplication should be clear, but keep in mind that the convergence secret was created to protect confidentiality. There are two diff --git a/docs/frontends/CLI.rst b/docs/frontends/CLI.rst index b2855671..ebeb34c9 100644 --- a/docs/frontends/CLI.rst +++ b/docs/frontends/CLI.rst @@ -56,13 +56,13 @@ functionality) and including versions for a number of dependent libraries, like Twisted, Foolscap, pycryptopp, and zfec. "``tahoe --version-and-path``" will also show the path from which each library was imported. -On Unix systems, the shell expands filename wildcards — ``'*'`` and ``'?'`` — -before the program is able to read them, which may produce unexpected -results for many ``tahoe`` comands. We recommend, if you use wildcards, -to start the path with "``./``", for example "``tahoe cp -r ./* somewhere:``". -This prevents the expanded filename from being interpreted as an option -or as an alias, allowing filenames that start with a dash or contain -colons to be handled correctly. +On Unix systems, the shell expands filename wildcards (``'*'`` and ``'?'``) +before the program is able to read them, which may produce unexpected results +for many ``tahoe`` comands. We recommend, if you use wildcards, to start the +path with "``./``", for example "``tahoe cp -r ./* somewhere:``". This +prevents the expanded filename from being interpreted as an option or as an +alias, allowing filenames that start with a dash or contain colons to be +handled correctly. On Windows, a single letter followed by a colon is treated as a drive specification rather than an alias (and is invalid unless a local path is diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst index 0f216130..232e0c01 100644 --- a/docs/frontends/webapi.rst +++ b/docs/frontends/webapi.rst @@ -1296,7 +1296,7 @@ Relinking ("Moving") a Child This instructs the node to move a child of the given source directory, into a different directory and/or to a different name. The command is named ``relink`` because what it does is add a new link to the child from the new - location, then remove the old link. Nothing is actually "moved" — the child + location, then remove the old link. Nothing is actually "moved": the child is still reachable through any path from which it was formerly reachable, and the storage space occupied by its ciphertext is not affected. diff --git a/docs/known_issues.rst b/docs/known_issues.rst index 34a8bb7f..a4a342ab 100644 --- a/docs/known_issues.rst +++ b/docs/known_issues.rst @@ -318,7 +318,7 @@ authorization (confidentiality), nor to change the contents of a file A person could learn the storage index of a file in several ways: -1. By being granted the authority to read the immutable file—i.e. by being +1. By being granted the authority to read the immutable file: i.e. by being granted a read capability to the file. They can determine the file's storage index from its read capability. @@ -347,17 +347,17 @@ if you upgrade a storage server to a fixed release then that server is no longer vulnerable to this problem. Note that the issue is local to each storage server independently of other -storage servers—when you upgrade a storage server then that particular +storage servers: when you upgrade a storage server then that particular storage server can no longer be tricked into deleting its shares of the target file. If you can't immediately upgrade your storage server to a version of Tahoe-LAFS that eliminates this vulnerability, then you could temporarily shut down your storage server. This would of course negatively impact -availability—clients would not be able to upload or download shares to that -particular storage server while it was shut down—but it would protect the -shares already stored on that server from being deleted as long as the server -is shut down. +availability -- clients would not be able to upload or download shares to +that particular storage server while it was shut down -- but it would protect +the shares already stored on that server from being deleted as long as the +server is shut down. If the servers that store shares of your file are running a version of Tahoe-LAFS with this vulnerability, then you should think about whether diff --git a/docs/specifications/backends/raic.rst b/docs/specifications/backends/raic.rst index 90f4b806..294c4e86 100644 --- a/docs/specifications/backends/raic.rst +++ b/docs/specifications/backends/raic.rst @@ -175,8 +175,8 @@ In this section we analyze the costs of the proposed design in terms of network, disk, memory, cloud storage, and API usage. -Network usage—bandwidth and number-of-round-trips -------------------------------------------------- +Network usage: bandwidth and number-of-round-trips +-------------------------------------------------- When a Tahoe-LAFS storage client allocates a new share on a storage server, the backend will request a list of the existing cloud objects with the @@ -324,14 +324,15 @@ Known Issues ============ This design worsens a known “write hole” issue in Tahoe-LAFS when updating -the contents of mutable files. An update to a mutable file can require changing -the contents of multiple chunks, and if the client fails or is disconnected -during the operation the resulting state of the stored cloud objects may be -inconsistent—no longer containing all of the old version, but not yet containing -all of the new version. A mutable share can be left in an inconsistent state -even by the existing Tahoe-LAFS disk backend if it fails during a write, but -that has a smaller chance of occurrence because the current client behavior -leads to mutable shares being written to disk in a single system call. +the contents of mutable files. An update to a mutable file can require +changing the contents of multiple chunks, and if the client fails or is +disconnected during the operation the resulting state of the stored cloud +objects may be inconsistent: no longer containing all of the old version, but +not yet containing all of the new version. A mutable share can be left in an +inconsistent state even by the existing Tahoe-LAFS disk backend if it fails +during a write, but that has a smaller chance of occurrence because the +current client behavior leads to mutable shares being written to disk in a +single system call. The best fix for this issue probably requires changing the Tahoe-LAFS storage protocol, perhaps by extending it to use a two-phase or three-phase commit