New README and CAVEAT

2 files changed, 46 insertions, 2 deletions

diff --git a/CAVEAT b/CAVEAT
new file mode 100644
index 0000000..dbb8813
--- /dev/null
+++ b/CAVEAT
@@ -0,0 +1,25 @@
+While using unionfs, you could experience more permission errors or 
+difficult or impossible file or directory deletion. This is a list of
+things that can happen.
+
+WARNINGS:
+
+- If the translator is run as by an unpriviledged user, other users will fail
+to create files or directory, since the translator won't be able to change
+the ownership of the file.
+
+
+PROBLEMS:
+
+- If there's a name conflict in underlying filesystems between directories 
+and files -- say that "foo" is a directory in underlying filesystem "a" while
+is a file in the underlying filesystem "b" -- then unionfs will be unable to
+delete this entry. This is a structural BUG (there's no clean way to solve it),
+and should be fixed.
+
+- If there's a name conflict in underlying filesystems between directories
+(or between files), and the user has not permission to delete _ALL_ the 
+entries -- e.g. one hidden entry is read-only -- then he will get an EPERM
+even if permissions seems ok. This is a structural BUG (there's no clean way
+to solve it), and should be fixed.
+
diff --git a/README b/README
index d703616..16d73d5 100644
--- a/README
+++ b/README
@@ -1,2 +1,21 @@
-This is an `unionfs' server for the Hurd.  The semantics are similar
-to BSD's unionfs.
+This is an `unionfs' translator for the Hurd. It is simple, but it is 
+definitely not a joke.
+
+It works by keeping in memory a dynamically updated tree of nodes, each 
+node representing a directory in the unionfs. A node contains an array 
+of ports that give access to the corrisponding directory in the underlying
+filesystems.
+
+On lookup, the first entry found is chosen. Thus, it is very important the
+underlying filesystems ordering, since the first underlying filesystem will
+be the first one to be searched during lookups, and it is the filesystem
+where new files and directories are written into.
+
+At the moment, underlying filesystem ordering is set by option ordering.
+
+See CAVEAT for other unexpected behaviour that could happen.
+
+The unionfs translator was originally written by Moritz Schulte 
+<moritz@duesseldorf.ccc.de> and currently mantained by Gianluca Guida 
+<glguida@gmail.com>.
+