documentation fixes

3 files changed, 68 insertions, 63 deletions

diff --git a/docs/source/api.rst b/docs/source/api.rst
index 1397732..502db1e 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -11,7 +11,7 @@ logfs.fstracer
 package_utils
 ================================
 
-This package contains modules which works with the Portage system
+This package contains modules which work with the Portage system
 
 .. automodule:: package_utils.portage_log_parser
    :members:
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
index 59b55f8..2caec16 100644
--- a/docs/source/architecture.rst
+++ b/docs/source/architecture.rst
@@ -13,66 +13,71 @@ Format of network messages
 --------------------------
 
 
-1. Format of messages to file access registrar::
+1. Format of messages to the File Access Registrar::
 
    <time of event: sec since 1970>
    <event type: open, read, write>
    <name of file>
    <building stage: stagename or unknown>
    <result:OK,ERR/errno,ASKING,DENIED>
-2. Format of answer for ASKING packet from registrar::
+2. Format of answer for ASKING packet from File Access Registrar::
 
    <ALLOW | DENY>
 
 *Notes:*
 
 * All sockets are SOCK_SEQPACKET
-* All fields are delimited with character with code 0
+* All fields are delimited with character \0
 
 
-How Hooklib approach works?
-===========================
+How does the Hooklib approach work?
+===================================
 
-The main idea of Hooklib approach is to load a dynamic library-hooker 
-**before** any other library(including the C runtime, libc.so). 
-So, the functions, such as open, read and write, executed from this library
-instead of libc.so.
+The main idea behind the Hooklib approach is to load a dynamic library-hook 
+**before** any other library(including the C runtime). 
+So, the calls to functions such as open, read and write, are intercepted 
+using this library, instead of executing the ones in *libc*.
 
-Hooklib module modifies Linux's dynamic linker behavior changing LD_PRELOAD 
-environment variable(see 
+Hooklib module modifies Linux's dynamic linker behavior, changing LD_PRELOAD 
+environment variable (see 
 `man 8 ld-linux <http://linux.die.net/man/8/ld-linux>`_ for details).
-Module protects LD_PRELOAD variable from further changes by program.
+This module also protects LD_PRELOAD variable from further changes by executing 
+program.
 
-When hooklib module loads, it connects to file access registrar via Unix domain 
-sockets. If program forks or creates a new thread, another copy of library 
-loads. 
+When Hooklib is loaded, it connects to the File Access Registrar via Unix domain 
+sockets. If a program forks or creates a new thread, another copy of the library 
+loads to register events from this new process/thread. 
 
-When program do open(...), read(...), write(...), library send an information 
-about a call to registrar. Registar can block or allow an event. If registrer 
-allows an event then the original function is called. Else error 
-"file not found" is returned.
+When a program calls open(...), read(...), write(...), Hooklib sends a message  
+about a call to the File Access Registrar. The Registar can then block 
+or allow this event. If Registrar responds to the previous query with 
+an ALLOW packet, then the original function is called. Otherwise, the function 
+is not called and a "File not Found" error is returned instead.
 
-How Fusefs approach works?
-==========================
+How does the Fusefs approach work?
+==================================
 
-The main idea if Fusefs approach is to create a loggable filesystem in userspace
-and chroot a program into it.
+The main idea of the Fusefs approach is to create a loggable filesystem in userspace
+and jail a program into it, using a chroot.
 
-Before program is launched registrar prepare mounts. It usually do:
+Before the program is launched, The File Access Registrar prepare the mounts. 
+It would usually take the following steps:
 
 1. mount -o bind / /mnt/rootfs/
-2. mount /dev/, /dev/pts, /dev/shm, /proc/, /sys/ same way
+2. mount /dev, /dev/pts, /dev/shm, /proc/, /sys/ binding them to /mnt/rootfs
 3. mount /lib64/, /lib32/, /var/tmp/portage/ same way to increase performance at 
    cost of accuracy
-4. launch fuse over /mnt/rootfs/
+4. launch FUSE over /mnt/rootfs/
 
-Fuse module blocks all external access to /mnt/rootfs while program runs.
-
-Fuse module also asks the registrar about event allowness.
+Fuse module blocks all external access to /mnt/rootfs while the program runs.
+The FUSE module will also ask the File Access Registrar to check whether access to 
+files inside the chroot are allowed or denied. As with the Hooklib approach, if 
+access to a file is denied, a "File not Found" error is returned.
 
 *Notes:*
 
-* Checking for allowness takes a much time
+* Checking for permission to access a file with the File Access Registrar, takes a 
+lot of time under this approach.
 
 Futher analysis of file access events
 =====================================
@@ -90,6 +95,6 @@ unuseful packages.
 Rules of heuristics
 -------------------
 
-1. *Package is not useful if all files are .desktop or .xml or .m4*.
+1. *Package is not useful if all files are .desktop, .xml or .m4*.
    Aclocal util tries to read all .m4 files in /usr/share/aclocal directory.
-   Files ending on .desktop and .xml often readed on postrm phase.
\ No newline at end of file
+   Files ending on .desktop and .xml are often read in the postrm phase.
\ No newline at end of file
diff --git a/docs/source/man.rst b/docs/source/man.rst
index b49fb54..bf5ad86 100644
--- a/docs/source/man.rst
+++ b/docs/source/man.rst
@@ -10,10 +10,10 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-Auto dependency builder is a tool for analysis files accessed during 
-building a package. It also can be used for runtime dependencies analysis.
+Auto dependency (autodep) builder is a tool for the analysis of accessed files during 
+the build of a package. It also can be used for runtime dependencies analysis.
 
-The tool can block an access to files of defined packages.
+The tool can trace, log and block access to files of given packages.
 
 OPTIONS
 =======
@@ -22,78 +22,78 @@ OPTIONS
 
 .. cmdoption:: --help, -h
 
-   show this help message and exit
+   Show this help message and exit.
 
 .. cmdoption:: -b, --block
 
-   strict mode: deny all access to non-dependency packages
+   strict mode: Deny all access to files from non-dependency packages.
 
 .. cmdoption:: --blockpkgs=PACKAGES
 
-   block an access to files from this packages
+   Block access to files from this packages.
 
 .. cmdoption:: -f, --files 
 
-   show accessed files and not founded files
+   Show all files, accessed and missing (not found).
 .. cmdoption:: -v, --verbose 
 
-   show non-important packages, show unknown package and unknown stage
+   Show non-important packages, unknown packages and unknown building stages.
 .. cmdoption:: --nocolor, -C
 
-   don't output color
+   Don't colorize output
 .. cmdoption:: --hooklib
 
-   use ld_preload logging approach(default)
+   Use LD_PRELOAD logging approach (default).
 .. cmdoption:: --fusefs
 
-   use fuse logging approach(slow, but reliable)
+   Use FUSE logging approach (slow, but reliable).
 
 HOOKLIB VS FUSEFS
 =================
 
 +------------------------------------------------+-------------+---------------+
-|                                                |   Hooklib   |     Fusefs    |
+|                                                |   Hooklib   |     FuseFS    |
 +================================================+=============+===============+
 | Who can use this approach?                     | **Any user**|   Only root   |
 +------------------------------------------------+-------------+---------------+
-| Is approach allows blocking an access to files?|  **YES**    | **YES**       |
+| Does approach allows to block access to files? |  **YES**    | **YES**       |
 +------------------------------------------------+-------------+---------------+
-| Is overhead in performance big?                |  **NO**     | YES [#f1]_    |
+| Is the overhead in performance noticeable?     |  **NO**     | YES [#f1]_    |
 +------------------------------------------------+-------------+---------------+
 | What events are logged?                        |  Most [#f2]_| **ALL**       |
 +------------------------------------------------+-------------+---------------+
-| When is it recomended to use an approach?      | For analysis| For analysis  |
+| When is it recomended to use an approach?      | Analysis    | Analysis      |
 |                                                | of          | of *runtime*  |
 |                                                | *buildtime* | dependencies  |
 |                                                | dependencies|               |
 +------------------------------------------------+-------------+---------------+
-| Is any pre-requirements for using an approach? | **NO**      | FUSE must be  |
-|                                                |             | enabled in    |
+| Are there any pre-requirements                 | **NO**      | FUSE must be  |
+| for using an approach?                         |             | enabled in    |
 |                                                |             | kernel        |
 +------------------------------------------------+-------------+---------------+
 
 .. rubric:: Notes
 
-.. [#f1] Fuse file system is slower than normal one. Program reads many files 
+.. [#f1] FUSE filesystems are slower than a normal one. A Program accesses many files 
    while launching, so this will take more time than usual.
-.. [#f2] Loading of dynamic libraries and direct syscalls will not be logged.
+.. [#f2] Loading of Dynamic libraries and direct syscalls will not be logged.
 
 Examples
 ========
 
-Get the potential dependencies of a xchat package:
------------------------------------------------------
-autodep emerge xchat
+Get the potential dependencies for net-irc/xchat:
+-------------------------------------------------
+autodep emerge net-irc/xchat
 
-Get the potential dependencies of a xchat package, blocking x11-misc/util-macros package:
---------------------------------------------------------------------------------------------
-autodep emerge --block x11-misc/util-macros emerge xchat
+Get the potential dependencies for net-irc/xchat, blocking files from x11-misc/util-macros package:
+---------------------------------------------------------------------------------------------------
+autodep emerge --block x11-misc/util-macros emerge net-irc/xchat
 
-Get the potential dependencies of a xchat package, and show files accessed:
-------------------------------------------------------------------------------
-autodep --files emerge xchat
+Get the potential dependencies for net-irc/xchat package, and show accessed files:
+----------------------------------------------------------------------------------
+autodep --files emerge net-irc/xchat
 
-Get the runtime dependencies of a xchat and show files accessed:
--------------------------------------------------------------------
+Get the runtime dependencies of a xchat and show accessed files:
+----------------------------------------------------------------
 autodep --fusefs --files xchat