From 96c85498c019e381d0aeed2e33e626563563ea8c Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Wed, 7 Mar 2012 09:28:43 -0500 Subject: Documentation overhaul with Discount (Markdown implementation). The standard LuaDoc template is no longer used. Instead, the new `scripts/markdowndoc.lua` has the template for LuaDoc and `scripts/update_doc` has the template for the Manual. Also added README, CHANGELOG, and THANKS files. --- doc/manual/14_Appendix.md | 421 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 410 insertions(+), 11 deletions(-) (limited to 'doc/manual/14_Appendix.md') diff --git a/doc/manual/14_Appendix.md b/doc/manual/14_Appendix.md index cdff8db7..426ab35f 100644 --- a/doc/manual/14_Appendix.md +++ b/doc/manual/14_Appendix.md @@ -16,7 +16,6 @@ Ctrl+Shift+W|⌘⇧W |Close all files None |None|Load session... None |None|Load session... Alt+Q |⌘Q |Quit - **Edit** ||| Ctrl+Z
Alt+Backspace|⌘Z |Undo Ctrl+Y
Ctrl+Shift+Z |⌘⇧Z |Redo @@ -58,7 +57,6 @@ Ctrl++ |⌘+ |Grow selection by 1 on either side Ctrl+\_ |⌘\_ |Shrink selection by 1 on either side Ctrl+Shift+Up |^⇧⇡ |Move selected lines up Ctrl+Shift+Down |^⇧⇣ |Move selected lines down - **Search** ||| Ctrl+F |⌘F |Find Ctrl+G
F3 |⌘G |Find next @@ -70,7 +68,6 @@ Ctrl+Shift+F |⌘⇧F |Find in files Ctrl+Alt+G |^⌘G |Goto next file found Ctrl+Alt+Shift+G |^⌘⇧G|Goto previous file found Ctrl+J |⌘J |Jump to line - **Tools** ||| Ctrl+E |⌘E |Command entry Ctrl+Shift+E |⌘⇧E |Select command @@ -92,7 +89,6 @@ Ctrl+U |⌘U |Snapopen `_USERHOME` None |None |Snapopen `_HOME` Ctrl+Alt+Shift+O|^⌘⇧O |Snapopen current directory Ctrl+I |⌘I |Show style - **Buffer** ||| Ctrl+Tab |^⇥ |Next buffer Ctrl+Shift+Tab |^⇧⇥ |Previous buffer @@ -112,7 +108,6 @@ None |None |`ISO-8859-1` encoding None |None |`UTF-16` encoding Ctrl+Shift+L |⌘⇧L |Select lexer... F5 |F5 |Refresh syntax highlighting - **View** ||| Ctrl+Alt+N |^⌥⇥ |Next view Ctrl+Alt+P |^⌥⇧⇥ |Previous view @@ -132,12 +127,10 @@ Ctrl+= |⌘= |Zoom in Ctrl+- |⌘- |Zoom out Ctrl+0 |⌘0 |Reset zoom Ctrl+Shift+T |⌘⇧T |Select theme... - **Help** ||| F1 |F1 |Open manual Shift+F1|⇧F1 |Open LuaDoc None |None|About - **Movement** ||| Down |⇣
^N |Line down Shift+Down |⇧⇣
^⇧N |Line down extend selection @@ -183,15 +176,12 @@ Tab |⇥ |Insert tab or indent Shift+Tab |⇧⇥ |Dedent None |^K |Cut to line end None |^L |Center line vertically - **Other** ||| Ctrl+Shift+U, xxxx, Enter|None|Input Unicode character U-xxxx. - ## Lua Patterns -The following is taken from the -[Lua 5.2 Reference Manual](http://www.lua.org/manual/5.2/manual.html#6.4.1). +The following is taken from the [Lua 5.2 Reference Manual][]. _Character Class:_ @@ -285,3 +275,412 @@ is captured with number 2, and the part matching "`%s*`" has number 3. As a special case, the empty capture `()` captures the current string position (a number). For instance, if we apply the pattern `"()aa()"` on the string `"flaaap"`, there will be two captures: 3 and 5. + +[Lua 5.2 Reference Manual]: http://www.lua.org/manual/5.2/manual.html#6.4.1 + +## Migration Guides + +### Textadept 4 to 5 + +Lua has been upgraded from [5.1 to 5.2][], so many scripts written for Textadept +4 are not compatible with Textadept 5. Since incompatible scripts may cause +crashes on startup, the following guide will help you migrate your scripts from +Textadept 4 to Textadept 5. While this guide is not exhaustive, it covers the +changes I had to Textadept's internals. + +[5.1 to 5.2]: http://www.lua.org/manual/5.2/manual.html#8 + +#### Module Changes + +##### Syntax Changes + +Although Lua 5.2 only deprecates Lua 5.1's `module` syntax, Textadept 5 removes +it. Therefore, replace + + -- File ~/.textadept/modules/foo.lua + module('_m.foo', package.seeall) + + function bar() + ... + end + + ... + +and + + -- File ~/.textadept/init.lua + require 'textadept' + require 'foo' + +with + + -- File ~/.textadept/modules/foo.lua + local M = {} + + function M.bar() + ... + end + + ... + + return M + +or + + local M = {} + local _ENV = M + if setfenv then setfenv(1, _ENV) end -- LuaJIT support + + function bar() + ... + end + + function baz() + bar() + end + + return M + +and + + -- File ~/.textadept/init.lua + require 'textadept' + _M.foo = require 'foo' + +Please remember that, as stated in the documentation, `require 'textadept'` is a +special case and `_M.textadept = require 'textadept'` is not necessary because +of internal dependencies. All other modules need the +`_M.module = require 'module'` construct. + +Notice that `_M` is the new module table instead of `_m`. More on this +[later](#Global.Module.Table). + +##### Module References + +Replace all instances of `_M` (a reference created by `module()` that holds the +current module table) with `M` (the local module table you created). + +Also, prefix all instances of internal module function calls with `M` if you are +not using `_ENV`. For example, change + + module('foo', package.seeall) + + function bar() + ... + end + + function baz() + bar() + end + +to + + local M = {} + + function M.bar() + ... + end + + function M.baz() + M.bar() + end + + return M + +##### LuaDoc + +If you use LuaDoc for your modules, you can still document them like this: + + local M = {} + + --[[ This comment is for LuaDoc + --- + -- This is the documentation for module foo. + module('foo')]] + + --- + -- Documentation for bar. + -- ... + -- @name bar + function M.bar() + ... + end + + return M + +##### Global Module Table + +Originally, I wanted to use `_M` as the global table that contains modules, but +Lua 5.1's modules used `_M` silently, so I had to settle with `_m`. Now that +modules have been removed, `_M` is available again and is used. Therefore, +replace all instances of `_m` with `_M`. In Textadept, you can easily do a +search and replace with "Match Case" and "Whole Words" checked -- this is what I +did when upgrading Textadept's internals. + +#### Function Changes + +##### `unpack` + +`unpack()` has been renamed to `table.unpack()`. Replace all instances of +`unpack` with `table.unpack`. + +##### `xpcall` + +`xpcall()` accepts error function parameters so you can change code from + + local args = {...} + xpcall(function() return f(unpack(args)) end, error_function) + +to + + xpcall(f, error_function, ...) + +However, this is not required. + +##### `loadstring` + +`loadstring()` has been replaced by `load()` since the latter now recognizes a +string chunk. Replace all instances of `loadstring` with `load`. + +##### `setfenv` + +`setfenv()` has been removed. In some cases, use `load()` with an environment +instead. For example, change + + local f, err = loadstring(command) + if err then error(err) end + setfenv(f, env)() + +to + + local f, err = load(command, nil, 'bt', env) + if err then error(err) end + f() + +(The `'bt'` is necessary for loading both binary and text chunks.) + +If instead you want to set a function's environment, change + + setfenv(f, env) + +to + + debug.setupvalue(f, 1, env) + +##### `getfenv` + +`getfenv()` has been removed. Change + + local env = getfenv(f) + +to + + local debug = require 'debug' + local env = debug.getupvalue(f, 1) + +##### `os.execute` + +`os.execute()`s function parameters have changed. If you are only interested in +the return code, change + + local code = os.execute(cmd) + +to + + local _, _, code = os.execute(cmd) + +##### `localize` + +Localization is done using a global table [`_L`][] instead of calling +`locale.localize()`. Replace all instances of `locale.localize('message')` with +`_L['message']`. This allows messages to be modified via scripts if desirable. + +[`_L`]: ../api/_L.html + +##### `current_word` + +`_M.textadept.editing.current_word()` has been renamed to `select_word()` and +does not take any parameters. There is a `_M.textadept.keys.utils.delete_word()` +function that replaces `current_word('delete')`. You can use it or create a new +function: + + local function delete_word() + _M.textadept.editing.select_word() + buffer:delete_back() + end + +#### Theme Changes + +Any custom themes need to be changed to remove the `module` syntax. Usually this +involves changing + + module('lexer', package.seeall) + + colors = { + ... + } + + style_nothing = style { ... } + style_class = style { fore = colors.light_yellow } + ... + style_identifier = style_nothing + + ... + + style_default = style { + ... + } + style_line_number = { fore = colors.dark_grey, back = colors.black } + ... + +to + + local l, color, style = lexer, lexer.color, lexer.style + + l.colors = { + ... + } + + l.style_nothing = style { ... } + l.style_class = style { fore = l.colors.light_yellow } + ... + l.style_identifier = l.style_nothing + + ... + + l.style_default = style { + ... + } + l.style_line_number = { fore = l.colors.dark_grey, back = l.colors.black } + ... + +Notice the `l.` prefix before most identifiers. + +### Textadept 3 to 4 + +#### Key and Menu Changes + +Textadept 4 allow key shortcuts to appear in menus, but only simple ones, not +keychains. Therefore, Textadept's key commands have changed radically, as has +the menu structure and menu mnemonics. In order for key shortcuts to appear in +menus, `_m.textadept.menu` needs to know which commands are assigned to which +keys. Therefore, the menu module needs to be `require`d *after* +`_m.textadept.keys`. If your `~/.textadept/init.lua` is calling +`require 'textadept'`, you do not have to make any changes. If you are loading +individual modules from `_m.textadept`, ensure `_m.textadept.menu` is loaded +after `_m.textadept.keys`. + +On Mac OSX, key command definition has changed. `m` is now ⌘ (command) and `a` +is now ⌥ (alt/option). `c` remains ^ (control). Previously `a` was ⌘ and ⌥ was +undefined. Please note, however, that not all ⌥ combinations by themselves will +work since that key is typically used to compose locale-dependent characters. + +#### Function Changes + +##### `select_scope` + +`_m.textadept.editing.select_scope()` was renamed to `select_style()`. +Therefore, replace all instances of `_m.textadept.editing.select_scope` with +`_m.textadept.editing.select_style`. + +##### `SAVE_STRIPS_WS` + +`_m.textadept.editing.SAVE_STRIPS_WS` was renamed to `STRIP_WHITESPACE_ON_SAVE`. +Replace all instances of `_m.textadept.editing.SAVE_STRIPS_WS` with +`_m.textadept.editing.STRIP_WHITESPACE_ON_SAVE`. + +### Textadept 2 to 3 + +#### Module Changes + +##### Core Extensions + +There are no more core extention modules (previously in `core/ext/`). They have +been relocated to `modules/textadept/` so putting + + require 'textadept' + +in your `~/.textadept/init.lua` will load all the modules you would expect. +Please see the [preferences][] page for instructions on how to load specific +modules. + +[preferences]: 9_Preferences.html#User.Init + +##### Autoloading + +Key commands in `~/.textadept/key_commands.lua` and snippets in +`~/.textadept/snippets.lua` are no longer auto-loaded. Instead, modify +[`keys`][] and/or [`snippets`][] from within your `~/.textadept/init.lua` or a +file loaded by `~/.textadept/init.lua`. + +[`keys`]: ../api/keys.html +[`snippets`]: ../api/_M.textadept.snippets.html + +#### Function Changes + +Textadept has a brand new Lua [API][]. It is likely that any external scripts, +including themes, need to be rewritten. + +Here is a summary of API changes: + +* `_m.textadept.lsnippets` renamed to [`_m.textadept.snippets`][]. +* `textadept.events` renamed to [`_G.events`][]. + * `events.handle()` renamed to [`events.emit()`][]. + * `events.add_handler()` renamed to [`events.connect()`][]. +* `textadept.constants` renamed to [`_SCINTILLA.constants`][]. +* `textadept.buffer_functions` renamed to [`_SCINTILLA.functions`][]. +* `textadept.buffer_properties` renamed to [`_SCINTILLA.properties`][]. +* `textadept.buffers` renamed to [`_BUFFERS`][]. +* `textadept.views` renamed to [`_VIEWS`][]. +* New [`gui`][] module. + * Renamed `textadept._print()` to [`gui._print()`][]. + * Renamed `textadept.check_focused_buffer()` to `gui.check_focused_buffer()`. + * Renamed `textadept.clipboard_text` to `gui.clipboard_text`. + * Renamed `textadept.context_menu` to `gui.context_menu`. + * Renamed `textadept.command_entry` to [`gui.command_entry`][]. + * Renamed `textadept.dialog` to [`gui.dialog()`][]. + * Renamed `textadept.docstatusbar_text` to `gui.docstatusbar_text`. + * Renamed `textadept.find` to [`gui.find`][]. + * Renamed `textadept.focused_doc_pointer` to `gui.focused_doc_pointer`. + * Renamed `textadept.get_split_table()` to [`gui.get_split_table()`][]. + * Renamed `textadept.gtkmenu()` to [`gui.gtkmenu()`][]. + * Renamed `textadept.goto_view()` to [`gui.goto_view()`][]. + * Renamed `textadept.menubar` to `gui.menubar`. + * Renamed `textadept.print()` to [`gui.print()`][]. + * Renamed `textadept.size` to `gui.size`. + * Renamed `textadept.statusbar_text` to `gui.statusbar_text`. + * Renamed `textadept.switch_buffer()` to [`gui.switch_buffer()`][]. + * Renamed `textadept.title` to `gui.title`. + * Renamed `textadept.new_buffer()` to [`new_buffer()`][]. + * Renamed `textadept.quit()` to [`quit()`][]. + * Renamed `textadept.reset()` to [`reset()`][]. + * Renamed `textadept.user_dofile()` to [`user_dofile()`][]. + * Renamed `textadept.iconv()` to [`string.iconv()`][]. + * Renamed `textadept.session_file` to `_SESSIONFILE`. +* Removed global `textadept` module. + +[API]: ../api +[`_m.textadept.snippets`]: ../api/_M.textadept.snippets.html +[`_G.events`]: ../api/events.html +[`events.emit()`]: ../api/events.html#emit +[`events.connect()`]: ../api/events.html#connect +[`_SCINTILLA.constants`]: ../api/_SCINTILLA.html#constants +[`_SCINTILLA.functions`]: ../api/_SCINTILLA.html#functions +[`_SCINTILLA.properties`]: ../api/_SCINTILLA.html#properties +[`_BUFFERS`]: ../api/_G.html#_BUFFERS +[`_VIEWS`]: ../api/_G.html#_VIEWS +[`gui`]: ../api/gui.html +[`gui._print()`]: ../api/gui.html#_print +[`gui.command_entry`]: ../api/gui.command_entry.html +[`gui.dialog()`]: ../api/gui.html#dialog +[`gui.find`]: ../api/gui.find.html +[`gui.get_split_table()`]: ../api/gui.html#get_split_table +[`gui.gtkmenu()`]: ../api/gui.html#gtkmenu +[`gui.goto_view()`]: ../api/gui.html#goto_view +[`gui.print()`]: ../api/gui.html#print +[`gui.switch_buffer()`]: ../api/gui.html#switch_buffer +[`new_buffer()`]: ../api/_G.html#new_buffer +[`quit()`]: ../api/_G.html#quit +[`reset()`]:../api/_G.html#reset +[`user_dofile()`]: ../api/_G.html#user_dofile +[`string.iconv()`]: ../api/string.html#iconv -- cgit v1.2.3