Code and documentation cleanup.

9 files changed, 46 insertions, 46 deletions

diff --git a/core/events.lua b/core/events.lua
index 5e830c79..f4461c58 100644
--- a/core/events.lua
+++ b/core/events.lua
@@ -174,7 +174,7 @@ local M = {}
 --   * _`alt`_: The "Alt"/"Option" modifier key is held down.
 --   * _`meta`_: The "Control" modifier key on Mac OSX is held down.
 -- @field MARGIN_CLICK (string)
---   Emitted when clicking the mouse inside a margin.
+--   Emitted when clicking the mouse inside a sensitive margin.
 --   Arguments:
 --
 --   * _`margin`_: The margin number clicked.
diff --git a/core/file_io.lua b/core/file_io.lua
index 17ca2824..ce3bf8ec 100644
--- a/core/file_io.lua
+++ b/core/file_io.lua
@@ -184,7 +184,7 @@ function io.reload_file()
 end
 
 ---
--- Converts the current buffer's contents to string encoding *encoding*.
+-- Converts the current buffer's contents to encoding *encoding*.
 -- @param encoding The string encoding to set. Valid encodings are ones that GNU
 --   iconv accepts.
 -- @usage io.set_buffer_encoding('ASCII')
diff --git a/core/keys.lua b/core/keys.lua
index bcfc8f7c..2278d247 100644
--- a/core/keys.lua
+++ b/core/keys.lua
@@ -27,10 +27,10 @@ local M = {}
 -- ## Key Sequences
 --
 -- Key sequences are strings built from an ordered combination of modifier keys
--- and the key itself. Modifier keys are "Control", "Shift", and "Alt" on
--- Windows, Linux, BSD, and in curses. On Mac OSX they are "Control" (`^`),
--- "Alt/Option" (`⌥`), "Command" (`⌘`), and "Shift" (`⇧`). These modifiers have
--- the following string representations:
+-- and the key's inserted character. Modifier keys are "Control", "Shift", and
+-- "Alt" on Windows, Linux, BSD, and in curses. On Mac OSX they are "Control"
+-- (`^`), "Alt/Option" (`⌥`), "Command" (`⌘`), and "Shift" (`⇧`). These
+-- modifiers have the following string representations:
 --
 -- Modifier | Linux / Win32 | Mac OSX | curses   |
 -- ---------|---------------|---------|----------|
diff --git a/doc/04_WorkingWithFiles.md b/doc/04_WorkingWithFiles.md
index c8fc43c5..4a941a40 100644
--- a/doc/04_WorkingWithFiles.md
+++ b/doc/04_WorkingWithFiles.md
@@ -29,16 +29,16 @@ Textadept shows the name of the active buffer in its titlebar. Pressing
 
 Individual files have three configurable settings: indentation, line endings,
 and encoding. Indentation consists of an indentation character and an
-indentation size. Line endings are characters that separate lines. File
-encoding determines how text characters are displayed. Textadept shows these
+indentation size. Line endings are the characters that separate lines. File
+encoding specifies how to display text characters. Textadept shows these
 settings in the buffer status statusbar.
 
 ![Document Statusbar](images/docstatusbar.png)
 
 #### Indentation
 
-Usually, [language modules][] or [user settings][] dictate the buffer's
-indentation setting. By default, indentation is 2 spaces. Pressing
+Normally, a [language module][] or the [user settings][] dictate a buffer's
+indentation settings. By default, indentation is 2 spaces. Pressing
 `Ctrl+Alt+Shift+T` (`^⇧T` on Mac OSX | `M-T` or `M-S-T` in curses) manually
 toggles between using tabs and spaces, although this only affects future
 indentation. Existing indentation remains unchanged. `Ctrl+Alt+I` (`^I` | `M-I`)
@@ -46,25 +46,24 @@ performs the conversion. (If the buffer uses tabs, all indenting spaces convert
 to tabs. If the buffer uses spaces, all indenting tabs convert to spaces.)
 Similarly, the "Buffer -> Indentation" menu manually sets indentation size.
 
-[language modules]: 07_Modules.html#Buffer.Properties
+[language module]: 07_Modules.html#Buffer.Properties
 [user settings]: 08_Preferences.html#Buffer.Properties
 
 #### Line Endings
 
-The current platform determines which line endings, commonly known as
-end-of-line (EOL) markers, to use by default. On Windows it is CRLF ("\r\n"). On
-all other platforms it is LF ('\n'). Textadept first tries to auto-detect the
-EOL mode of opened files before falling back on the platform default. The
-"Buffer -> EOL Mode" menu manually changes line endings and, unlike indentation
-settings, automatically converts all existing EOLs.
+Textadept determines which default line endings, commonly known as end-of-line
+(EOL) markers, to use based on the current platform. On Windows it is CRLF
+("\r\n"). On all other platforms it is LF ('\n'). Textadept first tries to
+auto-detect the EOL mode of opened files before falling back on the platform
+default. The "Buffer -> EOL Mode" menu manually changes line endings and, unlike
+indentation settings, automatically converts all existing EOLs.
 
 #### Encodings
 
-Textadept represents all characters and strings internally as UTF-8. UTF-8 is
-compatible with ASCII so those files are always detected properly. Textadept
-also recognizes ISO-8859-1 and MacRoman, two common encodings used on Windows
-and Mac OSX respectively. If you work with files whose encodings Textadept does
-not recognize, add the encodings to [`io.encodings`][] in your [preferences][].
+Textadept has the ability to decode files encoded in many different encodings,
+but by default it only attempts to decode UTF-8, ASCII, ISO-8859-1, and
+MacRoman. If you work with files with encodings Textadept does not recognize,
+add those encodings to [`io.encodings`][] in your [preferences][].
 
 UTF-8 is the recommended file encoding because of its wide support by other text
 editors and operating systems. The "Buffer -> Encoding" menu changes the file
diff --git a/doc/06_AdeptEditing.md b/doc/06_AdeptEditing.md
index 2176c39a..38f824a9 100644
--- a/doc/06_AdeptEditing.md
+++ b/doc/06_AdeptEditing.md
@@ -10,12 +10,12 @@ manual discusses more elaborate editing features below.
 
 ### Autopaired Characters
 
-Usually, quote (''', '"') and brace ('(', '[', '{') characters go
-together in pairs. By default, Textadept automatically inserts complement
-characters and allows you to type over them. Similarly, the editor deletes the
-complement when you press `Bksp` (`⌫` on Mac OSX | `Bksp` in curses) over the
-first. The [preferences][] page details how to disable these features if you
-find them unsuitable.
+Usually, brace ('(', '[', '{') and quote (''', '"') characters go
+together in pairs. Textadept automatically inserts the complement character of
+any user-typed opening brace or quote character and allows the user to
+subsequently type over it. Similarly, the editor deletes the complement when
+you press `Bksp` (`⌫` on Mac OSX | `Bksp` in curses) over the first. The
+[preferences][] page details how to configure or disable these features.
 
 [preferences]: 08_Preferences.html#Generic
 
@@ -32,8 +32,8 @@ word.
 ### Virtual Space Mode
 
 Pressing `Ctrl+Alt+Shift+V` (`^⇧V` in Mac OSX | none in curses) enables and
-disables Virtual space (freehand) mode. When enabled, line endings do not
-restrict caret movement.
+disables Virtual space (freehand) mode. When virtual space is enabled, the caret
+may move into the space past the ends of lines.
 
 ### Overwrite Mode
 
@@ -44,7 +44,7 @@ characters. The caret also changes to an underline in overwrite mode.
 ## Selections
 
 Textadept includes many ways of creating and working with selections. Creating
-basic selections entails holding down the "Shift" modifier key while pressing
+basic selections entails holding down the "Shift" modifier key and then pressing
 the arrow keys, clicking and dragging the mouse cursor over a range of text, or
 pressing `Ctrl+A` (`⌘A` | `M-A`) to select all text. Creating more advanced
 selections like multiple and rectangular selections requires slightly more
@@ -52,20 +52,21 @@ effort, but has powerful uses.
 
 ### Multiple Selection
 
-Clicking the mouse at a point in the buffer while holding the "Control" modifier
-key places an additional caret at that point. Clicking and dragging while
-holding the same modifier creates multiple selections. Textadept will now mirror
-typed text at each selection.
+Holding down the "Control" modifier key and then clicking and dragging the mouse
+cursor over ranges of text creates multiple selections. Holding "Control" and
+then clicking without dragging places an additional caret at the clicked
+position. Textadept mirrors any typed text at each selection.
 
 Textadept curses does not support creating multiple selections with the mouse.
 
 ### Rectangular Selection
 
-Holding `Alt+Shift` (`⌥⇧` on Mac OSX | `M-S-` in curses) and pressing the arrow
-keys creates a rectangular selection. A rectangular selection spanning multiple
-lines allows typing on each line. Holding the `Alt` modifier key (`Super` on
-Linux) while clicking and dragging the mouse also creates a rectangular
-selection.
+Rectangular selections are a more structured form of multiple selections. A
+rectangular selection spanning multiple lines allows typing on each line.
+Holding `Alt+Shift` (`⌥⇧` on Mac OSX | `M-S-` in curses) and then pressing the
+arrow keys creates a rectangular selection. Holding the `Alt` modifier key
+(`Super` on Linux) and then clicking and dragging the mouse cursor also creates
+a rectangular selection.
 
 ![Rectangular Selection](images/rectangularselection.png)
     
@@ -229,7 +230,7 @@ highlight syntax incorrectly. Pressing `F5` triggers a full redraw.
 ### Code Folding
 
 Some lexers support "code folding", the act of temporarily hiding blocks of code
-in order to make viewing easier. Arrows in the margin to the left of the code
+in order to make viewing easier. Markers in the margin to the left of the code
 denote fold points. Clicking on one toggles the folding for that block of code.
 Pressing `Ctrl+*` (`⌘*` on Mac OSX | `M-*` in curses) also toggles the fold
 point on the current line.
diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua
index c70983a1..6c9f7a03 100644
--- a/modules/textadept/bookmarks.lua
+++ b/modules/textadept/bookmarks.lua
@@ -49,7 +49,7 @@ function M.goto_mark(next)
     local marks, line = {}, buffer:marker_next(0, 2^M.MARK_BOOKMARK)
     if line == -1 then return end
     repeat
-      local text = buffer:get_line(line):sub(1, -2) -- chop \n
+      local text = buffer:get_line(line):match('^[^\r\n]*')
       marks[#marks + 1] = tostring(line + 1)..': '..text
       line = buffer:marker_next(line + 1, 2^M.MARK_BOOKMARK)
     until line < 0
diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua
index 103ea54b..dd1b6bc2 100644
--- a/modules/textadept/command_entry.lua
+++ b/modules/textadept/command_entry.lua
@@ -92,8 +92,8 @@ local env = setmetatable({}, {
 
 ---
 -- Executes string *code* as Lua code.
--- Code is subject to an "abbreviated" environment where the `buffer`, `view`,
--- and `ui` tables are also considered as globals.
+-- Code is subject to an "abbreviated" environment where the contents of the
+-- `buffer`, `view`, and `ui` tables are also considered as globals.
 -- Prints the results of '=' expressions like in the Lua prompt.
 -- @param code The Lua code to execute.
 -- @name execute_lua
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index 7d10ab46..c7984481 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -119,7 +119,7 @@ events.connect(events.ARG_NONE, function()
 end)
 
 ---
--- Saves a Textadept session to file *filename* or a user-selected file.
+-- Saves a Textadept session to file *filename* or user-selected file.
 -- Saves split views, opened buffers, cursor information, and recent files.
 -- @param filename Optional absolute path to the session file to save. If `nil`,
 --   the user is prompted for one.
diff --git a/properties.lua b/properties.lua
index 1798f59d..77e60566 100644
--- a/properties.lua
+++ b/properties.lua
@@ -36,7 +36,7 @@ buffer:set_y_caret_policy(buffer.CARET_SLOP + buffer.CARET_STRICT +
 -- Caret and Selection Styles.
 --buffer.sel_eol_filled = true
 buffer.caret_line_visible = not CURSES
-buffer.caret_line_visible_always = true
+--buffer.caret_line_visible_always = true
 --buffer.caret_period = 0
 --buffer.caret_style = buffer.CARETSTYLE_BLOCK
 --buffer.caret_width =