From 9dc8ce16a1efc6482db6f1d5456d42958e79a06c Mon Sep 17 00:00:00 2001
From: mitchell <70453897+667e-11@users.noreply.github.com>
Date: Wed, 12 Sep 2012 11:24:11 -0400
Subject: Documentation overhaul. Rewrote most of the manual and Lua API to
 complement each other. Key bindings reference moved from Appendix to
 modules/textadept/keys.lua LuaDoc.

---
 core/._M.luadoc | 165 +++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 111 insertions(+), 54 deletions(-)

(limited to 'core/._M.luadoc')

diff --git a/core/._M.luadoc b/core/._M.luadoc
index b73e9000..ea969647 100644
--- a/core/._M.luadoc
+++ b/core/._M.luadoc
@@ -6,92 +6,149 @@
 ---
 -- A table of loaded modules.
 --
--- ## Overview
+-- ## Module Guidelines
 --
--- Note that while language-specific modules can only be used by files of that
--- language, they persist in Textadept's Lua state. Because of this, it is not
--- recommended to set global functions or variables and depend on them, as they
--- may be inadvertantly overwritten. Keep them inside the module.
+-- At the very least, modules consist of a single directory with an `init.lua`
+-- script. However, the script can load additional Lua files present in the
+-- directory. (For an example, see `modules/textadept/init.lua`.)
 --
--- ## Structure
+-- Once modules are loaded, regardless of whether they are generic or
+-- language-specific, they persist in Textadept's Lua State; they are never
+-- unloaded. Therefore, modules should not set global functions or variables in
+-- order to avoid polluting the global environment. All functions and variables
+-- should be contained within the module.
 --
--- Each module should have an `init.lua` that `require`s all submodules it
--- needs. For an example, see `modules/textadept/init.lua`.
+-- ### Language-Specific
 --
--- ## Language-Specific Modules
+-- To fully take advantage of Textadept's features, language-specific modules
+-- should have at a minimum: a block comment string, run and/or compile
+-- commands, a buffer property setter function, and if possible, an Adeptsense.
+-- Optional features are extra snippets and commands and a context menu.
 --
--- The following is a list of recommended features for Language-Specific
--- modules. They are all entirely optional.
+-- #### Block Comment
 --
--- ### Snippets
+-- The `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in ncurses) key binding toggles code
+-- comments. In order for this to work for your language, the
+-- [`_M.textadept.editing.comment_string`][] table must have a key with the
+-- language's lexer name assigned to a comment prefix string. For Lua, it would
+-- look like
 --
--- [Snippets][] for common code constructs.
+--     _M.textadept.editing.comment_string.lua = '--'
 --
--- [Snippets]: _M.textadept.snippets.html
+-- [`_M.textadept.editing.comment_string`]: _M.textadept.editing.html#comment_string
 --
--- ### Commands
+-- #### Compile and Run
 --
--- #### Run
+-- The `Ctrl+Shift+R` and `Ctrl+R` (`⌘⇧R` and `⌘R` on Mac OSX | `M-^R` and `^R`
+-- in ncurses) key bindings compile and run code, respectively. In order for
+-- these to work for your language, the [`_M.textadept.run.compile_command`][]
+-- and [`_M.textadept.run.run_command`][] tables must have keys with the
+-- language's lexer name assigned to compile and run shell commands,
+-- respectively. Commands may contain [macros][]. For Lua, it would look like
 --
--- If the code can be run by an interpreter or other executable, create a [run
--- command][] for it as well as an [error format][] for the ability to jump to
--- the position in a file where the error occured.
+--     _M.textadept.run.compile_command.lua = 'luac %(filename)'
+--     _M.textadept.run.run_command = 'lua %(filename)'
 --
--- For example:
+-- The module should also define error details in
+-- [`_M.textadept.run.error_detail`][] so double-clicking on compile or runtime
+-- errors will jump to the error's location. The format for Lua errors looks
+-- like
 --
---     _M.textadept.run.run_command.lua = 'lua %(filename)'
+--     _M.textadept.run.error_detail.lua = {
+--       pattern = '^lua: (.-):(%d+): (.+)$',
+--       filename = 1, line = 2, message = 3
+--     }
 --
--- [run command]: _M.textadept.run.html#run_command
--- [error format]: _M.textadept.run.html#error_detail
+-- [`_M.textadept.run.compile_command`]: _M.textadept.run.html#compile_command
+-- [`_M.textadept.run.run_command`]: _M.textadept.run.html#run_command
+-- [macros]: _M.textadept.run.html#execute
+-- [`_M.textadept.run.error_detail`]: _M.textadept.run.html#error_detail
 --
--- #### Compile
+-- #### Buffer Properties
 --
--- If the code can be compiled by an executable, create a [compile command][]
--- for it.
+-- By default, Textadept uses 2 spaces as indentation. If your language has
+-- different indentation guidelines, change them in a `set_buffer_properties()`
+-- function. Using tabs of width 8 would look like
 --
--- For example:
+--     function M.set_buffer_properties()
+--       buffer.tab_width = 8
+--       buffer.use_tabs = true
+--     end
 --
---     _M.textadept.run.compile_command.lua = 'luac %(filename)'
+-- This function is called automatically to set the properties for the
+-- language's source files.
 --
--- [compile command]: _M.textadept.run.html#compile_command
+-- #### Adeptsense
 --
--- #### Block Comment
+-- The `Ctrl+Space` and `Ctrl+H` (`⌥⎋` and `^H` on Mac OSX | `^Space` and `M-H`
+-- or `M-S-H` in ncurses) key bindings autocomplete symbols and show API
+-- documentation, respectively, when editing code. In order for these to work
+-- for your language, you must create an [Adeptsense][].
 --
--- Create a [comment prefix][] for it so code can be easily commented and
--- uncommented.
+-- [Adeptsense]: _M.textadept.adeptsense.html
 --
--- [comment prefix]: _M.textadept.editing.html#comment_string
+-- #### Snippets
 --
--- For example:
+-- [Snippets][] for common language constructs can be useful. Some snippets for
+-- common Lua control structures look like
 --
---     _M.textadept.editing.comment_string.lua = '--'
---
--- [comment prefix]: _M.textadept.editing.html#comment_string
+--     snippets.lua = {
+--       f = "function %1(name)(%2(args))\n\t%0\nend",
+--       ['for'] = "for i = %1(1), %2(10)%3(, -1) do\n\t%0\nend",
+--       fori = "for %1(i), %2(val) in ipairs(%3(table)) do\n\t%0\nend",
+--       forp = "for %1(k), %2(v) in pairs(%3(table)) do\n\t%0\nend",
+--     }
 --
--- ### Buffer Properties
+-- [Snippets]: _M.textadept.snippets.html
 --
--- Add a `set_buffer_properties` function with default buffer properties for
--- code like tab and indentation settings.
+-- #### Commands
 --
--- For example:
+-- Additional editing features for the language can be useful. For example, the
+-- [Lua][] module has a feature to autocomplete the `end` keyword in a control
+-- structure and the [C/C++][] module has a feature to add a `;` to the end of
+-- the current line and insert a new line. Both are bound to the `Shift+Enter`
+-- (`⇧↩` on Mac OSX | `S-Enter` in ncurses) key for easy access.
 --
---     function set_buffer_properties()
---       local buffer = buffer
---       buffer.use_tabs = false
---       buffer.tab_width = 2
---       buffer.indent = 2
+--     function M.try_to_autocomplete_end()
+--       ...
 --     end
 --
--- ### Context Menu
+--     keys.lua = {
+--       ['s\n'] = M.try_to_autocomplete_end
+--     }
 --
--- Language-specific context menus, accessible by right-clicking inside the
--- view, can be defined as:
+-- ---
 --
---     context_menu = {
---       { 'label1', action1 },
---       { 'label2', action2 },
---       ...
+--     keys.cpp = {
+--       ['s\n'] = function()
+--         buffer:line_end()
+--         buffer:add_text(';')
+--         buffer:new_line()
+--       end
+--     }
+--
+-- [Lua]: _M.lua.html
+-- [C/C++]: _M.cpp.html
+--
+-- #### Context Menu
+--
+-- Language-specific [context menus][], accessible by right-clicking inside the
+-- view, can be useful for accessing module features without using key bindings.
+-- For Lua this may look like
+--
+--     M.context_menu = {
+--       { _L['_Undo'], buffer.undo },
+--       { _L['_Redo'], buffer.redo },
+--       { '' },
+--       { _L['Cu_t'], buffer.cut },
+--       { _L['_Copy'], buffer.copy },
+--       { _L['_Paste'], buffer.paste },
+--       { _L['_Delete'], buffer.clear },
+--       { '' },
+--       { _L['Select _All'], buffer.select_all },
+--       { '' },
+--       { 'Autocomplete "end"', M.try_to_autocomplete_end }
 --     }
 --
--- See `modules/textadept/menu.lua` for examples on how to define menus.
+-- [context menus]: _M.textadept.menu.html#set_contextmenu
 module('_M')]]
-- 
cgit v1.2.3