Documentation overhaul.

3 files changed, 175 insertions, 74 deletions

diff --git a/core/ext/key_commands.lua b/core/ext/key_commands.lua
index 9a98612c..26c1d929 100644
--- a/core/ext/key_commands.lua
+++ b/core/ext/key_commands.lua
@@ -5,10 +5,97 @@ local locale = _G.locale
 
 ---
 -- Defines the key commands used by the Textadept key command manager.
--- For non-ascii keys, see textadept.keys for string aliases.
 -- This set of key commands is pretty standard among other text editors.
 module('textadept.key_commands', package.seeall)
 
+-- Markdown:
+-- ## Overview
+--
+-- Key commands are defined in the global table `keys`. Each key-value pair in
+-- `keys` consists of either:
+--
+-- * A string representing a key command and an associated action table.
+-- * A string language name and its associated `keys`-like table.
+-- * A string style name and its associated `keys`-like table.
+-- * A string representing a key command and its associated `keys`-like table.
+--   (This is a keychain sequence.)
+--
+-- A key command string is built from a combination of the `CTRL`, `SHIFT`,
+-- `ALT`, and `ADD` constants as well as the pressed key itself. The value of
+-- `ADD` is inserted between each of `CTRL`, `SHIFT`, `ALT`, and the key.
+-- For example:
+--
+--     -- keys.lua:
+--     CTRL = 'Ctrl'
+--     SHIFT = 'Shift'
+--     ALT = 'Alt'
+--     ADD = '+'
+--     -- pressing control, shift, alt and 'a' yields: 'Ctrl+Shift+Alt+a'
+--
+-- For key values less than 255, Lua's [`string.char()`][string_char] is used to
+-- determine the key's string representation. Otherwise, the `KEYSYMS` lookup
+-- table in [`textadept.keys`][textadept_keys] is used.
+--
+-- [string_char]: http://www.lua.org/manual/5.1/manual.html#pdf-string.char
+-- [textadept_keys]: ../modules/textadept.keys.html
+--
+-- An action table is a table consisting of either:
+--
+-- * A Lua function followed by a list of arguments to pass to that function.
+-- * A string representing a [buffer][buffer] or [view][view] function followed
+--   by its respective `'buffer'` or `'view'` string and then any arguments to
+--   pass to the resulting function.
+--
+--       `buffer.`_`function`_ by itself cannot be used because at the time of
+--       evaluation, `buffer.`_`function`_ would apply only to the current
+--       buffer, not for all buffers. By using this string reference system, the
+--       correct `buffer.`_`function`_ will be evaluated every time. The same
+--       applies to `view`.
+--
+-- [buffer]: ../modules/buffer.html
+-- [view]: ../modules/view.html
+--
+-- 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`.
+--
+-- Key commands can be chained like in Emacs using keychain sequences. By
+-- default, the `Esc` key cancels the current keychain, but it can be redefined
+-- by setting the `keys.clear_sequence` field. Naturally, the clear sequence
+-- cannot be chained.
+--
+-- ## Key Command Precedence
+--
+-- When searching for a key command to execute in the `keys` table, key commands
+-- in the current style have priority, followed by the  ones in the current lexer,
+-- and finally the ones in the global table.
+--
+-- ## Example
+--
+--     keys = {
+--       ['ctrl+f'] = { 'char_right', 'buffer' },
+--       ['ctrl+b'] = { 'char_left',  'buffer' },
+--       lua = {
+--         ['ctrl+c'] = { 'add_text', 'buffer', '-- ' },
+--         whitespace = {
+--           ['ctrl+f'] = { function() print('whitespace') end }
+--         }
+--       }
+--     }
+--
+-- The first two key commands are global and call `buffer:char_right()` and
+-- `buffer:char_left()` respectively. The last two commands apply only in the
+-- Lua lexer with the very last one only being available in Lua's `whitespace`
+-- style. If `ctrl+f` is pressed when the current style is `whitespace` in the
+-- `lua` lexer, the global key command with the same shortcut is overriden and
+-- `whitespace` is printed to standard out.
+--
+-- ## Problems
+--
+-- All Lua functions must be defined BEFORE they are reference in key commands.
+-- Therefore, any module containing key commands should be loaded after all
+-- other modules, whose functions are being referenced, have been loaded.
+
 -- Windows and Linux key commands are listed in the first block.
 -- Mac OSX key commands are listed in the second block.
 
@@ -16,6 +103,12 @@ local keys = _G.keys
 local b, v = 'buffer', 'view'
 local t = textadept
 
+-- CTRL = 'c'
+-- SHIFT = 's'
+-- ALT = 'a'
+-- ADD = ''
+-- Control, Shift, Alt, and 'a' = 'csaa'
+
 if not MAC then
   -- Windows and Linux key commands.
 
@@ -410,3 +503,8 @@ else
   keys.cd   = { 'clear',             b }
   keys.cad  = { 'del_word_right',    b }
 end
+
+---
+-- This module has no functions.
+function no_functions() end
+no_functions = nil -- undefine
diff --git a/core/ext/keys.lua b/core/ext/keys.lua
index 5a27f36a..d89a08a0 100644
--- a/core/ext/keys.lua
+++ b/core/ext/keys.lua
@@ -7,76 +7,27 @@ local locale = _G.locale
 -- Manages key commands in Textadept.
 -- Default key commands should be defined in a separate file and loaded after
 -- all modules.
--- There are several option variables used:
---   SCOPES_ENABLED: Flag indicating whether scopes/styles can be used for key
---     commands.
---   CTRL: The string representing the Control key.
---   SHIFT: The string representing the Shift key.
---   ALT: The string representing the Alt key (the Apple key on Mac OSX).
---   ADD: The string representing used to join together a sequence of Control,
---     Shift, or Alt modifier keys.
---
 module('textadept.keys', package.seeall)
 
--- Usage:
--- Keys are defined in the global table 'keys'. Keys in that table are key
--- sequences, and values are tables of Lua functions and arguments to execute.
--- The exceptions are language names, style names, and keychains (discussed
--- later). Language names have table values of either key commands or style keys
--- with table values of key commands. 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:
---   keys = {
---     ['ctrl+f'] = { 'char_right', 'buffer' },
---     ['ctrl+b'] = { 'char_left',  'buffer' },
---     lua = {
---       ['ctrl+c'] = { 'add_text', 'buffer', '-- ' },
---       whitespace = { function() print('whitespace') end }
---     }
---   }
--- Style and lexer insensitive key commands should be placed in the lexer and
--- keys tables respectively.
---
--- When searching for a key command to execute in the keys table, key commands
--- in the current style have priority, then ones in the current lexer, and
--- finally the ones in the global table.
---
--- As mentioned, key commands are key-value pairs, the key being the key
--- sequence compiled from the CTRL, SHIFT, ALT, and ADD options (discussed
--- below) as well as the key pressed and the value being a table of a function
--- to call and its arguments. For the table, the first item can be either a Lua
--- function or a string (representing a function name). If it is a function, all
--- table items after it are used as arguments. If the first item is a string,
--- the next string is checked to be either 'buffer' or 'view' and the current
--- buffer or view is used as the table with the function name as a field,
--- indexing a function. The current buffer or view is then used as the first
--- argument to that function, with all items after the second following as
--- additional ones. Basically in Lua: {buffer|view}:{first_item}(...)
---
--- As noted previously, key sequences can be compiled differently via the CTRL,
--- SHIFT, ALT, and ADD options. The first three indicate the text for each
--- respective modifier key and ADD is the text inserted between modifiers.
---
--- Key commands can be chained like in Emacs. Instead of a key sequence having
--- a table of a function and its arguments, it has a table of key commands (much
--- like lexer or style specific key commands). My default, the 'escape' key
--- cancels the current keychain, but it can be redefined by setting the
--- 'clear_sequence' key in the global keys table. It cannot be chained however.
+-- Markdown:
+-- ## Settings
 --
--- Keys that have values higher than 255 cannot be represented by a string, but
--- can have a string representation defined in the KEYSYMS table.
+-- * `SCOPES_ENABLED`: Flag indicating whether scopes/styles can be used for key
+--   commands.
+-- * `CTRL`: The string representing the Control key.
+-- * `SHIFT`: The string representing the Shift key.
+-- * `ALT`: The string representing the Alt key (the Apple key on Mac OSX).
+-- * `ADD`: The string representing used to join together a sequence of Control,
+--   Shift, or Alt modifier keys.
 --
--- Keep in mind that all Lua functions used in key commands must be defined
--- BEFORE the key command references it. Therefore the module containing key
--- commands should be loaded LAST, after all other modules have been loaded.
 
--- options
+-- settings
 local SCOPES_ENABLED = true
 local ADD = ''
 local CTRL = 'c'..ADD
 local SHIFT = 's'..ADD
 local ALT = 'a'..ADD
--- end options
+-- end settings
 
 ---
 -- Global container that holds all key commands.
diff --git a/core/ext/mime_types.lua b/core/ext/mime_types.lua
index e6412884..e16ecf6b 100644
--- a/core/ext/mime_types.lua
+++ b/core/ext/mime_types.lua
@@ -3,9 +3,63 @@
 local textadept = _G.textadept
 local locale = _G.locale
 
---- Handles file-specific settings (based on file extension).
+---
+-- Handles file-specific settings.
 module('textadept.mime_types', package.seeall)
 
+-- Markdown:
+-- ## Overview
+--
+-- Files can be recognized and associated with programming language lexers in
+-- three ways:
+--
+-- * By file extension.
+-- * By keywords in the file's shebang (`#!/path/to/exe`) line.
+-- * By a pattern that matches the file's first line.
+--
+-- If a lexer is not associated with a file you open, first make sure the lexer
+-- exists in `lexers/`. If it does not, you will need to write one. Consult the
+-- [lexer][lexer] module for a tutorial.
+--
+-- [lexer]: ../modules/lexer.html
+--
+-- ## Configuration File
+--
+-- `core/ext/mime_types.conf` is the configuration file for mime-type detection.
+--
+-- #### Detection by File Extension
+--
+--     file_ext lexer
+--
+-- Note: `file_ext` should not start with a `.` (period).
+--
+-- #### Detection by Shebang Keywords
+--
+--     #shebang_word lexer
+--
+-- Examples of `shebang_word`'s are `lua`, `ruby`, `python`.
+--
+-- #### Detection by Pattern
+--
+--     /pattern lexer
+--
+-- Only the last space, the one separating the pattern from the lexer, is
+-- significant. No spaces in the pattern need to be escaped.
+--
+-- ## Extras
+--
+-- This module adds an extra function to `buffer`:
+--
+-- * **buffer:set\_lexer** (language)<br />
+--   Replacement for [`buffer:set_lexer_language()`][buffer_set_lexer_language].<br />
+--   Sets a buffer._lexer field so it can be restored without querying the
+--   mime-types tables. Also if the user manually sets the lexer, it should be
+--   restored.<br />
+--   Loads the language-specific module if it exists.
+--       - lang: The string language to set.
+--
+-- [buffer_set_lexer_language]: buffer.html#buffer:set_lexer_language
+
 ---
 -- File extensions with their associated lexers.
 -- @class table
@@ -43,17 +97,26 @@ if f then
   f:close()
 end
 
----
+--
 -- Replacement for buffer:set_lexer_language().
 -- Sets a buffer._lexer field so it can be restored without querying the
 -- mime-types tables. Also if the user manually sets the lexer, it should be
 -- restored.
+-- Loads the language-specific module if it exists.
 -- @param buffer The buffer to set the lexer language of.
 -- @param lang The string language to set.
 -- @usage buffer:set_lexer('language_name')
 local function set_lexer(buffer, lang)
   buffer._lexer = lang
   buffer:set_lexer_language(lang)
+  if buffer.filename then
+    local ret, err = pcall(require, lang)
+    if ret then
+      _m[lang].set_buffer_properties()
+    elseif not ret and not err:find("^module '"..lang.."' not found:") then
+      error(err)
+    end
+  end
 end
 textadept.events.add_handler('buffer_new',
   function() buffer.set_lexer = set_lexer end)
@@ -83,17 +146,6 @@ local function handle_new()
     end
   end
   buffer:set_lexer(lexer or 'container')
-  if buffer.filename then
-    local lang = extensions[buffer.filename:match('[^/\\.]+$')]
-    if lang then
-      local ret, err = pcall(require, lang)
-      if ret then
-        _m[lang].set_buffer_properties()
-      elseif not ret and not err:find("^module '"..lang.."' not found:") then
-        error(err)
-      end
-    end
-  end
 end
 
 -- Sets the buffer's lexer based on filename, shebang words, or