6 files changed, 180 insertions, 89 deletions
diff --git a/modules/textadept/bookmarks.lua b/modules/textadept/bookmarks.lua
index 3fdca987..a94c56db 100644
--- a/modules/textadept/bookmarks.lua
+++ b/modules/textadept/bookmarks.lua
@@ -5,15 +5,22 @@ local locale = _G.locale
 
 ---
 -- Bookmarks for the textadept module.
--- There are several option variables used:
---   MARK_BOOKMARK: The integer mark used to identify a bookmarked line.
---   MARK_BOOKMARK_COLOR: The Scintilla color used for a bookmarked line.
 module('_m.textadept.bookmarks', package.seeall)
 
--- options
-local MARK_BOOKMARK = 1
-local MARK_BOOKMARK_COLOR = 0xC08040
--- end options
+-- Markdown:
+-- ## Settings
+--
+-- * `MARK_BOOKMARK`: The unique integer mark used to identify a bookmarked
+--    line.
+-- * `MARK_BOOKMARK_COLOR`: The [Scintilla color][scintilla_color] used for a
+--    bookmarked line.
+--
+-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour
+
+-- settings
+MARK_BOOKMARK = 1
+MARK_BOOKMARK_COLOR = 0xC08040
+-- end settings
 
 ---
 -- Adds a bookmark to the current line.
diff --git a/modules/textadept/editing.lua b/modules/textadept/editing.lua
index d1d2c4a2..97ac9baa 100644
--- a/modules/textadept/editing.lua
+++ b/modules/textadept/editing.lua
@@ -7,6 +7,25 @@ local locale = _G.locale
 -- Editing commands for the textadept module.
 module('_m.textadept.editing', package.seeall)
 
+-- Markdown:
+-- ## Settings
+--
+-- * `AUTOPAIR`: Flag indicating whether or not when an opening `(`, `[`, `[`,
+--   `"`, or `'` is typed, its closing complement character is automatically
+--   inserted.
+-- * `HIGHLIGHT_BRACES`: Flag indicating whether or not when the caret is over a
+--   brace character (any of the following: `()[]{}<>`), its matching complement
+--   brace is highlighted.
+-- * `AUTOINDENT`: Flag indicating whether or not when the enter key is pressed,
+--   the inserted line has is indented to match the level of indentation of the
+--   previous line.
+
+-- settings
+AUTOPAIR = true
+HIGHLIGHT_BRACES = true
+AUTOINDENT = true
+-- end settings
+
 -- The kill-ring.
 -- @field maxn The maximum size of the kill-ring.
 local kill_ring = { pos = 1, maxn = 10 }
@@ -53,11 +72,14 @@ local comment_strings = {
   ruby = '#~',
 }
 
+if AUTOPAIR then
 textadept.events.add_handler('char_added',
   function(c) -- matches characters specified in char_matches
     if char_matches[c] then buffer:insert_text(-1, char_matches[c]) end
   end)
+end
 
+if HIGHLIGHT_BRACES then
 textadept.events.add_handler('update_ui',
   function() -- highlights matching braces
     local buffer = buffer
@@ -74,7 +96,9 @@ textadept.events.add_handler('update_ui',
       buffer:brace_bad_light(-1)
     end
   end)
+end
 
+if AUTOINDENT then
 textadept.events.add_handler('char_added',
   function(char) -- auto-indent on return
     if char ~= 10 then return end
@@ -101,6 +125,7 @@ textadept.events.add_handler('char_added',
       buffer:set_sel(anchor, caret)
     end
   end)
+end
 
 -- local functions
 local insert_into_kill_ring, scroll_kill_ring
diff --git a/modules/textadept/lsnippets.lua b/modules/textadept/lsnippets.lua
index 3d4c73fa..5eeb14e1 100644
--- a/modules/textadept/lsnippets.lua
+++ b/modules/textadept/lsnippets.lua
@@ -5,80 +5,130 @@ local locale = _G.locale
 
 ---
 -- Provides Lua-centric snippets for Textadept.
--- Snippets are basically pieces of text inserted into a document, but can
--- execute code, contain placeholders a user can enter in dynamic text for, and
--- make transformations on that text. This is much more powerful than standard
--- text templating.
--- There are several option variables used:
---   MARK_SNIPPET: The integer mark used to identify the line that marks the
---     end of a snippet.
---   MARK_SNIPPET_COLOR: The Scintilla color used for the line
---     that marks the end of the snippet.
---
 module('_m.textadept.lsnippets', package.seeall)
 
--- Usage:
--- Snippets are defined in the global table 'snippets'. Keys in that table are
--- snippet trigger words, and values are the snippet's text to insert. The
--- exceptions are language names and style names. Language names have table
--- values of either snippets or style keys with table values of snippets.
--- See /lexers/lexer.lua for some default style names. Each lexer's 'add_style'
--- function adds additional styles, the string argument being the style's name.
--- For example:
---   snippets = {
---     file = '%(buffer.filename)',
---     lua = {
---       f = 'function %1(name)(%2(args))\n  %0\nend',
---       string = { [string-specific snippets here] }
+-- Markdown:
+-- ## Settings
+--
+-- * `MARK_SNIPPET`: The unique integer mark used to identify the line that
+--    marks the end of a snippet.
+-- * `MARK_SNIPPET_COLOR`: The [Scintilla color][scintilla_color] used for the
+--   line that marks the end of the snippet.
+--
+-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour
+--
+-- ## Overview
+--
+-- Snippets are basically pieces of text inserted into a document, but can
+-- execute code, contain placeholders you can enter dynamic text for, and
+-- perform transformations on that text. This is much more powerful than
+-- standard text templating.
+--
+-- Snippets are defined in the global table `snippets`. Each key-value pair in
+-- `snippets` consist of either:
+--
+-- * A string snippet trigger word and its expanded text.
+-- * A string language name and its associated `snippets`-like table.
+-- * A string style name and its associated `snippets`-like table.
+--
+-- Language names are the names of the lexer files in `lexers/` such as `cpp`
+-- and `lua`. Style names are different lexer styles, most of which are in
+-- `lexers/lexer.lua`; examples are `whitespace`, `comment`, and `string`.
+--
+-- ## Snippet Precedence
+--
+-- When searching for a snippet to expand in the `snippets` table, snippets in
+-- the current style have priority, followed by the ones in the current lexer,
+-- and finally the ones in the global table.
+--
+-- ## Snippet Syntax
+--
+-- A snippet to insert may contain any of the following:
+--
+-- #### Plain Text
+--
+-- Any plain text characters may be used with the exception of `%` and &#96;.
+-- These are special characters and must be "escaped" by prefixing one with a
+-- `%`. As an example, `%%` inserts a single `%` in the snippet.
+--
+-- #### Lua and Shell Code
+--
+--     %(lua_code)
+--     `shell_code`
+--
+-- The code is executed the moment the snippet is inserted.
+--
+-- For Lua code, the global Lua state is available as well as a `selected_text`
+-- variable (containing the current selection in the buffer) for convenience.
+-- Only the return value of the code execution is inserted, not standard out.
+-- Therefore any `print()` statements are meaningless.
+--
+-- Shell code is run via Lua's [`io.popen()`][io_popen].
+--
+-- [io_popen]: http://www.lua.org/manual/5.1/manual.html#pdf-io.popen
+--
+-- #### Tab Stops and Mirrors
+--
+--     %num
+--
+-- These are visited in numeric order (1, 2, 3, etc.) with %0 being the final
+-- position of the caret, or the end of the snippet if %0 is not specified. If
+-- there is a placeholder (described below) with the specified `num`, its text
+-- is mirrored here.
+--
+-- #### Placeholders
+--
+--     %num(text)
+--
+-- These are also visited in numeric order, but have precedence over tab stops,
+-- and insert the specified `text` at the current position upon entry. `text`
+-- can contain Lua code executed at run-time:
+--
+--     %num(#(lua_code))
+--
+-- The global Lua state is available as well as a `selected_text` variable
+-- (containing the current selection in the buffer) for convenience.
+--
+-- `#`'s will have to be escaped with `%` for plain text. Any mis-matched `)`'s
+-- must also be escaped, but balanced `()`'s need not be.
+--
+-- #### Transformations
+--
+--     %num(pattern|replacement)
+--
+-- These act like mirrors, but transform the text that would be inserted using
+-- a given [Lua pattern][lua_pattern] and replacement. Like in placeholders,
+-- `replacement` can contain Lua code executed at run-time as well as the
+-- standard Lua capture sequences: `%n` where 1 <= `n` <= 9.
+--
+-- [lua_pattern]: http://www.lua.org/manual/5.1/manual.html#5.4.1
+--
+-- Any `|`'s after the first one do not need to be escaped.
+--
+-- ## Example
+--
+--     snippets = {
+--       file = '%(buffer.filename)',
+--       lua = {
+--         f = 'function %1(name)(%2(args))\n  %0\nend',
+--         string = { [string-specific snippets here] }
+--       }
 --     }
---   }
--- Style and lexer insensitive snippets should be placed in the lexer and
--- snippets tables respectively.
---
--- When searching for a snippet to expand in the snippets table, snippets in the
--- current style have priority, then the ones in the current lexer, and finally
--- the ones in the global table.
---
--- As mentioned, snippets are key-value pairs, the key being the trigger word
--- and the value being the snippet text: ['trigger'] = 'text'.
--- Snippet text however can contain more than just text.
---
--- Insert-time Lua and shell code: %(lua_code), `shell_code`
---   The code is executed the moment the snippet is inserted. For Lua code, the
---   result of the code execution is inserted, so print statements are useless.
---   All global variables and a 'selected_text' variable are available.
---
--- Tab stops/Mirrors: %num
---   These are visited in numeric order with %0 being the final position of the
---   caret, the end of the snippet if not specified. If there is a placeholder
---   (described below) with the specified num, its text is mirrored here.
---
--- Placeholders: %num(text)
---   These are also visited in numeric order, having precedence over tab stops,
---   and inserting the specified text. If no placeholder is available, the tab
---   stop is visited instead. The specified text can contain Lua code executed
---   at run-time: #(lua_code).
---
--- Transformations: %num(pattern|replacement)
---   These act like mirrors, but transform the text that would be inserted using
---   a given Lua pattern and replacement. The replacement can contain Lua code
---   executed at run-time: #(lua_code), as well as the standard Lua capture
---   sequences: %n where 1 <= n <= 9.
---   See the Lua documentation for using patterns and replacements.
---
--- To escape any of the special characters '%', '`', ')', '|', or '#', prepend
--- the standard Lua escape character '%'. Note:
---   * Only '`' needs to be escaped in shell code.
---   * '|'s after the first in transformations do not need to be escaped.
---   * Only unmatched ')'s need to be escaped. Nested ()s are ignored.
+--
+-- The first snippet is global and runs the Lua code to determine the current
+-- buffer's filename and inserts it. The other snippets apply only in the `lua`
+-- lexer. Any snippets in the `string` table are available only when the current
+-- style is `string` in the `lua` lexer.
 
-local MARK_SNIPPET = 4
-local MARK_SNIPPET_COLOR = 0x4D9999
+-- settings
+MARK_SNIPPET = 4
+MARK_SNIPPET_COLOR = 0x4D9999
+-- end settings
 
 ---
 -- Global container that holds all snippet definitions.
 -- @class table
--- @name snippets
+-- @name _G.snippets
 _G.snippets = {}
 
 _G.snippets.file = "%(buffer.filename)"
diff --git a/modules/textadept/mlines.lua b/modules/textadept/mlines.lua
index daddf4b5..6d4d866b 100644
--- a/modules/textadept/mlines.lua
+++ b/modules/textadept/mlines.lua
@@ -5,21 +5,25 @@ local locale = _G.locale
 
 ---
 -- Multiple line editing for the textadept module.
--- There are several option variables used:
---   MARK_MLINE: The integer mark used to identify an MLine marked line.
---   MARK_MLINE_COLOR: The Scintilla color used for an MLine marked line.
 module('_m.textadept.mlines', package.seeall)
 
--- options
-local MARK_MLINE = 2
-local MARK_MLINE_COLOR = 0x4D994D
--- end options
+-- Markdown:
+-- ## Settings
+--
+-- * `MARK_MLINE`: The unique integer mark used to identify an MLine marked
+--   line.
+-- * `MARK_MLINE_COLOR`: The [Scintilla color][scintilla_color] used for an
+--   MLine marked line.
+--
+-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour
 
----
--- [Local table] Contains all MLine marked lines with the column index to edit
--- with respect to for each specific line.
--- @class table
--- @name mlines
+-- settings
+MARK_MLINE = 2
+MARK_MLINE_COLOR = 0x4D994D
+-- end settings
+
+-- Contains all MLine marked lines with the column index to edit with respect to
+-- for each specific line.
 local mlines = {}
 
 local mlines_most_recent
diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua
index d6fa0a24..fcdb6a43 100644
--- a/modules/textadept/run.lua
+++ b/modules/textadept/run.lua
@@ -20,7 +20,7 @@ function execute(command)
   local filedir, filename = filepath:match('^(.+[/\\])([^/\\]+)$')
   local filename_noext = filename:match('^(.+)%.')
   command = command:gsub('%%%b()', {
-    ['%(filepath)'] = filepath, _CHARSET, 'UTF-8',
+    ['%(filepath)'] = filepath,
     ['%(filedir)'] = filedir,
     ['%(filename)'] = filename,
     ['%(filename_noext)'] = filename_noext,
diff --git a/modules/textadept/session.lua b/modules/textadept/session.lua
index a464da68..ba98a728 100644
--- a/modules/textadept/session.lua
+++ b/modules/textadept/session.lua
@@ -5,11 +5,16 @@ local locale = _G.locale
 
 ---
 -- Session support for the textadept module.
--- There are several option variables used:
---   DEFAULT_SESSION: The path to the default session file.
 module('_m.textadept.session', package.seeall)
 
-local DEFAULT_SESSION = _USERHOME..'/session'
+-- Markdown:
+-- ## Settings
+--
+-- * `DEFAULT_SESSION`: The path to the default session file.
+
+-- settings
+DEFAULT_SESSION = _USERHOME..'/session'
+-- end settings
 
 ---
 -- Loads a Textadept session file.