[Gzz-commits] storm README

[Benja Fallenstein]

CVSROOT:        /cvsroot/storm
Module name:    storm
Changes by:     Benja Fallenstein <address@hidden>      03/05/04 15:57:26

Modified files:
        .              : README 

Log message:
        start improving readme

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/storm/storm/README.diff?tr1=1.2&tr2=1.3&r1=text&r2=text

Patches:
Index: storm/README
diff -u storm/README:1.2 storm/README:1.3
--- storm/README:1.2    Fri May  2 12:21:52 2003
+++ storm/README        Sun May  4 15:57:26 2003
@@ -1,11 +1,62 @@
-
+=========================
 Storm - permanent storage
+=========================
+
+
+The Storm (STORage Module) library provides an alternative
+to traditional file-based storage. Storm stores data
+in *blocks*. A block is like a file but it cannot be changed,
+and instead of a file name it is identified by a
+cryptographic content hash, like this::
+
+    nkownd7c3yvtk2ll7b3c7m2abg25etb3.3ghrsnouwddhjm4uh6vv4qk6yvdaw46o2jvsmxq
+
+A content hash is a number computed from the content
+of a block. In practice it's impossible to find two blocks
+with the same hash (as long as the algorithm isn't broken).
+
+Don't worry about the 'cannot be changed' part. You can create
+a *reference* that can point to different blocks over time.
+(However, while we used to have an implementation of this,
+this is unimplemented currently; stay tuned.)
+
+Here are a few reasons why you would want to use this 
+instead of files:
+
+- When you make a new version of something, the old one
+  doesn't get overwritten. The new version has a new
+  'name' (content hash).
+- You can check whether the content of a block matches
+  its id. If you download a block from somewhere, you
+  can check you got the correct data.
+- Thus, it doesn't matter where you find a block. No matter
+  if it's on your harddisk, sent to you by e-mail, stored
+  in your Web cache, or downloaded from the Web.
+- You don't have to store a block twice, even if you
+  use it in different places. For example, an image used
+  in many different documents would only need to be
+  stored once.
+- Network transparency: When you have a block locally,
+  your computer can use it; when you don't, your computer
+  can go find it on the 'net. (Or on another one of your
+  machines, if the computer you're currently using
+  is connected to them.)
+- When you're offline, any blocks stored on your computer--
+  or a computer connected to it-- can be used just as if
+  you were online.
 
+We are building a P2P system that allows you to find and
+download a block if *anybody* on the 'net publishes it.
+So when the original site is down, or the content
+was removed from it, you can still download
 
-Storm (STORage Module) system provides a permanent data store. Data is 
-stored in immutable blocks, which can be retrieved by an identifier based 
-on the content of the block. Unlike files, blocks don't have names and their 
-location doesn't affect their identity.
+Don't worry that accidentally, there may be two *different*
+blocks with the *same* hash floating around on the Internet.
+In theory it *could* happen. In practice, the number of
+possible hashes is about an octillion times larger than the
+estimated number of atoms in the universe. We suggest that
+you worry about something more likely instead, like, say,
+the destruction of Earth through an asteroid ;-)
 
 Storm software can:
 - import files as Storm blocks