Documentation: Improve readability

3 files changed, 77 insertions, 75 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4c467c9c..a75afcae 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,10 +6,10 @@
   those in bug reports rather than the usual, single-line error message.
 * Please mention the version of ranger and Python
 * If possible, Please give step-by-step instructions to reproduce the bug.
-* Send security-relevant bugs PGP-encrypted to hut@hut.pm, see HACKING.md
+* Send security-relevant bugs PGP-encrypted to hut@hut.pm, see `HACKING.md`
 
 ## Tips on patching
 
-* See HACKING.md
+* See `HACKING.md`
 
 Thank you!
diff --git a/HACKING.md b/HACKING.md
index a961e2e4..68055555 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -4,21 +4,20 @@ Guidelines for Code Modification
 Coding Style
 ------------
 
-* Use syntax compatible to both python 2.6+ and 3.1+.
-* Use docstrings with pydoc in mind
-* Follow the style guide for python code:
-    http://www.python.org/dev/peps/pep-0008/
-* Test the code with "doctest" where it makes sense
-* when breaking backward compatibility with old configuration files or plugins,
+* Use syntax compatible to both Python 2.6+ and 3.1+.
+* Use docstrings with `pydoc` in mind
+* Follow the style guide for python code: https://www.python.org/dev/peps/pep-0008/
+* Test the code with `doctest` where it makes sense
+* When breaking backward compatibility with old configuration files or plugins,
   please include a temporary workaround code that provides a compatibility
-  layer and mark it with a comment that includes the word "COMPAT".  For
-  examples, grep the code for the word "COMPAT". :)
+  layer and mark it with a comment that includes the word `COMPAT`.  For
+  examples, grep the code for the word `COMPAT`. :)
 
 
 Patches
 -------
 
-Send patches, created with "git format-patch", to the email address
+Send patches, created with `git format-patch`, to the email address
 
     hut@hut.pm
 
@@ -26,17 +25,17 @@ or open a pull request on GitHub.
 
 Please use PGP-encryption for security-relevand patches or messages.  The UIDs
 of my key are `huterich <hut@lavabit.com>` and `hut <hut@hut.pm>`, my
-fingerprint is `1E9B 36EC 051F F6F7 FFC9  69A7 F08C E1E2 00FB 5CDF` and my full
+fingerprint is `1E9B 36EC 051F F6F7 FFC9 69A7 F08C E1E2 00FB 5CDF` and my full
 pubkey is at the very bottom of this file.
 
 
 Version Numbering
 -----------------
 
-Three numbers, A.B.C, where
-* A changes on a rewrite
-* B changes when major configuration incompatibilities occur
-* C changes with each release
+Three numbers, `A.B.C`, where
+* `A` changes on a rewrite
+* `B` changes when major configuration incompatibilities occur
+* `C` changes with each release
 
 
 Starting Points
@@ -44,14 +43,14 @@ Starting Points
 
 Good places to read about ranger internals are:
 
-* ranger/core/actions.py
-* ranger/container/fsobject.py
+* `ranger/core/actions.py`
+* `ranger/container/fsobject.py`
 
 About the UI:
 
-* ranger/gui/widgets/browsercolumn.py
-* ranger/gui/widgets/browserview.py
-* ranger/gui/ui.py
+* `ranger/gui/widgets/browsercolumn.py`
+* `ranger/gui/widgets/browserview.py`
+* `ranger/gui/ui.py`
 
 
 Common Changes
@@ -60,53 +59,51 @@ Common Changes
 Adding options
 --------------
 
-* Add a default value in rc.conf, along with a comment that describes the option.
-* Add the option to the ALLOWED_SETTINGS dictionary in the file
-  ranger/container/settings.py.  Make sure to sort in the new entry
-  alphabetically.
-* Add an entry in the man page by editing doc/ranger.pod, then rebuild the man
-  page by running "make man" in the ranger root directory
+* Add a default value in `rc.conf`, along with a comment that describes the option.
+* Add the option to the `ALLOWED_SETTINGS` dictionary in the file
+  `ranger/container/settings.py` in alphabetical order.
+* Add an entry in the man page by editing `doc/ranger.pod`, then rebuild the man
+  page by running `make man` in the ranger root directory
 
-The setting is now accessible with self.settings.my_option, assuming self is a
-subclass of ranger.core.shared.SettingsAware.
+The setting is now accessible with `self.settings.my_option`, assuming self is a
+subclass of `ranger.core.shared.SettingsAware`.
 
 
 Adding colorschemes
 -------------------
 
-* Copy ranger/colorschemes/default.py to ranger/colorschemes/myscheme.py
+* Copy `ranger/colorschemes/default.py` to `ranger/colorschemes/myscheme.py`
   and modify it according to your needs.  Alternatively, create a subclass of
-  ranger.colorschemes.default.Default and override the "use" method, as it is
-  done in the "Jungle" colorscheme.
+  `ranger.colorschemes.default.Default` and override the `use` method, as it is
+  done in the `Jungle` colorscheme.
 
-* Add this line to your ~/.config/ranger/rc.conf:
-
-    set colorscheme myscheme
+* Add this line to your `~/.config/ranger/rc.conf`:
+  `set colorscheme myscheme`
 
 
 Change which programs start which file types
 --------------------------------------------
 
-Edit the configuration file ~/.config/ranger/rifle.conf.  The default one can
-be obtained by running "ranger --copy-config rifle".
+Edit the configuration file `~/.config/ranger/rifle.conf`.  The default one can
+be obtained by running `ranger --copy-config rifle`.
 
 
 Change which file extensions have which mime type
 -------------------------------------------------
 
-Modify ranger/data/mime.types.  You may also add your own entries to ~/.mime.types
+Modify `ranger/data/mime.types`.  You may also add your own entries to `~/.mime.types`
 
 
 Change which files are previewed in the auto preview
 ----------------------------------------------------
 
-In ranger/container/file.py, change the constant PREVIEW_BLACKLIST
+In `ranger/container/file.py`, change the constant `PREVIEW_BLACKLIST`
 
 
 PGP key
 =======
 
-You may wish to send the author (hut@hut.pm) PGP-encrypted mails for
+You may wish to send the author (`hut@hut.pm`) PGP-encrypted mails for
 security-relevant messages.  This is the authors key.  Save everything from the
 `BEGIN PGP PUBLIC KEY BLOCK` up until the `END PGP PUBLIC KEY BLOCK` message
 into a file and import it with `gpg --import <filename>`.
diff --git a/README.md b/README.md
index b1512797..d1a1da25 100644
--- a/README.md
+++ b/README.md
@@ -5,26 +5,29 @@ ranger v.1.8.1
 
 ranger is a console file manager with VI key bindings.  It provides a
 minimalistic and nice curses interface with a view on the directory hierarchy.
-It ships with "rifle", a file launcher that is good at automatically finding
+It ships with `rifle`, a file launcher that is good at automatically finding
 out which program to use for what file type.
 
 ![screenshot](https://raw.githubusercontent.com/ranger/ranger-assets/master/screenshots/screenshot.png)
 
 This file describes ranger and how to get it to run.  For instructions on the
-usage, please read the man page.  See HACKING.md for development specific
-information.  For configuration, check the files in ranger/config/ or copy the
-default config to ~/.config/ranger with ranger's --copy-config option.  The
-examples/ directory contains several scripts and plugins that demonstrate how
+usage, please read the man page.  See `HACKING.md` for development specific
+information.
+
+For configuration, check the files in `ranger/config/` or copy the
+default config to `~/.config/ranger` with `ranger --copy-config`.
+
+The `examples/` directory contains several scripts and plugins that demonstrate how
 ranger can be extended or combined with other programs.  These files can be
-found in the git repository or in /usr/share/doc/ranger.
+found in the git repository or in `/usr/share/doc/ranger`.
 
-A note to packagers:  Versions meant for packaging are listed in the changelog
+A note to packagers: Versions meant for packaging are listed in the changelog
 on the website.
 
 
 About
 -----
-* Authors:     see "AUTHORS" file
+* Authors:     see `AUTHORS` file
 * License:     GNU General Public License Version 3
 * Website:     http://ranger.nongnu.org/
 * Download:    http://ranger.nongnu.org/ranger-stable.tar.gz
@@ -50,59 +53,61 @@ Features
 * VIM-like console and hotkeys
 * Automatically determine file types and run them with correct programs
 * Change the directory of your shell after exiting ranger
-* Tabs, Bookmarks, Mouse support
+* Tabs, bookmarks, mouse support
 
 
 Dependencies
 ------------
-* Python (tested with version 2.6, 2.7, 3.1-3.5) with the "curses" module
+* Python (tested with version 2.6, 2.7, 3.1-3.5) with the `curses` module
   and (optionally) wide-unicode support.
-* A pager ("less" by default)
+* A pager (`less` by default)
 
 Optional:
 
-* The "file" program for determining file types
-* The python module "chardet", in case of encoding detection problems
-* "sudo" to use the "run as root"-feature
-* w3m for the "w3mimgdisplay" program to preview images
+* The `file` program for determining file types
+* The python module `chardet`, in case of encoding detection problems
+* `sudo` to use the "run as root"-feature
+* `w3m` for the `w3mimgdisplay` program to preview images
 
-Optional, for enhanced file previews (with "scope.sh"):
+Optional, for enhanced file previews (with `scope.sh`):
 
-* img2txt (from caca-utils) for ASCII-art image previews
-* highlight or pygmentize for syntax highlighting of code
-* atool, acat, bsdtar and/or unrar for previews of archives
-* lynx, w3m or elinks for previews of html pages
-* pdftotext for pdf previews
-* transmission-show for viewing bit-torrent information
-* mediainfo or exiftool for viewing information about media files
-* odt2txt for OpenDocument text files (odt, ods, odp and sxw)
+* `img2txt` (from `caca-utils`) for ASCII-art image previews
+* `highlight` or `pygmentize` for syntax highlighting of code
+* `atool`, `acat`, `bsdtar` and/or `unrar` for previews of archives
+* `lynx`, `w3m` or `elinks` for previews of html pages
+* `pdftotext` for pdf previews
+* `transmission-show` for viewing bit-torrent information
+* `mediainfo` or `exiftool` for viewing information about media files
+* `odt2txt` for OpenDocument text files (`odt`, `ods`, `odp` and `sxw`)
 
 
 Installing
 ----------
 Use the package manager of your operating system to install ranger.
-Note that ranger can be started without installing by simply running ranger.py.
+Note that ranger can be started without installing by simply running `ranger.py`.
 
 To install ranger manually:
-
-    sudo make install
+```
+sudo make install
+```
 
 This translates roughly to:
+```
+sudo python setup.py install --optimize=1 --record=install_log.txt
+```
 
-    sudo python setup.py install --optimize=1 --record=install_log.txt
-
-This also saves a list of all installed files to install_log.txt, which you can
+This also saves a list of all installed files to `install_log.txt`, which you can
 use to uninstall ranger.
 
 
 Getting Started
 ---------------
-After starting ranger, you can use the Arrow Keys (or hjkl) to navigate, Enter
-to open a file or type Q to quit.  The third column shows a preview of the
+After starting ranger, you can use the Arrow Keys or `h` `j` `k` `l` to navigate, `Enter`
+to open a file or type `Q` to quit.  The third column shows a preview of the
 current file.  The second is the main column and the first shows the parent
 directory.
 
-Ranger can automatically copy default configuration files to ~/.config/ranger
-if you run it with the switch --copy-config. (see ranger --help for a
-description of that switch.)  Also check ranger/config/ for the default
+Ranger can automatically copy default configuration files to `~/.config/ranger`
+if you run it with the switch `--copy-config`. See `ranger --help` for a
+description of that switch.  Also check `ranger/config/` for the default
 configuration.