--- a/docs/usage/general.rst	Tue Mar 31 16:25:49 2015 +0000
+++ b/docs/usage/general.rst	Tue Mar 31 22:15:38 2015 +0200
@@ -8,48 +8,51 @@
 Repository deleting
 -------------------
 
-Currently when admin/owner deletes a repository, Kallithea does not physically
-delete a repository from filesystem, it renames it in a special way so it's
-not possible to push,clone or access repository. It's worth a notice that,
-even if someone will be given administrative access to Kallithea and will
-delete a repository You can easy restore such action by restoring `rm__<date>`
-from the repository name, and internal repository storage (.hg/.git). There
-is also a special command for cleaning such archived repos::
+Currently when an admin or owner deletes a repository, Kallithea does
+not physically delete said repository from the filesystem, but instead
+renames it in a special way so that it is not possible to push, clone
+or access repository. It is worth noting that even if someone will be
+given administrative access to Kallithea and will delete a repository,
+you can easy restore such an action by removing ``rm__<date>`` from
+the repository name. There is also a special command for cleaning such
+archived repos::
 
     paster cleanup-repos --older-than=30d my.ini
 
-This command will scan for archived repositories that are older than 30d,
-display them and ask if you want to delete them (there's a --dont-ask flag also)
-If you host big amount of repositories with forks that are constantly deleted
-it's recommended that you run such command via crontab.
+This command will scan for archived repositories that are older than
+30 days, display them, and ask if you want to delete them (there is
+a ``--dont-ask`` flag also) If you host a large amount of repositories with
+forks that are constantly deleted it is recommended that you run such a
+command via crontab.
 
 Follow current branch in file view
 ----------------------------------
 
 In file view when this checkbox is checked the << and >> arrows will jump
-to changesets within the same branch currently viewing. So for example
-if someone is viewing files at 'beta' branch and marks `follow current branch`
-checkbox the << and >> buttons will only show him revisions for 'beta' branch
+to changesets within the same branch currently being viewed. So for example
+if someone is viewing files in the ``beta`` branch and marks the `follow current branch`
+checkbox the << and >> buttons will only show revisions for the `'beta`` branch.
 
 
 Compare view from changelog
 ---------------------------
 
-Checkboxes in compare view allow users to view combined compare view. You can
-only show the range between the first and last checkbox (no cherry pick).
-Clicking more than one checkbox will activate a link in top saying
-`Show selected changesets <from-rev> -> <to-rev>` clicking this will bring
-compare view. In this view also it's possible to switch to combined compare.
+Checkboxes in the compare view allow users to view a combined compare
+view. You can only show the range between the first and last checkbox
+(no cherry pick).  Clicking more than one checkbox will activate a
+link at the top saying ``Show selected changesets <from-rev> ->
+<to-rev>``. Clicking this will activate the compare view. In this view
+it is also possible to switch to combined compare.
 
 Compare view is also available from the journal on pushes having more than
-one changeset
+one changeset.
 
 
 Non changeable repository urls
 ------------------------------
 
-Due to complicated nature of repository grouping, often urls of repositories
-can change.
+Due to the complicated nature of repository grouping, URLs of repositories
+can often change.
 
 example::
 
@@ -59,58 +62,56 @@
   http://server.com/test_group/repo_name
 
 This can be an issue for build systems and any other hardcoded scripts, moving
-repository to a group leads to a need for changing external systems. To
-overcome this Kallithea introduces a non changable replacement url. It's
-simply an repository ID prefixed with `_` above urls are also accessible as::
+a repository to a group leads to a need for changing external systems. To
+overcome this Kallithea introduces a non-changable replacement URL. It's
+simply a repository ID prefixed with ``_``. The above URLs are also accessible as::
 
   http://server.com/_<ID>
 
-Since ID are always the same moving the repository will not affect such url.
-the _<ID> syntax can be used anywhere in the system so urls with repo_name
-for changelogs, files and other can be exchanged with _<ID> syntax.
+Since IDs are always the same, moving the repository will not affect
+such a URL.  the ``_<ID>`` syntax can be used anywhere in the system so
+URLs with ``repo_name`` for changelogs and files can be exchanged
+with the ``_<ID>`` syntax.
 
 
 Mailing
 -------
 
-When administrator will fill up the mailing settings in .ini files
-Kallithea will send mails on user registration, or when Kallithea errors occur
-on errors the mails will have a detailed traceback of error.
-
+When the administrator configures the mailing settings in .ini files
+Kallithea will send mails on user registration, or when Kallithea
+errors occur.
 
 Mails are also sent for code comments. If someone comments on a changeset
 mail is sent to all participants, the person who commited the changeset
-(if present in Kallithea), and to all people mentioned with @mention system.
+(if present in Kallithea), and to all people mentioned with the @mention system.
 
 
 Trending source files
 ---------------------
 
-Trending source files are calculated based on pre defined dict of known
-types and extensions. If You miss some extension or Would like to scan some
-custom files it's possible to add new types in `LANGUAGES_EXTENSIONS_MAP` dict
-located in `/kallithea/lib/celerylib/tasks.py`
+Trending source files are calculated based on a pre-defined dict of known
+types and extensions. If you miss some extension or would like to scan some
+custom files, it is possible to add new types in the ``LANGUAGES_EXTENSIONS_MAP`` dict
+located in ``kallithea/lib/celerylib/tasks.py``.
 
 
 Cloning remote repositories
 ---------------------------
 
-Kallithea has an ability to clone remote repos from given remote locations.
-Currently it support following options:
+Kallithea has the ability to clone remote repos from given remote locations.
+Currently it supports the following options:
 
 - hg  -> hg clone
 - svn -> hg clone
 - git -> git clone
 
 
-.. note::
-
-    - *`svn -> hg` cloning requires `hgsubversion` library to be installed.*
+.. note:: svn -> hg cloning requires tge ``hgsubversion`` library to be installed.
 
 If you need to clone repositories that are protected via basic auth, you
-might pass the url with stored credentials inside eg.
-`http://user:passw@remote.server/repo`, Kallithea will try to login and clone
-using given credentials. Please take a note that they will be stored as
+might pass the url with stored credentials inside, e.g.,
+``http://user:passw@remote.server/repo``, Kallithea will try to login and clone
+using the given credentials. Please take note that they will be stored as
 plaintext inside the database. Kallithea will remove auth info when showing the
 clone url in summary page.
 
@@ -121,26 +122,28 @@
 
 
 Visualisation settings in Kallithea settings view are extra customizations
-of server behavior. There are 3 main section in the settings.
+of server behavior. There are 3 main sections in the settings.
 
 General
 ~~~~~~~
 
-`Use repository extra fields` option allows to set a custom fields for each
-repository in the system. Each new field consists of 3 attributes `field key`,
-`field label`, `field description`. Example usage of such fields would be to
-define company specific information into repositories eg. defining repo_manager
-key that would add give info about a manager of each repository. There's no
-limit for adding custom fields. Newly created fields are accessible via API.
+The `Use repository extra fields` option allows to set a custom fields
+for each repository in the system. Each new field consists of 3
+attributes: ``field key``, ``field label``, ``field
+description``. Example usage of such fields would be to define company
+specific information into repositories, e.g., defining a
+``repo_manager`` key that would give info about a manager of each
+repository. There's no limit for adding custom fields. Newly created
+fields are accessible via API.
 
-`Show Kallithea version` option toggles displaying exact Kallithea version in
-the footer
+The `Show Kallithea version` option toggles displaying the exact
+Kallithea version in the footer
 
 
 Dashboard items
 ~~~~~~~~~~~~~~~
 
-Number if items in main page dashboard before pagination is displayed
+Number of items in main page dashboard before pagination is displayed.
 
 
 Icons