Lots of docs, some cosmetic changes

git-svn-id: http://pyfilesystem.googlecode.com/svn/trunk@637 67cdc799-7952-0410-af00-57a81ceafa0f

1 files changed, 24 insertions, 0 deletions

diff --git a/docs/opening.rst b/docs/opening.rst
new file mode 100644
index 0000000..5bfe120
--- /dev/null
+++ b/docs/opening.rst
@@ -0,0 +1,24 @@
+Opening Filesystems
+===================
+
+Generally, when you want to work with the files and directories of any of the supported filesytems,
+you create an instance of the appropriate class. For example, the following opens the directory /foo/bar::
+
+	from fs.osfs import OSFS
+	my_fs = OSFS('/foo/bar')
+
+This is fine if you know beforehand where the directory you want to work with is located, and on what medium.
+However, there are occasions where the location of the files may change at runtime or should be specified in a config file or from the command line.
+
+In these situations you can use an _opener_ which is a generic way of specifying a filesystem. For example, the following is equivalent to the code above::
+	
+	from fs.opener import fsopen
+	my_fs = fsopen('/foo/bar')
+
+The `fsopen` method takes a string that identifies the filesystem, but if called with a regular path, it will return an OSFS instance.
+To open a different kind of filesystem, you specify it with a URI like syntax. The following code opens an ftp filesystem rather than a directory on your harddrive::
+
+	from fs.opener import fsopen
+	my_fs = fsopen('ftp://example.org/foo/bar')
+
+For further information regarding filesystem openers see :doc:`opener`.
\ No newline at end of file