Documentation updates, permissions diagrams and inkscape sources

docs/topics/file_storage.rst

@@ -7,15 +7,9 @@ filename clashes (each file gets renamed to its UUID and with an extension)
 and stored in a simple flat arrangement in a directory.  This doesn't
 stop access to the files but it is not recommended because moving,
 renaming or updating the files directly would throw the database out
-of sync.  For access to the files the recommended way is to create and
-index which would create a directory tree like structure in the database
-and then turn on the index filesystem mirror options which would create
-an actual directory tree and links to the actual stored files but using
-the filename of the documents as stored in the database.  This
-filesystem mirror of the index can them be shared with Samba_ across the
-network.  This access would be read-only, and new versions of the files
-would have to be uploaded from the web GUI using the new document
-versioning support.
+of sync.  For direct access to the files the recommended way is to create an
+:doc:`index <indexes>`, use the indexing mirroring feature and share the result via 
+file serving software [#f1]_.
 
 **Mayan EDMS** components are as decoupled from each other as possible,
 storage in this case is very decoupled and its behavior is controlled
@@ -27,4 +21,6 @@ network or even across the internet and still operate exactly the same.
 The file storage behavior is controlled by the :setting:`DOCUMENTS_STORAGE_BACKEND`
 and should be set to a class or subclass of Django's ``django.core.files.storage.FileSystemStorage`` class.
 
-.. _Samba: http://www.samba.org/
+.. rubric:: Footnotes
+
+.. [#f1] http://en.wikipedia.org/wiki/File_server

docs/topics/indexes.rst

@@ -5,8 +5,20 @@ Indexes
 Administrators first define the template of the index and an instance
 of the index is then auto-populated with links to the documents depending
 on the rules of each branch of the index evaluated againts the metadata
-of the documents.  The index cannot be edited manually, only changing
+of the documents.  Indexes can be mirrored to the operating system filesystem
+using the configuration option
+:setting:`DOCUMENT_INDEXING_FILESYSTEM_SERVING`.  This creates an actual
+directory tree and links to the actual stored files but using
+the filename of the documents as stored in the database.  This
+filesystem mirror of the index can them be served with Samba_ across the
+network.  This access would be read-only, and new versions of the files
+would have to be uploaded from the web GUI using the new document
+versioning support.
+
+The index cannot be edited manually, only changing
 the rules or the metadata of the documents would cause the index to be
 regenerated.  For manual organization of documents there are the folders,
 their structure is however flat, and they have to be manually updated and
 curated.
+
+.. _Samba: http://www.samba.org/

docs/topics/permissions.rst

@@ -12,6 +12,9 @@ perform.  This control is divided into two levels of operation:
   this method could be thought out as a global permission granting level.
   Example: Roles being granted the ``Document view`` permission will be able to view
   **all** documents in existance.
+
+  .. image:: permissions.png
+     :alt: 2-tier permission diagram
   
 * 3-tier access control - When more control is desired over which objects
   actors(user, groups and roles) can exercise an action this method should be
@@ -19,6 +22,9 @@ perform.  This control is divided into two levels of operation:
   permission but only in relation to a selected object.  Example: Granting user
   ``Joe`` the ``Document view`` access control for document ``Payroll``,
   would allow him to view this document only.
+
+  .. image:: ACL.png
+     :alt: 3-tier access control diagram
   
 The permission system enforces inheritance by first checking if the user
 has a global permission, is a member of a group or a role that has a global
@@ -30,3 +36,4 @@ is forbidden to perform the action and a generic message indicating this is
 displayed to avoid providing any information that could be used to sidetrack
 the permission system or obtain any kind of information about the object
 from which the user was not allowed access.
+