Rewrote the manual to use the active voice.

1 files changed, 65 insertions, 66 deletions

diff --git a/doc/08_Preferences.md b/doc/08_Preferences.md
index d1acabc5..447d7ef9 100644
--- a/doc/08_Preferences.md
+++ b/doc/08_Preferences.md
@@ -1,6 +1,6 @@
 # Preferences
 
-At this point it is assumed you are at least familiar with the basics of
+At this point the manual assumes you are at least familiar with the basics of
 [Lua][]. You do not have to know a lot of the language to configure Textadept.
 
 [Lua]: http://www.lua.org
@@ -8,36 +8,36 @@ At this point it is assumed you are at least familiar with the basics of
 ## User Init
 
 Textadept executes a *~/.textadept/init.lua*, your user-init file, on startup.
-If this file does not exist, Textadept creates it for you. You can use the file
+If this file does not exist, Textadept creates it for you. This file allows you
 to indicate what you want Textadept to do when the application starts, such as
-changing the settings of existing modules, loading new ones, and/or running
-plain Lua code.
+change the settings of existing modules, load new ones, and/or run plain Lua
+code.
 
 ### Modules
 
-It is never recommended to modify the default modules that come with Textadept,
-even if you just want to change an option in a generic module, modify the buffer
+Try to refrain from modifying the default modules that come with Textadept, even
+if you just want to change an option in a generic module, modify the buffer
 settings for a language-specific module, edit file types, or add a small bit of
-custom code. Those changes may be overwritten when you upgrade Textadept to a
-newer version. Instead you have two options: load your own module instead of the
-default one, or run your custom module code after the default module loads. For
-the most part you will want to use the second option because it is simpler and
-more compatible with future releases. Both options are discussed below in the
-context of generic and language-specific modules.
+custom code. Upgrading Textadept to a new version may overwrite those changes.
+Instead you have two options: load your own module instead of the default one,
+or run your custom module code after the default module loads. For the most
+part, use the second option because it is simpler and more compatible with
+future releases. The manual discusses both options below in the context of
+generic and language-specific modules.
 
 #### Generic
 
-Many of Textadept's generic modules have settings you can change from
-*~/.textadept/init.lua* after the module is loaded. These settings are viewed
-from module's [LuaDoc][]. For example, to disable character autopairing with
-typeover and stripping whitespace on save, your *~/.textadept/init.lua* would
-contain:
+Many of Textadept's generic modules have configurable settings changeable from
+*~/.textadept/init.lua* after Textadept loads the module. The module's
+[LuaDoc][] lists these settings. For example, to disable character autopairing
+with typeover and stripping whitespace on save, add the following to your
+*~/.textadept/init.lua*:
 
     _M.textadept.editing.AUTOPAIR = false
     _M.textadept.editing.TYPEOVER_CHARS = false
     _M.textadept.editing.STRIP_WHITESPACE_ON_SAVE = false
 
-Now suppose you wanted to load all of Textadept's default modules except for the
+Now suppose you want to load all of Textadept's default modules except for the
 menu. You cannot do this after-the-fact from *~/.textadept/init.lua*. Instead
 you need Textadept to load your own module rather than the default one. Copy the
 `textadept` module's *init.lua* (located in the *modules/textadept/* directory)
@@ -49,11 +49,11 @@ to
 
     --M.menu = require 'textadept.menu'
 
-Now when Textadept looks for *modules/textadept/init.lua*, it will load yours
-in place of its own, and load everything but the menu. If instead you wanted to
-completely change the menu structure, you would first create a new *menu.lua*
-and then put it in *~/.textadept/modules/textadept/*. Textadept will now load
-your *menu.lua* rather than its own.
+Now when Textadept looks for *modules/textadept/init.lua*, it loads yours in
+place of its own, thus loading everything but the menu. If instead you want to
+completely change the menu structure, first create a new *menu.lua* and then put
+it in *~/.textadept/modules/textadept/*. Textadept now loads your *menu.lua*
+rather than its own.
 
 [LuaDoc]: api/index.html
 
@@ -63,21 +63,21 @@ Similar to generic modules, putting your own language-specific module in
 *~/.textadept/modules/* causes Textadept to load that module for editing the
 language's code instead of the default one in *modules/* (if the latter exists).
 For example, copying the default Lua language-specific module from
-*modules/lua/* to *~/.textadept/modules/* causes Textadept to use that module
-for editing Lua code in place of the default one. However, if you make custom
+*modules/lua/* to *~/.textadept/modules/* results in Textadept loading that
+module for editing Lua code in place of its own. However, if you make custom
 changes to that module and upgrade Textadept later, the module may no longer be
-compatible. Rather than potentially wasting time merging changes, you can run
-custom code independent of a module in the module's *post_init.lua* file. For
-example, instead of copying the `lua` module and creating an
-`events.LANGUAGE_MODULE_LOADED` event handler to use tabs, you can do this from
-*~/.textadept/modules/lua/post_init.lua*:
+compatible. Rather than potentially wasting time merging changes, run custom
+code independent of a module in the module's *post_init.lua* file. In this case,
+instead of copying the `lua` module and creating an
+`events.LANGUAGE_MODULE_LOADED` event handler to use tabs, simply put the event
+handler in *~/.textadept/modules/lua/post_init.lua*:
 
     events.connect(events.LANGUAGE_MODULE_LOADED, function(lang)
       if lang == 'lua' then buffer.use_tabs = true end
     end)
 
-Similarly, you can use *post_init.lua* to change the module's
-[compile and run][] commands, load more [Adeptsense tags][], and add additional
+Similarly, use *post_init.lua* to change the module's [compile and run][]
+commands, load more [Adeptsense tags][], and add additional
 [key bindings](#Key.Bindings) and [snippets](#Snippets) (instead of in
 *~/.textadept/init.lua*). For example:
 
@@ -93,15 +93,15 @@ Similarly, you can use *post_init.lua* to change the module's
 
 ### Loading Modules
 
-Suppose you created or downloaded a generic module called `foo` that you wanted
-to load along with the default modules Your *~/.textadept/init.lua* would
-contain the following:
+After creating or downloading a generic module called `foo` that you want to
+load along with the default modules, simply add the following to your
+*~/.textadept/init.lua*:
 
     _M.foo = require 'foo'
 
-Language-specific modules are loaded automatically by Textadept when a source
-file of that language is opened. No additional action is required after
-installing the module.
+Textadept automatically loads language-specific modules when opening a source
+file of that language, so simply installing the language-specific module is
+sufficient.
 
 ### Key Bindings
 
@@ -109,41 +109,41 @@ For simple changes to key bindings, *~/.textadept/init.lua* is a good place to
 put them. For example, maybe you want `Ctrl+Shift+C` to create a new buffer
 instead of `Ctrl+N`:
 
-    keys.cC = new_buffer
+    keys.cC = buffer.new
     keys.cn = nil
 
-If you plan on redefining most key bindings, you would probably want to copy or
-create a new *keys.lua* and then put it in *~/.textadept/modules/textadept/*.
-You can learn more about key bindings and how to define them in the
+If you plan on redefining most key bindings, copy or create a new *keys.lua* and
+put it in *~/.textadept/modules/textadept/* to get Textadept to load your set
+instead of its own. Learn more about key bindings and how to define them in the
 [key bindings LuaDoc][].
 
 [key bindings LuaDoc]: api/keys.html
 
 ### Snippets
 
-You can add global snippets in *~/.textadept/init.lua*, such as:
+Define your own global snippets in *~/.textadept/init.lua*, such as:
 
     snippets['file'] = '%<buffer.filename>'
     snippets['path'] = "%<(buffer.filename or ''):match('^.+[/\\]')>"
 
 So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX | `Tab` in
-curses) will insert the snippet, regardless of the current programming language.
-You can learn about snippet syntax in the [snippets LuaDoc][].
+curses) inserts the snippet, regardless of the current programming language.
+Learn more about snippet syntax in the [snippets LuaDoc][].
 
 [snippets LuaDoc]: api/_M.textadept.snippets.html
 
 ## Buffer Settings
 
-Since *~/.textadept/init.lua* is only run once on startup, it is not the
+Since Textadept runs *~/.textadept/init.lua* only once on startup, it is not the
 appropriate place to set per-buffer properties like indentation size or
 view-related properties like the behaviors for scrolling and autocompletion.
 If you do set such properties in *~/.textadept/init.lua*, those settings only
 apply to the first buffer and view -- subsequent buffers and split views will
 not inherit those settings. Instead, put your settings in a
-*~/.textadept/settings.lua* file which is run each time a new buffer or split
-view is created. Any settings there override Textadept's default *settings.lua*
-settings. For example, to use tabs rather than spaces and have a tab size of 4
-spaces by default your *~/.textadept/settings.lua* would contain:
+*~/.textadept/settings.lua* file which runs after creating a new buffer or split
+view. Any settings there override Textadept's default *settings.lua* settings.
+For example, to use tabs rather than spaces and have a tab size of 4 spaces by
+default, your *~/.textadept/settings.lua* would contain:
 
     buffer.tab_width = 4
     buffer.use_tabs = true
@@ -151,11 +151,10 @@ spaces by default your *~/.textadept/settings.lua* would contain:
 (Remember that in order to have per-filetype properties, you need to have a
 [language-specific module][].)
 
-You can use Textadept's *settings.lua* as a reference to see what properties are
-available. It also has many commented out properties that you can copy to your
-*~/.textadept/settings.lua* and uncomment to turn on or change the value of. You
-can use [Adeptsense][] to view a property's documentation or read the
-[LuaDoc][].
+Textadept's *settings.lua* is a good reference to see available properties to
+set. It also has many commented out properties that you can copy to your
+*~/.textadept/settings.lua* and uncomment to turn on or change the value of. Use
+[Adeptsense][] to view a property's documentation or read the [LuaDoc][].
 
 [language-specific module]: 07_Modules.html#Buffer.Properties
 [Adeptsense]: 06_AdeptEditing.html#Adeptsense
@@ -164,12 +163,12 @@ can use [Adeptsense][] to view a property's documentation or read the
 ## Locale
 
 Textadept attempts to auto-detect your locale settings using the "$LANG"
-environment variable. If it is unsuccessful, the English locale is used by
-default. To set the locale manually, copy the desired locale file from the
-*core/locales/* folder to *~/.textadept/locale.conf*. If your language is not
-yet supported by Textadept, please translate the English messages in
-*core/locale.conf* to your language and send the modified *locale.conf* file to
-[me][]. I will include it in a future release.
+environment variable, falling back on the English locale. To set the locale
+manually, copy the desired locale file from the *core/locales/* folder to
+*~/.textadept/locale.conf*. If Textadept does not support your language yet,
+please translate the English messages in *core/locale.conf* to your language and
+send the modified *locale.conf* file to [me][]. I will include it in a future
+release.
 
 [me]: README.html#Contact
 
@@ -182,8 +181,8 @@ following:
 * Keywords in the file's shebang ("#!/path/to/exe") line.
 * A pattern that matches the text of the file's first line.
 
-Built-in file types are located in *modules/textadept/mime_types.conf*. You
-can override or add to them in your *~/.textadept/mime_types.conf*:
+*modules/textadept/mime_types.conf* contains built-in file types. Override or
+add to them in your *~/.textadept/mime_types.conf*:
 
     % Recognize .luadoc files as Lua code.
     luadoc lua
@@ -216,8 +215,8 @@ lexer is:
 
     /pattern lexer
 
-[Lua pattern syntax][] is used. Only the last space, the one separating the
-pattern from the lexer, is significant. No spaces in the pattern need to be
-escaped.
+Patterns use [Lua pattern syntax][] with only the last space, the one separating
+the pattern from the lexer, being significant. No spaces in the pattern need
+escaping.
 
 [Lua pattern syntax]: 14_Appendix.html#Lua.Patterns