From 03b0b8932ea1c41854a487f9fa6555def9b59462 Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Mon, 30 Jun 2014 13:06:25 -0400 Subject: Condensed manual and API documentation into single files. --- CHANGELOG.md | 416 +++--- FAQ.md | 18 +- README.md | 2 +- core/._M.luadoc | 51 +- core/.buffer.luadoc | 190 ++- core/.view.luadoc | 10 +- core/args.lua | 2 +- core/events.lua | 42 +- core/file_io.lua | 8 +- core/init.lua | 10 +- core/keys.lua | 15 +- core/lfs_ext.lua | 4 +- core/ui.lua | 19 +- doc/.api_index.md | 6 - doc/.header.md | 4 +- doc/01_Introduction.md | 68 - doc/02_Installation.md | 194 --- doc/03_UserInterface.md | 55 - doc/04_WorkingWithFiles.md | 167 --- doc/05_FileNavigation.md | 36 - doc/06_AdeptEditing.md | 324 ----- doc/07_Modules.md | 81 -- doc/08_Preferences.md | 192 --- doc/09_Themes.md | 103 -- doc/10_Advanced.md | 89 -- doc/11_Scripting.md | 103 -- doc/12_Compiling.md | 190 --- doc/13_Help.md | 29 - doc/14_Appendix.md | 691 ---------- doc/index.html | 18 +- doc/manual.md | 2370 +++++++++++++++++++++++++++++++++++ doc/markdowndoc.lua | 199 ++- modules/ansi_c/init.lua | 1 - modules/lua/init.lua | 3 +- modules/textadept/command_entry.lua | 12 +- modules/textadept/editing.lua | 8 +- modules/textadept/find.lua | 1 + modules/textadept/keys.lua | 4 +- modules/textadept/menu.lua | 7 +- modules/textadept/run.lua | 6 +- modules/textadept/session.lua | 12 +- modules/textadept/snippets.lua | 8 +- src/Makefile | 8 +- 43 files changed, 2853 insertions(+), 2923 deletions(-) delete mode 100644 doc/.api_index.md delete mode 100644 doc/01_Introduction.md delete mode 100644 doc/02_Installation.md delete mode 100644 doc/03_UserInterface.md delete mode 100644 doc/04_WorkingWithFiles.md delete mode 100644 doc/05_FileNavigation.md delete mode 100644 doc/06_AdeptEditing.md delete mode 100644 doc/07_Modules.md delete mode 100644 doc/08_Preferences.md delete mode 100644 doc/09_Themes.md delete mode 100644 doc/10_Advanced.md delete mode 100644 doc/11_Scripting.md delete mode 100644 doc/12_Compiling.md delete mode 100644 doc/13_Help.md delete mode 100644 doc/14_Appendix.md create mode 100644 doc/manual.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0645caa6..9d144403 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -81,15 +81,15 @@ Changes: [Textadept 7.3 -- Linux]: download/textadept_7.3.i386.tgz [Textadept 7.3 -- Linux x86_64]: download/textadept_7.3.x86_64.tgz [Textadept 7.3 -- Modules]: download/textadept_7.3.modules.zip -[`spawn()`]: api/_G.html#spawn -[`buffer:set_encoding()`]: api/buffer.html#set_encoding -[autocompleter functions]: api/textadept.editing.html#autocompleters -[api file format]: api/textadept.editing.html#api_files -[`textadept.editing.autocomplete`]: api/textadept.editing.html#autocomplete -[`textadept.editing.AUTOCOMPLETE_ALL`]: api/textadept.editing.html#AUTOCOMPLETE_ALL -[`textadept.menu.menubar`]: api/textadept.menu.html#menubar -[`textadept.menu.context_menu`]: api/textadept.menu.html#context_menu -[`textadept.menu.tab_context_menu`]: api/textadept.menu.html#tab_context_menu +[`spawn()`]: api.html#spawn +[`buffer:set_encoding()`]: api.html#buffer.set_encoding +[autocompleter functions]: api.html#textadept.editing.autocompleters +[api file format]: api.html#textadept.editing.api_files +[`textadept.editing.autocomplete`]: api.html#textadept.editing.autocomplete +[`textadept.editing.AUTOCOMPLETE_ALL`]: api.html#textadept.editing.AUTOCOMPLETE_ALL +[`textadept.menu.menubar`]: api.html#textadept.menu.menubar +[`textadept.menu.context_menu`]: api.html#textadept.menu.context_menu +[`textadept.menu.tab_context_menu`]: api.html#textadept.menu.tab_context_menu [Scintilla]: http://scintilla.org ## 7.2 (01 May 2014) @@ -173,11 +173,11 @@ Changes: [Textadept 7.2 beta 3 -- Linux]: download/textadept_7.2_beta_3.i386.tgz [Textadept 7.2 beta 3 -- Linux x86_64]: download/textadept_7.2_beta_3.x86_64.tgz [Textadept 7.2 beta 3 -- Modules]: download/textadept_7.2_beta_3.modules.zip -[optionselect]: api/ui.dialogs.html#optionselect -[`ui.SILENT_PRINT`]: api/ui.html#SILENT_PRINT -[spawn processes]: api/_G.html#spawn -[Snapopen]: 04_WorkingWithFiles.html#Snapopen -[building projects]: api/_M.html#Build.a.Project +[optionselect]: api.html#ui.dialogs.optionselect +[`ui.SILENT_PRINT`]: api.html#ui.SILENT_PRINT +[spawn processes]: api.html#spawn +[Snapopen]: manual.html#Snapopen +[building projects]: api.html#_M.Build.a.Project [LuaJIT]: http://luajit.org [Scintilla]: http://scintilla.org @@ -231,7 +231,7 @@ Changes: [Textadept 7.2 beta -- Linux]: download/textadept_7.2_beta.i386.tgz [Textadept 7.2 beta -- Linux x86_64]: download/textadept_7.2_beta.x86_64.tgz [Textadept 7.2 beta -- Modules]: download/textadept_7.2_beta.modules.zip -[inputdialogs]: api/ui.dialogs.html#inputbox +[inputdialogs]: api.html#ui.dialogs.inputbox [Scintilla]: http://scintilla.org ## 7.2 alpha (01 Jan 2014) @@ -258,7 +258,7 @@ Changes: * Added Dart lexer. * Do not split the view when printing messages if tabs are enabled. * Look for *~/.textadept/osx_env.sh* for [OSX environment variables][] due to - changes in Mac OSX 10.9. + changes in Mac OSX 1n0.9. * [Experimental] Replaced Lua's `io.popen()` and `os.execute()` with versions that do not flash the "black box" on Windows. * Added read-only access to the current key chain via [`keys.keychain`][]. @@ -274,9 +274,9 @@ Changes: [Textadept 7.2 alpha -- Linux]: download/textadept_7.2_alpha.i386.tgz [Textadept 7.2 alpha -- Linux x86_64]: download/textadept_7.2_alpha.x86_64.tgz [Textadept 7.2 alpha -- Modules]: download/textadept_7.2_alpha.modules.zip -[`ui.maximized`]: api/ui.html#maximized -[OSX environment variables]: 02_Installation.html#Environment.Variables -[`keys.keychain`]: api/keys.html#keychain +[`ui.maximized`]: api.html#ui.maximized +[OSX environment variables]: manual.html#Mac.OSX.Environment.Variables +[`keys.keychain`]: api.html#keys.keychain [Lua]: http://lua.org [Scintilla]: http://scintilla.org @@ -311,10 +311,10 @@ Changes: [Textadept 7.1 -- Linux]: download/textadept_7.1.i386.tgz [Textadept 7.1 -- Linux x86_64]: download/textadept_7.1.x86_64.tgz [Textadept 7.1 -- Modules]: download/textadept_7.1.modules.zip -[`ui.tabs`]: api/ui.html#tabs -[`textadept.editing.STRIP_TRAILING_SPACES`]: api/textadept.editing.html#STRIP_TRAILING_SPACES -[`ui.clipboard_text`]: api/ui.html#clipboard_text -[`events.FILE_CHANGED`]: api/io.html#_G.events.FILE_CHANGED +[`ui.tabs`]: api.html#ui.tabs +[`textadept.editing.STRIP_TRAILING_SPACES`]: api.html#textadept.editing.STRIP_TRAILING_SPACES +[`ui.clipboard_text`]: api.html#ui.clipboard_text +[`events.FILE_CHANGED`]: api.html#events.FILE_CHANGED ## 7.0 (01 Nov 2013) @@ -341,13 +341,13 @@ Changes: * `textadept.adeptsense.goto_ctag()` can show all known tags now. * [`textadept.editing.enclose()`][] encloses the whole current word. -[6 to 7 migration guide]: 14_Appendix.html#Textadept.6.to.7 +[6 to 7 migration guide]: manual.html#Textadept.6.to.7 [Textadept 7.0 -- Win32]: download/textadept_7.0.win32.zip [Textadept 7.0 -- Mac OSX Intel 10.5+]: download/textadept_7.0.osx.zip [Textadept 7.0 -- Linux]: download/textadept_7.0.i386.tgz [Textadept 7.0 -- Linux x86_64]: download/textadept_7.0.x86_64.tgz [Textadept 7.0 -- Modules]: download/textadept_7.0.modules.zip -[`textadept.editing.enclose()`]: api/textadept.editing.html#enclose +[`textadept.editing.enclose()`]: api.html#textadept.editing.enclose ## 7.0 beta 5 (21 Oct 2013) @@ -380,9 +380,9 @@ Changes: [Textadept 7.0 beta 5 -- Linux]: download/textadept_7.0_beta_5.i386.tgz [Textadept 7.0 beta 5 -- Linux x86_64]: download/textadept_7.0_beta_5.x86_64.tgz [Textadept 7.0 beta 5 -- Modules]: download/textadept_7.0_beta_5.modules.zip -[`ui.set_theme()`]: api/ui.html#set_theme -[`textadept.editing.INDIC_BRACEMATCH`]: api/textadept.editing.html#INDIC_BRACEMATCH -[`buffer`]: api/buffer.html +[`ui.set_theme()`]: api.html#ui.set_theme +[`textadept.editing.INDIC_BRACEMATCH`]: api.html#textadept.editing.INDIC_BRACEMATCH +[`buffer`]: api.html#buffer ## 7.0 beta 4 (01 Oct 2013) @@ -428,18 +428,18 @@ Changes: [Textadept 7.0 beta 4 -- Linux]: download/textadept_7.0_beta_4.i386.tgz [Textadept 7.0 beta 4 -- Linux x86_64]: download/textadept_7.0_beta_4.x86_64.tgz [Textadept 7.0 beta 4 -- Modules]: download/textadept_7.0_beta_4.modules.zip -[`events.disconnect()`]: api/events.html#disconnect -[`buffer.filename`]: api/buffer.html#filename -[`_CHARSET`]: api/_G.html#_CHARSET -[`textadept.editing.select_word()`]: api/textadept.editing.html#select_word -[`convert_eols()`]: api/buffer.html#convert_eols -[`textadept.run.MARK_WARNING`]: api/textadept.run.html#MARK_WARNING -[`compile_commands`]: api/textadept.run.html#compile_commands -[`run_commands`]: api/textadept.run.html#run_commands -[`error_patterns`]: api/textadept.run.html#error_patterns -[`ui.dialogs`]: api/ui.dialogs.html -[`io.open_file()`]: api/io.html#open_file -[`io.snapopen()`]: api/io.html#snapopen +[`events.disconnect()`]: api.html#events.disconnect +[`buffer.filename`]: api.html#buffer.filename +[`_CHARSET`]: api.html#_CHARSET +[`textadept.editing.select_word()`]: api.html#textadept.editing.select_word +[`convert_eols()`]: api.html#buffer.convert_eols +[`textadept.run.MARK_WARNING`]: api.html#textadept.run.MARK_WARNING +[`compile_commands`]: api.html#textadept.run.compile_commands +[`run_commands`]: api.html#textadept.run.run_commands +[`error_patterns`]: api.html#textadept.run.error_patterns +[`ui.dialogs`]: api.html#ui.dialogs +[`io.open_file()`]: api.html#io.open_file +[`io.snapopen()`]: api.html#io.snapopen ## 7.0 beta 3 (11 Sep 2013) @@ -469,7 +469,7 @@ Changes: * Removed `textadept.bookmarks.BOOKMARK_COLOR`, `textadept.editing.HIGHLIGHT_COLOR`, and `textadept.run.ERROR_COLOR` while exposing their respective marker and indicator numbers for customization. -* Moved buffer IO functions into [`io`][]. +* Moved buffer IO functions into [`io` module][]. * Updated to [CDK][] 5.0-20130901. [Textadept 7.0 beta 3 -- Win32]: download/textadept_7.0_beta_3.win32.zip @@ -477,13 +477,13 @@ Changes: [Textadept 7.0 beta 3 -- Linux]: download/textadept_7.0_beta_3.i386.tgz [Textadept 7.0 beta 3 -- Linux x86_64]: download/textadept_7.0_beta_3.x86_64.tgz [Textadept 7.0 beta 3 -- Modules]: download/textadept_7.0_beta_3.modules.zip -[`events.LEXER_LOADED`]: api/textadept.file_types.html#_G.events.LEXER_LOADED -[`ui`]: api/ui.html -[`textadept`]: api/textadept.html -[`events.INITIALIZED`]: api/events.html#INITIALIZED -[`buffer.style_name`]: api/buffer.html#style_name -[`ui.bufstatusbar_text`]: api/ui.html#bufstatusbar_text -[`io`]: api/io.html +[`events.LEXER_LOADED`]: api.html#events.LEXER_LOADED +[`ui`]: api.html#ui +[`textadept`]: api.html#textadept +[`events.INITIALIZED`]: api.html#events.INITIALIZED +[`buffer.style_name`]: api.html#buffer.style_name +[`ui.bufstatusbar_text`]: api.html#ui.bufstatusbar_text +[`io` module]: api.html#io [CDK]: http://invisible-island.net/cdk/cdk.html ## 7.0 beta 2 (11 Aug 2013) @@ -511,8 +511,8 @@ Changes: [Textadept 7.0 beta 2 -- Linux]: download/textadept_7.0_beta_2.i386.tgz [Textadept 7.0 beta 2 -- Linux x86_64]: download/textadept_7.0_beta_2.x86_64.tgz [Textadept 7.0 beta 2 -- Modules]: download/textadept_7.0_beta_2.modules.zip -[`gui.set_theme()`]: api/ui.html#set_theme -[`gui.maximized`]: api/ui.html#maximized +[`gui.set_theme()`]: api.html#ui.set_theme +[`gui.maximized`]: api.html#ui.maximized [Scintilla]: http://scintilla.org ## 7.0 beta (11 Jul 2013) @@ -543,8 +543,8 @@ Changes: [Textadept 7.0 beta -- Linux]: download/textadept_7.0_beta.i386.tgz [Textadept 7.0 beta -- Linux x86_64]: download/textadept_7.0_beta.x86_64.tgz [Textadept 7.0 beta -- Modules]: download/textadept_7.0_beta.modules.zip -[`_M.textadept.file_types`]: api/textadept.file_types.html -[directly]: 08_Preferences.html#File.Types +[`_M.textadept.file_types`]: api.html#textadept.file_types +[directly]: manual.html#File.Types ## 7.0 alpha 2 (01 Jul 2013) @@ -565,8 +565,8 @@ Bugfixes: Changes: -* Makefile improvements. See the [compiling][] page for more information. The - source release is no longer necessary. +* Makefile improvements. See [compiling][] for more information. The source + release is no longer necessary. * Removed `_G._LEXERPATH` and `_L._EXISTS()`. * Renamed Adeptsense image fields. * Renamed `_M.textadept.editing.STRIP_WHITESPACE_ON_SAVE` to @@ -588,10 +588,10 @@ Changes: [Textadept 7.0 alpha 2 -- Linux]: download/textadept_7.0_alpha_2.i386.tgz [Textadept 7.0 alpha 2 -- Linux x86_64]: download/textadept_7.0_alpha_2.x86_64.tgz [Textadept 7.0 alpha 2 -- Modules]: download/textadept_7.0_alpha_2.modules.zip -[compiling]: 12_Compiling.html -[`_M.textadept.editing.block_comment()`]: api/textadept.editing.html#block_comment -[`gui.set_theme()`]: api/ui.html#set_theme -[`_M.textadept.bookmarks.goto_mark()`]: api/textadept.bookmarks.html#goto_mark +[compiling]: manual.html#Compiling +[`_M.textadept.editing.block_comment()`]: api.html#textadept.editing.block_comment +[`gui.set_theme()`]: api.html#ui.set_theme +[`_M.textadept.bookmarks.goto_mark()`]: api.html#textadept.bookmarks.goto_mark [LuaJIT]: http://luajit.org [nightly builds]: README.html#Download @@ -622,8 +622,8 @@ Changes: [Textadept 7.0 alpha -- Linux x86_64]: download/textadept_7.0_alpha.x86_64.tgz [Textadept 7.0 alpha -- Source]: download/textadept_7.0_alpha.src.zip [Textadept 7.0 alpha -- Modules]: download/textadept_7.0_alpha.modules.zip -[theme implementation]: 09_Themes.html -[*properties.lua*]: 08_Preferences.html#Buffer.Properties +[theme implementation]: manual.html#Themes +[*properties.lua*]: manual.html#Buffer.Settings [Scintilla]: http://scintilla.org ## 6.6 (01 Jun 2013) @@ -712,14 +712,14 @@ Changes: [Textadept 6.6 beta -- Source]: download/textadept_6.6_beta.src.zip [Textadept 6.6 beta -- Modules]: download/textadept_6.6_beta.modules.zip [Messagebox]: http://foicica.com/gtdialog/02_Usage.html#Messageboxes -[key modes]: api/keys.html#Modes +[key modes]: api.html#keys.Modes [Scintilla]: http://scintilla.org -[`buffer.new()`]: api/buffer.html#new -[`_M.textadept.editing.filter_through()`]: api/textadept.editing.html#filter_through -[`_M.textadept.run.goto_error()`]: api/textadept.run.html#goto_error -[`gui.find.goto_file_found()`]: api/gui.find.html#goto_file_found -[`_M.textadept.editing.select_enclosed()`]: api/textadept.editing.html#select_enclosed -[`io.encodings`]: api/io.html#encodings +[`buffer.new()`]: api.html#buffer.new +[`_M.textadept.editing.filter_through()`]: api.html#textadept.editing.filter_through +[`_M.textadept.run.goto_error()`]: api.html#textadept.run.goto_error +[`gui.find.goto_file_found()`]: api.html#ui.find.goto_file_found +[`_M.textadept.editing.select_enclosed()`]: api.html#textadept.editing.select_enclosed +[`io.encodings`]: api.html#io.encodings ## 6.5 (01 Apr 2013) @@ -757,11 +757,11 @@ Changes: [Textadept 6.5 -- Linux x86_64]: download/textadept_6.5.x86_64.tgz [Textadept 6.5 -- Source]: download/textadept_6.5.src.zip [Textadept 6.5 -- Modules]: download/textadept_6.5.modules.zip -[`_M.textadept.run.cwd`]: api/textadept.run.html#cwd -[`lfs.dir_foreach()`]: api/lfs.html#dir_foreach -[filtering]: api/gui.find.html#FILTER -[`io`]: api/io.html#snapopen -[`lexer` constants]: api/lexer.html#FOLD_BASE +[`_M.textadept.run.cwd`]: api.html#textadept.run.cwd +[`lfs.dir_foreach()`]: api.html#lfs.dir_foreach +[filtering]: api.html#ui.find.FILTER +[`io`]: api.html#io.snapopen +[`lexer` constants]: api.html#lexer.FOLD_BASE [Scintilla]: http://scintilla.org [Lua]: http://lua.org @@ -795,7 +795,7 @@ Changes: [Textadept 6.4 -- Linux x86_64]: download/textadept_6.4.x86_64.tgz [Textadept 6.4 -- Source]: download/textadept_6.4.src.zip [Textadept 6.4 -- Modules]: download/textadept_6.4.modules.zip -[command line switches]: 13_Help.html#Command.Line.Parameters +[command line switches]: manual.html#Command.Line.Parameters [Scintilla]: http://scintilla.org [LuaJIT]: http://luajit.org @@ -828,7 +828,7 @@ Changes: [Textadept 6.3 -- Source]: download/textadept_6.3.src.zip [Textadept 6.3 -- Modules]: download/textadept_6.3.modules.zip [Scintilla]: http://scintilla.org -[typeover characters]: api/textadept.editing.html#TYPEOVER_CHARS +[typeover characters]: api.html#textadept.editing.TYPEOVER_CHARS ## 6.2 (01 Jan 2013) @@ -857,7 +857,7 @@ Changes: [Textadept 6.2 -- Linux x86_64]: download/textadept_6.2.x86_64.tgz [Textadept 6.2 -- Source]: download/textadept_6.2.src.zip [Textadept 6.2 -- Modules]: download/textadept_6.2.modules.zip -[`_M.textadept.snapopen.open()`]: api/textadept.snapopen.html#open +[`_M.textadept.snapopen.open()`]: api.html#io.snapopen ## 6.1 (11 Dec 2012) @@ -893,7 +893,7 @@ Changes: [Textadept 6.1 -- Linux x86_64]: download/textadept_6.1.x86_64.tgz [Textadept 6.1 -- Source]: download/textadept_6.1.src.zip [Textadept 6.1 -- Modules]: download/textadept_6.1.modules.zip -[API documentation]: api/index.html +[API documentation]: api.html [LuaJIT]: http://luajit.org ## 6.0 (01 Nov 2012) @@ -930,15 +930,15 @@ Changes: * Updated to [Scintilla][] 3.2.3. * Updated to [LuaJIT][] 2.0.0-beta11. -[5 to 6 migration guide]: 14_Appendix.html#Textadept.5.to.6 +[5 to 6 migration guide]: manual.html#Textadept.5.to.6 [Textadept 6.0 -- Win32]: download/textadept_6.0.win32.zip [Textadept 6.0 -- Mac OSX Intel 10.5+]: download/textadept_6.0.osx.zip [Textadept 6.0 -- Linux]: download/textadept_6.0.i386.tgz [Textadept 6.0 -- Linux x86_64]: download/textadept_6.0.x86_64.tgz [Textadept 6.0 -- Source]: download/textadept_6.0.src.zip [Textadept 6.0 -- Modules]: download/textadept_6.0.modules.zip -[`event.FIND_WRAPPED`]: api/gui.find.html#_G.events.FIND_WRAPPED -[Python module]: api/_M.python.html +[`event.FIND_WRAPPED`]: api.html#events.FIND_WRAPPED +[Python module]: api.html#_M.python [Scintilla]: http://scintilla.org [LuaJIT]: http://luajit.org @@ -982,10 +982,10 @@ Changes: [Textadept 6.0 beta 3 -- Linux x86_64]: download/textadept_6.0_beta_3.x86_64.tgz [Textadept 6.0 beta 3 -- Source]: download/textadept_6.0_beta_3.src.zip [Textadept 6.0 beta 3 -- Modules]: download/textadept_6.0_beta_3.modules.zip -[`buffer:close()`]: api/buffer.html#close -[`RUN_OUTPUT` events]: api/textadept.run.html#Run.Events -[`string.iconv()`]: api/string.html#iconv -[`_M.textadept.keys`]: api/textadept.keys.html +[`buffer:close()`]: api.html#buffer.close +[`RUN_OUTPUT` events]: api.html#textadept.run.Run.Events +[`string.iconv()`]: api.html#string.iconv +[`_M.textadept.keys`]: api.html#textadept.keys ## 6.0 beta 2 (01 Sep 2012) @@ -1013,7 +1013,7 @@ Changes: * Consolidated `_M.textadept.bookmarks.add()` and `_M.textadept.bookmarks.remove()` into [`_M.textadept.bookmarks.toggle()`][]. * Updated manual images. -* [`_M.textadept.snapopen.DEFAULT_DEPTH`][] is now `99` since [`MAX`][] is the +* `_M.textadept.snapopen.DEFAULT_DEPTH` is now `99` since [`MAX`][] is the limiting factor. * Use constant names in theme options instead of nondescript integers. * Updated to [Scintilla][] 3.2.2. @@ -1024,10 +1024,9 @@ Changes: [Textadept 6.0 beta 2 -- Linux x86_64]: download/textadept_6.0_beta_2.x86_64.tgz [Textadept 6.0 beta 2 -- Source]: download/textadept_6.0_beta_2.src.zip [Textadept 6.0 beta 2 -- Modules]: download/textadept_6.0_beta_2.modules.zip -[`_M.textadept.menu.select_command()`]: api/textadept.menu.html#select_command -[`_M.textadept.bookmarks.toggle()`]: api/textadept.bookmarks.html#toggle -[`_M.textadept.snapopen.DEFAULT_DEPTH`]: api/textadept.snapopen.html#DEFAULT_DEPTH -[`MAX`]: api/textadept.snapopen.html#MAX +[`_M.textadept.menu.select_command()`]: api.html#textadept.menu.select_command +[`_M.textadept.bookmarks.toggle()`]: api.html#textadept.bookmarks.toggle +[`MAX`]: api.html#io.SNAPOPEN_MAX [Scintilla]: http://scintilla.org ## 6.0 beta (01 Aug 2012) @@ -1064,8 +1063,8 @@ Changes: [Textadept 6.0 beta -- Linux x86_64]: download/textadept_6.0_beta.x86_64.tgz [Textadept 6.0 beta -- Source]: download/textadept_6.0_beta.src.zip [Textadept 6.0 beta -- Modules]: download/textadept_6.0_beta.modules.zip -[`_M.textadept.session.load()`]: api/textadept.session.html#load -[`_M.textadept.session.save()`]: api/textadept.session.html#save +[`_M.textadept.session.load()`]: api.html#textadept.session.load +[`_M.textadept.session.save()`]: api.html#textadept.session.save [Scintilla]: http://scintilla.org ## 5.5 beta (01 Jul 2012) @@ -1103,9 +1102,9 @@ Changes: [Textadept 5.5 beta -- Linux x86_64]: download/textadept_5.5_beta.x86_64.tgz [Textadept 5.5 beta -- Source]: download/textadept_5.5_beta.src.zip [Textadept 5.5 beta -- Modules]: download/textadept_5.5_beta.modules.zip -[`gui.menu()`]: api/ui.html#menu -[`gui.statusbar_text`]: api/ui.html#statusbar_text -[compiling]: 12_Compiling.html +[`gui.menu()`]: api.html#ui.menu +[`gui.statusbar_text`]: api.html#ui.statusbar_text +[compiling]: manual.html#Compiling [Lua 5.2.1]: http://www.lua.org/manual/5.2/ [LuaJIT]: http://luajit.org @@ -1167,9 +1166,9 @@ Changes: [Textadept 5.3 -- Linux x86_64]: download/textadept_5.3.x86_64.tgz [Textadept 5.3 -- Source]: download/textadept_5.3.src.zip [Textadept 5.3 -- Modules]: download/textadept_5.3.modules.zip -[single-instance]: 02_Installation.html#Single.Instance +[single-instance]: manual.html#Single.Instance [GTK]: http://gtk.org -[require]: 02_Installation.html#Requirements +[require]: manual.html#Requirements [GLib]: http://gtk.org/download/linux.php [Scintilla]: http://scintilla.org @@ -1211,12 +1210,12 @@ Changes: [Textadept 5.2 -- Linux x86_64]: download/textadept_5.2.x86_64.tgz [Textadept 5.2 -- Source]: download/textadept_5.2.src.zip [Textadept 5.2 -- Modules]: download/textadept_5.2.modules.zip -[`buffer:get_lexer()`]: api/buffer.html#buffer.get_lexer -[`buffer:get_lexer(true)`]: api/buffer.html#buffer.get_lexer -[`_M.set_buffer_properties()`]: api/_M.html#Buffer.Properties -[`keys.KEYSYMS`]: api/keys.html#KEYSYMS -[`_G.timeout()`]: api/_G.html#timeout -[generating LuaDoc]: 11_Scripting.html#Generating.LuaDoc +[`buffer:get_lexer()`]: api.html#buffer.get_lexer +[`buffer:get_lexer(true)`]: api.html#buffer.get_lexer +[`_M.set_buffer_properties()`]: api.html#_M.Buffer.Properties +[`keys.KEYSYMS`]: api.html#keys.KEYSYMS +[`_G.timeout()`]: api.html#timeout +[generating LuaDoc]: manual.html#Generating.LuaDoc [GTK]: http://gtk.org [Scintilla]: http://scintilla.org @@ -1278,7 +1277,7 @@ Changes: * Updated to [Scintilla][] 3.0.3. * Also include [LuaJIT][] executables in releases. -[4 to 5 migration guide]: 14_Appendix.html#Textadept.4.to.5 +[4 to 5 migration guide]: manual.html#Textadept.4.to.5 [Textadept 5.0 -- Win32]: download/textadept_5.0.win32.zip [Textadept 5.0 -- Mac OSX Intel 10.5+]: download/textadept_5.0.osx.zip [Textadept 5.0 -- Linux]: download/textadept_5.0.tgz @@ -1318,11 +1317,11 @@ Changes: [Textadept 5.0 beta -- Linux x86_64]: download/textadept_5.0_beta.x86_64.tgz [Textadept 5.0 beta -- Source]: download/textadept_5.0_beta.src.zip [Textadept 5.0 beta -- Modules]: download/textadept_5.0_beta.modules.zip -[`reset()`]: api/_G.html#reset -[`_L`]: api/_L.html -[`_M`]: api/_M.html -[manual]: ./ -[`select_word()`]: api/textadept.editing.html#select_word +[`reset()`]: api.html#reset +[`_L`]: api.html#_L +[`_M`]: api.html#_M +[manual]: manual.html +[`select_word()`]: api.html#textadept.editing.select_word ## 5.0 alpha (21 Dec 2011) @@ -1352,7 +1351,7 @@ Changes: [Textadept 5.0 alpha -- Source]: download/textadept_5.0_alpha.src.zip [Textadept 5.0 alpha -- Modules]: download/textadept_5.0_alpha.modules.zip [Lua 5.2]: http://www.lua.org/manual/5.2/ -[manual]: ./ +[manual]: manual.html [LuaJIT]: http://luajit.org ## 4.3 (01 Dec 2011) @@ -1385,8 +1384,8 @@ Changes: [Textadept 4.3 -- Linux x86_64]: download/textadept_4.3.x86_64.tgz [Textadept 4.3 -- Source]: download/textadept_4.3.src.zip [Textadept 4.3 -- Modules]: download/textadept_4.3.modules.zip -[theme switching]: api/ui.html#set_theme -[gtkrc]: 8_Themes.html#Theming.the.GUI +[theme switching]: api.html#ui.set_theme +[gtkrc]: manual.html#GUI.Theme [Scintilla]: http://scintilla.org ## 4.2 (01 Nov 2011) @@ -1442,7 +1441,7 @@ Changes: + [`_BUFFERS`][] and [`_VIEWS`][] structure changed. + Removed `buffer.doc_pointer` and `view.doc_pointer`. + Added [`view.buffer`][] field. - + Renamed `gui.check_focused_buffer()` to [`buffer:check_global()`][]. + + Renamed `gui.check_focused_buffer()` to `buffer:check_global()`. + [`view:goto_buffer()`][] and [`gui.goto_view()`] arguments make sense now. (May require changes to custom key commands.) * Directory is remembered in file chooser dialog after open or save as. @@ -1457,14 +1456,13 @@ Changes: [Textadept 4.1 -- Linux x86_64]: download/textadept_4.1.x86_64.tgz [Textadept 4.1 -- Source]: download/textadept_4.1.src.zip [Textadept 4.1 -- Modules]: download/textadept_4.1.modules.zip -[dwell events]: api/events.html -[`_BUFFERS`]: api/_G.html#_BUFFERS -[`_VIEWS`]: api/_G.html#_VIEWS -[`view.buffer`]: api/view.html#buffer -[`buffer:check_global()`]: api/buffer.html#buffer.check_global -[`view:goto_buffer()`]: api/view.html#view:goto_buffer -[`gui.goto_view()`]: api/ui.html#goto_view -[context menu]: api/_M.html#Context.Menu +[dwell events]: api.html#events +[`_BUFFERS`]: api.html#_BUFFERS +[`_VIEWS`]: api.html#_VIEWS +[`view.buffer`]: api.html#view.buffer +[`view:goto_buffer()`]: api.html#view.goto_buffer +[`gui.goto_view()`]: api.html#ui.goto_view +[context menu]: api.html#_M.Context.Menu [LuaCoco]: http://coco.luajit.org/ [Scintilla]: http://scintilla.org @@ -1496,15 +1494,15 @@ Changes: * Changed some key commands from 4.0 beta 2. * Do not hide the statusbar when the command entry has focus. -[3 to 4 migration guide]: 14_Appendix.html#Textadept.3.to.4 +[3 to 4 migration guide]: manual.html#Textadept.3.to.4 [Textadept 4.0 -- Win32]: download/textadept_4.0.win32.zip [Textadept 4.0 -- Mac OSX Intel 10.5+]: download/textadept_4.0.osx.zip [Textadept 4.0 -- Linux]: download/textadept_4.0.tgz [Textadept 4.0 -- Linux x86_64]: download/textadept_4.0.x86_64.tgz [Textadept 4.0 -- Source]: download/textadept_4.0.src.zip [Textadept 4.0 -- Modules]: download/textadept_4.0.modules.zip -[`gui.dialog()`]: api/ui.html#dialog -[`buffer.auto_c_ignore_case`]: api/buffer.html#auto_c_ignore_case +[`gui.dialog()`]: api.html#ui.dialog +[`buffer.auto_c_ignore_case`]: api.html#buffer.auto_c_ignore_case ## 4.0 beta 2 (11 Aug 2011) @@ -1538,7 +1536,7 @@ Changes: [Textadept 4.0 beta 2 -- Linux x86_64]: download/textadept_4.0_beta_2.x86_64.tgz [Textadept 4.0 beta 2 -- Source]: download/textadept_4.0_beta_2.src.zip [Textadept 4.0 beta 2 -- Modules]: download/textadept_4.0_beta_2.modules.zip -[recent file list]: api/io.html#recent_files +[recent file list]: api.html#io.recent_files ## 4.0 beta (01 Aug 2011) @@ -1560,7 +1558,7 @@ Changes: * Mac OSX uses GTK 2.24. * Added [`io.open_recent_file()`][]. * Changes to localization file again. -* [`buffer` functions][] may omit the first `buffer` argument (e.g. +* [`buffer`][] functions may omit the first `buffer` argument (e.g. `buffer.line_down()` is allowed). * Complete overhaul of menus and added accelerators to [menu][] items. * Renamed `_m.textadept.editing.SAVE_STRIPS_WS` to @@ -1576,10 +1574,10 @@ Changes: [Textadept 4.0 beta -- Linux x86_64]: download/textadept_4.0_beta.x86_64.tgz [Textadept 4.0 beta -- Source]: download/textadept_4.0_beta.src.zip [Textadept 4.0 beta -- Modules]: download/textadept_4.0_beta.modules.zip -[`io.open_recent_file()`]: api/io.html#open_recent_file -[`buffer` functions]: api/buffer.html#Functions -[`_m.textadept.editing.STRIP_WHITESPACE_ON_SAVE`]: api/textadept.editing.html#STRIP_WHITESPACE_ON_SAVE -[menu]: api/ui.html#gtkmenu +[`io.open_recent_file()`]: api.html#io.open_recent_file +[`buffer`]: api.html#buffer +[`_m.textadept.editing.STRIP_WHITESPACE_ON_SAVE`]: api.html#textadept.editing.STRIP_WHITESPACE_ON_SAVE +[menu]: api.html#ui.menu [Scintilla]: http://scintilla.org ## 3.9 (01 Jul 2011) @@ -1617,11 +1615,11 @@ Changes: [Textadept 3.9 -- Source]: download/textadept_3.9.src.zip [Textadept 3.9 -- Modules]: download/textadept_3.9.modules.zip [GTK]: http://gtk.org -[`gui.dialog`]: api/ui.html#dialog -[functions]: api/_SCINTILLA.html#Functions +[`gui.dialog`]: api.html#ui.dialog +[functions]: api.html#_SCINTILLA [Scintilla]: http://scintilla.org -[emit events]: api/textadept.run.html#Run.Events -[find]: api/gui.find.html +[emit events]: api.html#events.COMPILE_OUTPUT +[find]: api.html#ui.find ## 3.8 (11 Jun 2011) @@ -1642,7 +1640,7 @@ Bugfixes: Changes: * Updated Adeptsense and documentation. -* [`events.handlers`][] is accessible. +* `events.handlers` is accessible. * Added menu mnemonics for indentation size. * Added support for indicator and hotspot [events][]. * Updated [documentation][] for installing [official modules][]. @@ -1657,12 +1655,11 @@ Changes: [Textadept 3.8 -- Linux x86_64]: download/textadept_3.8.x86_64.tgz [Textadept 3.8 -- Source]: download/textadept_3.8.src.zip [Textadept 3.8 -- Modules]: download/textadept_3.8.modules.zip -[`events.handlers`]: api/events.html#handlers -[events]: api/events.html -[documentation]: 7_Modules.html#Getting.Modules +[events]: api.html#events +[documentation]: manual.html#Getting.Modules [official modules]: http://foicica.com/hg [Scintilla]: http://scintilla.org -[easier]: api/lexer.html#Simple.Folding +[easier]: api.html#lexer.Code.Folding ## 3.7 (01 May 2011) @@ -1682,7 +1679,7 @@ Bugfixes: Changes: * Changed Mac OSX Adeptsense complete key command from `~` to `Ctrl+Escape`. -* Added [PHP module][]. +* Added PHP module. [Textadept 3.7 -- Win32]: download/textadept_3.7.win32.zip [Textadept 3.7 -- Mac OSX Intel 10.5+]: download/textadept_3.7.osx.zip @@ -1690,8 +1687,7 @@ Changes: [Textadept 3.7 -- Linux x86_64]: download/textadept_3.7.x86_64.tgz [Textadept 3.7 -- Source]: download/textadept_3.7.src.zip [Textadept 3.7 -- Modules]: download/textadept_3.7.modules.zip -[`buffer:get_lexer()`]: api/buffer.html#buffer.get_lexer -[PHP module]: api/_M.php.html +[`buffer:get_lexer()`]: api.html#buffer.get_lexer ## 3.7 beta 3 (01 Apr 2011) @@ -1714,8 +1710,8 @@ Changes: * Adeptsense tweaks for better completion and apidoc support. * Language modules load a user [`post_init.lua`][] script if it exists. -* Added Ruby on Rails lexer and [module][]. -* Added [RHTML module][]. +* Added Ruby on Rails lexer and module. +* Added RHTML module. * Updated mime-types and prioritize by shebang, pattern, and then file extension. * [`buffer:get_lexer(true)`] returns the lexer at the caret position. @@ -1742,13 +1738,11 @@ Changes: [Textadept 3.7 beta 3 -- Linux x86_64]: download/textadept_3.7_beta_3.x86_64.tgz [Textadept 3.7 beta 3 -- Source]: download/textadept_3.7_beta_3.src.zip [Textadept 3.7 beta 3 -- Modules]: download/textadept_3.7_beta_3.modules.zip -[`post_init.lua`]: 7_Modules.html#Customizing.Modules -[module]: api/_M.rails.html -[RHTML module]: api/_M.rhtml.html -[`buffer:get_lexer(true)`]: api/buffer.html#buffer.get_lexer +[`post_init.lua`]: manual.html#Language.Module.Preferences +[`buffer:get_lexer(true)`]: api.html#buffer.get_lexer [Scintilla]: http://scintilla.org -[`_m.textadept.snippets`]: api/textadept.snippets.html -[`gui.print()`]: api/ui.html#print +[`_m.textadept.snippets`]: api.html#textadept.snippets +[`gui.print()`]: api.html#ui.print [repositories]: http://foicica.com/hg ## 3.7 beta 2 (01 Mar 2011) @@ -1789,7 +1783,7 @@ Changes: * Language modules condensed into single `init.lua` file. * Added `sense.syntax.word_chars` to Adeptsense. * Included libpng12 build for 64-bit Debian-based Linux distros (Ubuntu). -* Added [CSS][], [HTML][], [Java][], and [Ruby][] modules with Adeptsenses. +* Added [CSS][], [HTML][], Java, and [Ruby][] modules with Adeptsenses. [Textadept 3.7 beta 2 -- Win32]: download/textadept_3.7_beta_2.win32.zip [Textadept 3.7 beta 2 -- Mac OSX Intel 10.5+]: download/textadept_3.7_beta_2.osx.zip @@ -1797,10 +1791,9 @@ Changes: [Textadept 3.7 beta 2 -- Linux x86_64]: download/textadept_3.7_beta_2.x86_64.tgz [Textadept 3.7 beta 2 -- Source]: download/textadept_3.7_beta_2.src.zip [Scintilla]: http://scintilla.org -[CSS]: api/_M.css.html -[HTML]: api/_M.html.html -[Java]: api/_M.java.html -[Ruby]: api/_M.ruby.html +[CSS]: api.html#_M.css +[HTML]: api.html#_M.html +[Ruby]: api.html#_M.ruby ## 3.7 beta (01 Feb 2011) @@ -1834,8 +1827,8 @@ Changes: [Textadept 3.7 beta -- Linux]: download/textadept_3.7_beta.tgz [Textadept 3.7 beta -- Linux x86_64]: download/textadept_3.7_beta.x86_64.tgz [Textadept 3.7 beta -- Source]: download/textadept_3.7_beta.src.zip -[`char_matches`]: api/textadept.editing.html#char_matches -[`braces`]: api/textadept.editing.html#braces +[`char_matches`]: api.html#textadept.editing.char_matches +[`braces`]: api.html#textadept.editing.braces ## 3.6 (01 Jan 2011) @@ -1868,9 +1861,9 @@ Changes: [Textadept 3.6 -- Linux]: download/textadept_3.6.tgz [Textadept 3.6 -- Linux x86_64]: download/textadept_3.6.x86_64.tgz [Textadept 3.6 -- Source]: download/textadept_3.6.src.zip -[`buffer.rectangular_selection_modifier`]: api/buffer.html#rectangular_selection_modifier -[`_m.textadept.filter_through`]: api/textadept.filter_through.html -[shell commands]: 10_Advanced.html#Shell.Commands.and.Filtering.Text +[`buffer.rectangular_selection_modifier`]: api.html#buffer.rectangular_selection_modifier +[`_m.textadept.filter_through`]: api.html#textadept.editing.filter_through +[shell commands]: manual.html#Shell.Commands.and.Filtering.Text ## 3.5 (01 Dec 2010) @@ -1894,17 +1887,17 @@ Changes: * Win32 and Mac OSX packages are all-in-one bundles; GTK is no longer an external dependency. * New [manual][]. -* Added `file_after_save` [event][]. +* Added [`file_after_save`][] event. [Textadept 3.5 -- Win32]: download/textadept_3.5.win32.zip [Textadept 3.5 -- Mac OSX Intel 10.5+]: download/textadept_3.5.osx.zip [Textadept 3.5 -- Linux]: download/textadept_3.5.tgz [Textadept 3.5 -- Linux x86_64]: download/textadept_3.5.x86_64.tgz [Textadept 3.5 -- Source]: download/textadept_3.5.src.zip -[Menus]: api/textadept.menu.html -[`_m.textadept.editing.enclose()`]: api/textadept.editing.html#enclose -[manual]: ./ -[event]: api/io.html#File.Events +[Menus]: api.html#textadept.menu +[`_m.textadept.editing.enclose()`]: api.html#textadept.editing.enclose +[manual]: manual.html +[`file_after_save`]: api.html#events.FILE_AFTER_SAVE ## 3.4 (01 Nov 2010) @@ -1932,7 +1925,7 @@ Changes: * An `update_ui` event is triggered after a Lua command is entered. * [`gui.dialog()`][] can take tables of strings as arguments now. * [`_m.textadept.snapopen.open()`][] takes a recursion depth as a parameter and - falls back on a [`DEFAULT_DEPTH`][] if necessary. + falls back on a `DEFAULT_DEPTH` if necessary. * Removed `_m.textadept.editing.smart_cutcopy()` and `_m.textadept.editing.squeeze()` functions. * Added `_m.textadept.editing.SAVE_STRIPS_WS` option to disable strip whitespace @@ -1955,16 +1948,15 @@ Changes: [Textadept 3.4 -- Linux]: download/textadept_3.4.tgz [Textadept 3.4 -- Linux x86_64]: download/textadept_3.4.x86_64.tgz [Textadept 3.4 -- Source]: download/textadept_3.4.src.zip -[Switch Buffers]: 4_WorkingWithFiles.html#Buffer.Browser -[`gui.dialog()`]: api/ui.html#dialog -[`_m.textadept.snapopen.open()`]: api/textadept.snapopen.html#open -[`DEFAULT_DEPTH`]: api/textadept.snapopen.html#DEFAULT_DEPTH -[`gui.statusbar_text`]: api/ui.html#statusbar_text -[highlight]: 6_AdeptEditing.html#Word.Highlight -[`_G.timeout()`]: api/_G.html#timeout -[find API]: api/gui.find.html#find_in_files +[Switch Buffers]: manual.html#Buffers +[`gui.dialog()`]: api.html#ui.dialog +[`_m.textadept.snapopen.open()`]: api.html#io.snapopen +[`gui.statusbar_text`]: api.html#ui.statusbar_text +[highlight]: manual.html#Word.Highlight +[`_G.timeout()`]: api.html#timeout +[find API]: api.html#ui.find.find_in_files [Scintilla]: http://scintilla.org -[`_G.OSX`]: api/_G.html#OSX +[`_G.OSX`]: api.html#OSX ## 3.3 (01 Oct 2010) @@ -1990,7 +1982,7 @@ Changes: [Textadept 3.3 -- Linux]: download/textadept_3.3.tgz [Textadept 3.3 -- Linux x86_64]: download/textadept_3.3.x86_64.tgz [Textadept 3.3 -- Source]: download/textadept_3.3.src.zip -[`_m.textadept.snapopen`]: api/textadept.snapopen.html +[`_m.textadept.snapopen`]: api.html#io.snapopen ## 3.2 (01 Sep 2010) @@ -2035,7 +2027,7 @@ Bugfixes: Changes: -* Refactored key commands to support [propagation][]. +* Refactored key commands to support propagation. * Updated to [Scintilla][] 2.20. * Added Lua autocompletion. @@ -2044,7 +2036,6 @@ Changes: [Textadept 3.1 -- Linux]: download/textadept_3.1.tgz [Textadept 3.1 -- Linux x86_64]: download/textadept_3.1.x86_64.tgz [Textadept 3.1 -- Source]: download/textadept_3.1.src.zip -[propagation]: api/keys.html#Propagation [Scintilla]: http://scintilla.org ## 3.0 (01 Jul 2010) @@ -2068,7 +2059,7 @@ Changes: * More accurate CSS and Diff lexers. -[2 to 3 migration guide]: 14_Appendix.html#Textadept.2.to.3 +[2 to 3 migration guide]: manual.html#Textadept.2.to.3 [Textadept 3.0 -- Win32]: download/textadept_3.0.win32.zip [Textadept 3.0 -- Mac OSX Intel 10.5+]: download/textadept_3.0.osx.zip [Textadept 3.0 -- Linux]: download/textadept_3.0.tgz @@ -2109,13 +2100,13 @@ Changes: [Textadept 3.0 beta -- Linux]: download/textadept_3.0_beta.tgz [Textadept 3.0 beta -- Linux x86_64]: download/textadept_3.0_beta.x86_64.tgz [Textadept 3.0 beta -- Source]: download/textadept_3.0_beta.src.zip -[`buffer:text_range()`]: api/buffer.html#buffer.text_range -[`textadept`]: api/textadept.html -[API]: api +[`buffer:text_range()`]: api.html#buffer.text_range +[`textadept`]: api.html#textadept +[API]: api.html [Scintilla]: http://scintilla.org -[Abbreviated]: 10_Advanced.html#Command.Entry -[arguments]: api/args.html -[`reset()`]: api/_G.html#reset +[Abbreviated]: manual.html#Lua.Command.Entry +[arguments]: api.html#args +[`reset()`]: api.html#reset ## 2.2 (11 May 2010) @@ -2143,8 +2134,8 @@ Changes: [Textadept 2.2 -- Linux]: download/textadept_2.2.tgz [Textadept 2.2 -- Linux x86_64]: download/textadept_2.2.x86_64.tgz [Textadept 2.2 -- Source]: download/textadept_2.2.src.zip -[`_USERHOME`]: api/_G.html#_USERHOME -[`_HOME`]: api/_G.html#_HOME +[`_USERHOME`]: api.html#_USERHOME +[`_HOME`]: api.html#_HOME ## 2.2 beta 2 (01 May 2010) @@ -2168,7 +2159,7 @@ Changes: * Added BSD support. * Removed kill-ring from editing module. -* [Run][] and [compile][] commands are in language modules. +* [Compile and Run][] commands are in language modules. * [Block comment][] strings are in language modules now. * Remove "Untitled" buffer when necessary. * Moved "Search" menu into "Tools" menu to prevent `Alt+S` key conflict. @@ -2181,10 +2172,9 @@ Changes: [Textadept 2.2 beta 2 -- Linux]: download/textadept_2.2_beta2.tgz [Textadept 2.2 beta 2 -- Linux x86_64]: download/textadept_2.2_beta2.x86_64.tgz [Textadept 2.2 beta 2 -- Source]: download/textadept_2.2_beta2.src.zip -[`buffer:text_range()`]: api/buffer.html#buffer.text_range -[run]: api/_M.html#Run -[compile]: api/_M.html#Compile -[Block comment]: api/_M.html#Block.Comment +[`buffer:text_range()`]: api.html#buffer.text_range +[Compile and run]: api.html#_M.Compile.and.Run +[Block comment]: api.html#textadept.editing.comment_string ## 2.2 beta (01 Apr 2010) @@ -2224,7 +2214,7 @@ Changes: [Textadept 2.2 beta -- Linux x86_64]: download/textadept_2.2_beta.x86_64.tgz [Textadept 2.2 beta -- Source]: download/textadept_2.2_beta.src.zip [gtdialog]: http://foicica.com/gtdialog -[`gui.dialog('filteredlist', ...)]: api/ui.html#dialog +[`gui.dialog('filteredlist', ...)]: api.html#ui.dialog ## 2.1 (01 Mar 2010) @@ -2263,8 +2253,8 @@ Changes: [Textadept 2.1 -- Linux]: download/textadept_2.1.tgz [Textadept 2.1 -- Linux x86_64]: download/textadept_2.1.x86_64.tgz [Textadept 2.1 -- Source]: download/textadept_2.1.src.zip -[`_USERHOME`]: api/_G.html#_USERHOME -[`_HOME`]: api/_G.html#_HOME +[`_USERHOME`]: api.html#_USERHOME +[`_HOME`]: api.html#_HOME [Scintilla]: http://scintilla.org ## 2.0 (01 Oct 2009) @@ -2300,8 +2290,8 @@ Changes: [Textadept 2.0 -- Linux]: download/textadept_2.0.tgz [Textadept 2.0 -- Linux x86_64]: download/textadept_2.0.x86_64.tgz [Textadept 2.0 -- Source]: download/textadept_2.0.src.zip -[`style_whitespace`]: api/lexer.html#style_whitespace -[lexers]: api/lexer.html +[`style_whitespace`]: api.html#lexer.STYLE_WHITESPACE +[lexers]: api.html#lexer ## 2.0 beta (31 Jul 2009) @@ -2355,15 +2345,15 @@ Changes: [Textadept 2.0 beta -- Linux]: download/textadept_2.0_beta.tgz [Textadept 2.0 beta -- Linux x86_64]: download/textadept_2.0_beta.x86_64.tgz [Textadept 2.0 beta -- Source]: download/textadept_2.0_beta.src.zip -[list of encodings]: api/io.html#try_encodings -[events]: api/events.html +[list of encodings]: api.html#io.encodings +[events]: api.html#events [Scintilla]: http://scintilla.org -[compile commands]: api/textadept.run.html#compile_commands -[run commands]: api/textadept.run.html#run_commands +[compile commands]: api.html#textadept.run.compile_commands +[run commands]: api.html#textadept.run.run_commands [gtdialog]: http://foicica.com/gtdialog [lua_dialog]: http://luaforge.net/projects/lua-dialog [cocoaDialog]: http://cocoadialog.sf.net -[Incremental find]: 6_AdeptEditing.html#Find.Incremental +[Incremental find]: manual.html#Incremental.Find [GTK]: http://gtk.org ## 1.6 (01 Apr 2009) @@ -2387,14 +2377,14 @@ Bugfixes: Updates: * Trimmed theme files. -* Added `file_before_save` [event][]. +* Added [`file_before_save`][] event. [Textadept 1.6 -- Win32]: download/textadept_1.6.win32.zip [Textadept 1.6 -- Mac OSX Intel 10.5+]: download/textadept_1.6.dmg [Textadept 1.6 -- Linux]: download/textadept_1.6.tgz [Textadept 1.6 -- Linux x86_64]: download/textadept_1.6.x86_64.tgz [Textadept 1.6 -- Source]: download/textadept_1.6.src.zip -[event]: api/io.html#File.Events +[`file_before_save`]: api.html#events.FILE_BEFORE_SAVE ## 1.6 beta (01 Mar 2009) @@ -2432,7 +2422,7 @@ Updates: [Textadept 1.6 beta -- Linux]: download/textadept_1.6beta.tgz [Textadept 1.6 beta -- Linux x86_64]: download/textadept_1.6beta.x86_64.tgz [Textadept 1.6 beta -- Source]: download/textadept_1.6beta.src.zip -[`_m.textadept.run`]: api/textadept.run.html +[`_m.textadept.run`]: api.html#textadept.run ## 1.5 (20 Feb 2009) @@ -2571,7 +2561,7 @@ Updates: [Textadept 1.2 -- Win32]: download/textadept_1.2.win32.zip [Textadept 1.2 -- Mac OSX Intel 10.5+]: download/textadept_1.2.dmg [Textadept 1.2 -- Linux]: download/textadept_1.2.tgz -[`_m.textadept.run`]: api/textadept.run.html +[`_m.textadept.run`]: api.html#textadept.run ## 1.1 (11 Jan 2009) @@ -2598,8 +2588,8 @@ Updates: [Textadept 1.1 -- Win32]: download/textadept_1.1_win32.zip [Textadept 1.1 -- Mac OSX Intel 10.5+]: download/textadept_1.1.dmg [Textadept 1.1 -- Linux]: download/textadept_1.1.tgz -[localization]: api/_L.html -[bookmarks]: api/textadept.bookmarks.html +[localization]: api.html#_L +[bookmarks]: api.html#textadept.bookmarks ## 1.0 (01 Jan 2009) @@ -2631,7 +2621,7 @@ Updates: [Textadept 1.0 -- Win32]: download/textadept_1.0_win32.zip [Textadept 1.0 -- Mac OSX Intel 10.5+]: download/textadept_1.0.dmg [Textadept 1.0 -- Linux]: download/textadept_1.0.tgz -[find]: api/gui.find.html +[find]: api.html#ui.find [GTK-OSX]: http://www.gtk.org/download/macos.php [LPeg]: http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html [LuaFileSystem]: http://keplerproject.github.com/luafilesystem/ @@ -2663,9 +2653,9 @@ Updates: [Textadept 0.6 -- Win32]: download/ta_beta_r6_win32.zip [Textadept 0.6 -- Linux]: download/ta_beta_r6.tgz [Textadept 0.6 -- Linux x86_64]: download/ta_beta_r6_x86_64.tgz -[Theming]: 8_Themes.html -[manual]: ./ -[pattern matching]: 9_Preferences.html#Detect.by.Pattern +[Theming]: manual.html#Themes +[manual]: manual.html +[pattern matching]: manual.html#File.Types ## 0.5 (23 Jul 2008) @@ -2720,8 +2710,8 @@ Updates: [Textadept 0.4 -- Mac OSX Intel 10.5+]: download/ta_beta_r4_osx.tgz [Textadept 0.4 -- Linux]: download/ta_beta_r4.tgz [Textadept 0.4 -- Linux x86_64]: download/ta_beta_r4_x86_64.tgz -[bookmark]: api/textadept.bookmarks.html -[tab-completion]: 10_Advanced.html#Tab.Completion +[bookmark]: api.html#textadept.bookmarks +[tab-completion]: manual.html#Command.Entry.Tab.Completion ## 0.3 (04 Mar 2008) @@ -2746,7 +2736,7 @@ Updates: * Fixed some code redundancy and typos in documentation. [Textadept 0.3 -- Linux]: download/ta_beta_r3.tgz -[`buffer.filename`]: api/buffer.html#filename +[`buffer.filename`]: api.html#buffer.filename [Zenity]: http://live.gnome.org/Zenity [lua_dialog]: http://luaforge.net/projects/lua-dialog diff --git a/FAQ.md b/FAQ.md index 2e6a0fff..05c1e4b9 100644 --- a/FAQ.md +++ b/FAQ.md @@ -11,7 +11,7 @@ delete your old `~/.textadept/` folder or move everything within it somewhere else before gradually copying those files back to see which of them causes an error. -[migration guide]: 14_Appendix.html#Textadept.6.to.7 +[migration guide]: manual.html#Textadept.6.to.7 - - - @@ -41,12 +41,12 @@ It is difficult to provide a binary that runs on all Linux platforms since the library versions installed vary widely from distribution to distribution. For example, "libpng14" has been available for many distributions since late 2009 while the latest 2012 Ubuntu still uses "libpng12". Unfortunately in these -cases, the best idea is to compile Textadept. This process is actually very -simple though. See the [compiling][] page. Only the GTK+ development libraries -are needed for the GUI version. (A development library for a curses -implementation is required for the terminal version.) +cases, the best idea is to [compile][] Textadept. This process is actually very +simple though. Only the GTK+ development libraries are needed for the GUI +version. (A development library for a curses implementation is required for the +terminal version.) -[compiling]: 12_Compiling.html +[compile]: manual.html#Compiling - - - @@ -88,7 +88,7 @@ When I open a file in a non-English language, I see a lot of strange characters. Textadept was not able to detect the file's encoding correctly. You'll need to [help it][]. -[help it]: 04_WorkingWithFiles.html#Encodings +[help it]: manual.html#Buffer.Encodings - - - @@ -100,7 +100,7 @@ Textadept which command to run? **A:** Please see the LuaDoc on [compile and run commands][]. -[compile and run commands]: api/_M.html#Compile.and.Run +[compile and run commands]: api.html#_M.Compile.and.Run - - - @@ -119,7 +119,7 @@ Please see the [curses compatibility][] section of the appendix. If the feature in question is not listed there, it may be a bug. Please [contact][] me with any bug reports. -[curses compatibility]: 14_Appendix.html#Curses.Compatibility +[curses compatibility]: manual.html#Curses.Compatibility [contact]: README.html#Contact - - - diff --git a/README.md b/README.md index f40450cd..e62af3d0 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ _Warning_: nightly builds are untested, may have bugs, and are the absolute cutting-edge versions of Textadept. Do not use them in production, but for testing purposes only. -[donation]: http://gum.co/textadept +[donate]: http://gum.co/textadept [book]: MEDIA.html#Book [download page]: http://foicica.com/textadept/download [Win32]: download/textadept_LATEST.win32.zip diff --git a/core/._M.luadoc b/core/._M.luadoc index 18df50d9..673597eb 100644 --- a/core/._M.luadoc +++ b/core/._M.luadoc @@ -28,35 +28,30 @@ -- The `Ctrl+Shift+R` and `Ctrl+R` (`⌘⇧R` and `⌘R` on Mac OSX | `M-^R` and `^R` -- in curses) key bindings compile and run code, respectively. If Textadept does -- not execute the correct commands for your language, modify them in the --- [`textadept.run.compile_commands`][] and [`textadept.run.run_commands`][] --- tables using the appropriate lexer key. Commands may contain [macros][]. For --- Lua, it would look like +-- [`textadept.run.compile_commands`]() and [`textadept.run.run_commands`]() +-- tables using the appropriate lexer key. Commands may contain macros. For Lua, +-- it would look like: -- --- textadept.run.compile_commands.lua = 'luac "%(filename)"' --- textadept.run.run_commands.lua = 'lua "%(filename)"' +-- textadept.run.compile_commands.lua = 'luac "%f"' +-- textadept.run.run_commands.lua = 'lua "%f"' -- -- Double-clicking on compile or runtime errors jumps to the error's location. -- If Textadept does not recognize your language's errors properly, add an error --- pattern to [`textadept.run.error_patterns`][]. The Lua error pattern looks +-- pattern to [`textadept.run.error_patterns`](). The Lua error pattern looks -- like -- -- table.insert(textadept.run.error_patterns, 1, -- '^luac?: (.-):(%d+): (.+)$') -- --- [`textadept.run.compile_commands`]: textadept.run.html#compile_commands --- [`textadept.run.run_commands`]: textadept.run.html#run_commands --- [macros]: textadept.run.html#execute --- [`textadept.run.error_patterns`]: textadept.run.html#error_patterns --- -- #### Build a Project -- -- The `Ctrl+Shift+B` (`⌘⇧B` on Mac OSX | `M-^B` in curses) key bindings build -- the current project. Textadept can only detect projects under version --- control, and uses [`io.get_project_root()`][] to do so. The editor looks in +-- control, and uses [`io.get_project_root()`]() to do so. The editor looks in -- the detected project's root directory for some sort of "makefile" (GNU -- Makefiles, Ruby Rakefiles, etc.) and prompts the user for any additional -- arguments to pass to that makefile's run command. Textadept references --- [`textadept.run.build_commands`][] for makefiles and their associated run +-- [`textadept.run.build_commands`]() for makefiles and their associated run -- commands. Per-project build commands may also be defined. For example, the -- following command builds Textadept after prompting for makefile targets: -- @@ -69,8 +64,6 @@ -- -- As with compile and run commands, any recognized errors are flagged. -- --- [`io.get_project_root()`]: io.html#get_project_root --- [`textadept.run.build_commands`]: textadept.run.html#build_commands -- -- #### Buffer Properties -- @@ -90,15 +83,14 @@ -- The `Ctrl+Space` and `Ctrl+H` (`⌥⎋` and `^H` on Mac OSX | `^Space` and `M-H` -- or `M-S-H` in curses) 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 [autocompleter][] and [API file(s)][]. --- --- [autocompleter]: textadept.editing.html#autocompleters --- [API file(s)]: textadept.editing.html#api_files +-- for your language, you must create an +-- [autocompleter](#textadept.editing.autocompleters) and +-- [API file(s)](#textadept.editing.api_files). -- -- #### Snippets -- --- [Snippets][] for common language constructs are useful. Some snippets for --- common Lua control structures look like +-- [Snippets](#textadept.snippets) for common language constructs are useful. +-- Some snippets for common Lua control structures look like -- -- snippets.lua = { -- f = "function %1(name)(%2(args))\n\t%0\nend", @@ -107,15 +99,13 @@ -- forp = "for %1(k), %2(v) in pairs(%3(table)) do\n\t%0\nend", -- } -- --- [Snippets]: textadept.snippets.html --- -- #### Commands -- -- 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 curses) key for easy access. +-- [Lua](#_M.lua) module has a feature to autocomplete the `end` keyword in a +-- control structure and the [C](#_M.ansi_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 curses) key for easy access. -- -- -- In file *lua/init.lua* | -- In file *cpp/init.lua* -- | @@ -127,12 +117,9 @@ -- ['s\n'] = M.try_to_autocomplete_end | end -- } | } -- --- [Lua]: _M.lua.html --- [C/C++]: _M.cpp.html --- -- #### Context Menu -- --- Language-specific [context menus][], accessible by right-clicking inside the +-- Language-specific context menus, accessible by right-clicking inside the -- view, are useful for accessing module features without using key bindings. -- For Lua this might look like -- @@ -149,6 +136,4 @@ -- {''}, -- {'Autocomplete "end"', M.try_to_autocomplete_end} -- } --- --- [context menus]: textadept.menu.html#context_menu module('_M')]] diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc index 298411d8..0f6874cd 100644 --- a/core/.buffer.luadoc +++ b/core/.buffer.luadoc @@ -20,10 +20,10 @@ -- The default value is `buffer.ALPHA_NOALPHA`, for no alpha. -- @field additional_sel_back (number, Write-only) -- The background color, in "0xBBGGRR" format, of additional selections. --- This field has no effect when calling `buffer:set_sel_back(false, ...)`. +-- This field has no effect when calling `buffer.set_sel_back(false, ...)`. -- @field additional_sel_fore (number, Write-only) -- The foreground color, in "0xBBGGRR" format, of additional selections. --- This field has no effect when calling `buffer:set_sel_fore(false, ...)`. +-- This field has no effect when calling `buffer.set_sel_fore(false, ...)`. -- @field additional_selection_typing (bool) -- Type into multiple selections. -- The default value is `false`. @@ -41,8 +41,7 @@ -- size/size_fractional, bold/weight, italics, fore, back, and character_set. -- @field annotation_style_offset (number) -- The beginning of the range of style numbers used for annotations. --- Always set this to the result of --- [`buffer.allocate_extended_styles`](#allocate_extended_styles). +-- Always set this to the result of [`buffer.allocate_extended_styles()`](). -- Annotation styles may be completely separated from standard text styles by -- setting a style offset. For example, when set to `512`, annotation styles -- are numbered from `512` upto `767` so they do not overlap styles set by @@ -74,7 +73,7 @@ -- The default value is `true`. -- @field auto_c_case_insensitive_behaviour (number) -- The behavior mode for a case insensitive autocompletion or user list when --- [`buffer.auto_c_ignore_case`](#auto_c_ignore_case) is `true`. +-- [`buffer.auto_c_ignore_case`]() is `true`. -- -- * `buffer.CASEINSENSITIVEBEHAVIOUR_RESPECTCASE` -- Prefer to select case-sensitive matches. @@ -121,13 +120,12 @@ -- The order setting for autocompletion and user lists. -- -- * `buffer.ORDER_PRESORTED` --- Lists passed to [`buffer.auto_c_show`](#auto_c_show) are in sorted, --- alphabetical order. +-- Lists passed to [`buffer.auto_c_show()`]() are in sorted, alphabetical +-- order. -- * `buffer.ORDER_PERFORMSORT` --- Sort autocompletion lists passed to [`buffer.auto_c_show`](#auto_c_show). +-- Sort autocompletion lists passed to [`buffer.auto_c_show()`](). -- * `buffer.ORDER_CUSTOM` --- Lists passed to [`buffer.auto_c_show`](#auto_c_show) are already in a --- custom order. +-- Lists passed to [`buffer.auto_c_show()`]() are already in a custom order. -- -- The default value is `buffer.ORDER_PRESORTED`. -- @field auto_c_separator (number) @@ -138,10 +136,9 @@ -- The character byte that separates autocompletion and user list items and -- their image types. -- Autocompletion and user list items can display both an image and text. --- Register images and their types using --- [`buffer:register_image()`](#register_image) or --- [`buffer:register_rgba_image()`](#register_rgba_image) before appending --- image types to list items after type separator characters. +-- Register images and their types using [`buffer.register_image()`]() or +-- [`buffer.register_rgba_image()`]() before appending image types to list +-- items after type separator characters. -- The default value is 63 ('?'). -- @field back_space_un_indents (bool) -- Un-indent text when backspacing within indentation. @@ -154,9 +151,9 @@ -- @field call_tip_fore_hlt (number, Write-only) -- A call tip's highlighted text foreground color, in "0xBBGGRR" format. -- @field call_tip_pos_start (number, Write-only) --- The position to display a call tip at with --- [`buffer.call_tip_show()`](#call_tip_show). When a call tip is visible, --- this is the position where backspacing beyond it hides the call tip. +-- The position to display a call tip at with [`buffer.call_tip_show()`](). +-- When a call tip is visible, this is the position where backspacing beyond +-- it hides the call tip. -- @field call_tip_position (boolean) -- Display a call tip above the current line instead of below it. -- The default value is `false`. @@ -245,12 +242,11 @@ -- * `buffer.EDGE_NONE` -- Long lines are not marked. -- * `buffer.EDGE_LINE` --- Draw a vertical line whose color is [`buffer.edge_colour`](#edge_colour) --- at column [`buffer.edge_column`](#edge_column). +-- Draw a vertical line whose color is [`buffer.edge_colour`]() at column +-- [`buffer.edge_column`](). -- * `buffer.EDGE_BACKGROUND` --- Change the background color of text after column --- [`buffer.edge_column`](#edge_column) to --- [`buffer.edge_colour`](#edge_colour). +-- Change the background color of text after column [`buffer.edge_column`]() +-- to [`buffer.edge_colour`](). -- @field encoding (string or nil) -- The string encoding of the file, or `nil` for binary files. -- @field encoding_bom (string) @@ -264,7 +260,7 @@ -- @field eol_mode (number) -- The current end of line mode. Changing the current mode does not convert -- any of the buffer's existing end of line characters. --- Use [`buffer:convert_eols()`](#convert_eols) to do so. +-- Use [`buffer.convert_eols()`]() to do so. -- -- * `buffer.EOL_CRLF` -- Carriage return with line feed ("\r\n"). @@ -289,7 +285,7 @@ -- Table of flags that indicate whether or not fold points are expanded for -- line numbers starting from zero. -- Setting expanded fold states does not toggle folds; it only updates fold --- margin markers. Use [`buffer:toggle_fold()`](#toggle_fold) instead. +-- margin markers. Use [`buffer.toggle_fold()`]() instead. -- @field fold_flags (number) -- Bit-mask of folding lines to draw in the buffer. -- @@ -337,8 +333,7 @@ -- The default value is `true`. -- @field indent (number) -- The number of spaces in one level of indentation. --- The default value is `0`, which uses the value of --- [`buffer.tab_width`](#tab_width). +-- The default value is `0`, which uses the value of [`buffer.tab_width`](). -- @field indentation_guides (number) -- The indentation guide drawing mode. -- Indentation guides are dotted vertical lines that appear within indentation @@ -389,10 +384,9 @@ -- A bounding box. -- * `buffer.INDIC_ROUNDBOX` -- A translucent box with rounded corners around the text. Use --- [`buffer.indic_alpha`](#indic_alpha) and --- [`buffer.indic_outline_alpha`](#indic_outline_alpha) to set the fill and --- outline transparency, respectively. Their default values are `30` and --- `50`. +-- [`buffer.indic_alpha`]() and [`buffer.indic_outline_alpha`]() to set the +-- fill and outline transparency, respectively. Their default values are +-- `30` and `50`. -- * `buffer.INDIC_STRAIGHTBOX` -- Similar to `INDIC_ROUNDBOX` but with sharp corners. -- * `buffer.INDIC_DASH` @@ -403,9 +397,8 @@ -- A squiggly underline 2 pixels in height. -- * `buffer.INDIC_DOTBOX` -- Similar to `INDIC_STRAIGHTBOX` but with a dotted outline. --- Translucency alternates between [`buffer.indic_alpha`](#indic_alpha) and --- [`buffer.indic_outline_alpha`](#indic_outline_alpha) starting with the --- top-left pixel. +-- Translucency alternates between [`buffer.indic_alpha`]() and +-- [`buffer.indic_outline_alpha`]() starting with the top-left pixel. -- * `buffer.INDIC_SQUIGGLEPIXMAP` -- Identical to `INDIC_SQUIGGLE` but draws faster by using a pixmap instead -- of multiple line segments. @@ -414,19 +407,16 @@ -- on either side. Similar in appearance to Asian language input -- composition. -- --- Use [`_SCINTILLA.next_indic_number()`][] for custom indicators. --- --- [`_SCINTILLA.next_indic_number()`]: _SCINTILLA.html#next_indic_number +-- Use [`_SCINTILLA.next_indic_number()`]() for custom indicators. -- @field indic_under (table) -- Table of flags that indicate whether or not to draw indicators behind text -- instead of over the top of it for indicator numbers from `0` to `31`. --- For values to be `true`, [`buffer.two_phase_draw`](#two_phase_draw) must be --- `true`. +-- For values to be `true`, [`buffer.two_phase_draw`]() must be `true`. -- The default values are `false`. -- @field indicator_current (number) -- The indicator number in the range of `0` to `31` used by --- [`buffer:indicator_fill_range()`](#indicator_fill_range) and --- [`buffer:indicator_clear_range()`](#indicator_clear_range). +-- [`buffer.indicator_fill_range()`]() and +-- [`buffer.indicator_clear_range()`](). -- @field length (number, Read-only) -- The number of bytes in the buffer. -- @field line_count (number, Read-only) @@ -496,8 +486,7 @@ -- italics, fore, and back. -- @field margin_style_offset (number) -- The beginning of the range of style numbers used for margin text. --- Always set this to the result of --- [`buffer.allocate_extended_styles`](#allocate_extended_styles). +-- Always set this to the result of [`buffer.allocate_extended_styles()`](). -- Margin styles may be completely separated from standard text styles by -- setting a style offset. For example, when set to `256`, margin styles are -- numbered from `256` upto `511` so they do not overlap styles set by lexers. @@ -550,7 +539,7 @@ -- `DWELL_START` event. A time of `buffer.TIME_FOREVER` will never generate -- one. -- @field mouse_selection_rectangular_switch (bool) --- Whether or not pressing `buffer.rectangular_selection_modifier` during +-- Whether or not pressing [`buffer.rectangular_selection_modifier`]() during -- normal text selection with the mouse turns on rectangular selection. -- The default value is `false`. -- @field modify (bool) @@ -580,7 +569,7 @@ -- or `0` if not found. -- @field punctuation_chars (string) -- The string set of characters recognized as punctuation characters. --- Set this only after setting [`buffer.word_chars`](#word_chars). +-- Set this only after setting [`buffer.word_chars`](). -- The default value is a string that contains all non-word and non-whitespace -- characters. -- @field read_only (bool) @@ -611,37 +600,34 @@ -- The alternative string representations of characters. -- Representations are displayed in the same way control characters are. Use -- the empty string for the '\0' character when assigning its representation. --- Call [`buffer:clear_representation()`](#clear_representation) to remove a --- representation. +-- Call [`buffer.clear_representation()`]() to remove a representation. -- @field rgba_image_height (number) -- The height of the RGBA image to be defined using --- [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image). +-- [`buffer.marker_define_rgba_image()`](). -- @field rgba_image_scale (number) -- The scale factor in percent of the RGBA image to be defined using --- [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image). +-- [`buffer.marker_define_rgba_image()`](). -- This is useful on OSX with a retina display where each display unit is 2 -- pixels: use a factor of `200` so that each image pixel is displayed using a -- screen pixel. The default scale, `100`, will stretch each image pixel to -- cover 4 screen pixels on a retina display. -- @field rgba_image_width (number) -- The width of the RGBA image to be defined using --- [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image) and --- [`buffer:register_rgba_image()`](#register_rgba_image). +-- [`buffer.marker_define_rgba_image()`]() and +-- [`buffer.register_rgba_image()`](). -- @field scroll_width (number) -- The horizontal scrolling pixel width. -- For performance, the view does not measure the display width of the buffer -- to determine the properties of the horizontal scroll bar, but uses an -- assumed width instead. To ensure the width of the currently visible lines --- can be scrolled use --- [`buffer.scroll_width_tracking`](#scroll_width_tracking). +-- can be scrolled use [`buffer.scroll_width_tracking`](). -- The default value is `2000`. -- @field scroll_width_tracking (bool) -- Continuously update the horizontal scrolling width to match the maximum --- width of a displayed line beyond [`buffer.scroll_width`](#scroll_width). +-- width of a displayed line beyond [`buffer.scroll_width`](). -- The default value is `false`. -- @field search_flags (number) --- The bit-mask of search flags used by --- [`buffer:search_in_target()`](#search_in_target). +-- The bit-mask of search flags used by [`buffer.search_in_target()`](). -- -- * `buffer.FIND_WHOLEWORD` -- Match search text only when it is surrounded by non-word characters. @@ -714,7 +700,7 @@ -- selected. -- -- When set, caret movement alters the selected text until this field is set --- again to the same value or until [`buffer:cancel()`](#cancel) is called. +-- again to the same value or until [`buffer.cancel()`]() is called. -- @field selection_n_anchor (table) -- Table of positions at the beginning of existing selections numbered from -- zero, the main selection. @@ -806,12 +792,10 @@ -- List of capture text for capture numbers from a regular expression search. -- @field target_end (number) -- The position of the end of the target range. --- This is also set by a successful --- [`buffer:search_in_target()`](#search_in_target). +-- This is also set by a successful [`buffer.search_in_target()`](). -- @field target_start (number) -- The position of the beginning of the target range. --- This is also set by a successful --- [`buffer:search_in_target()`](#search_in_target). +-- This is also set by a successful [`buffer.search_in_target()`](). -- @field text_length (number, Read-only) -- The number of bytes in the buffer. -- @field two_phase_draw (bool) @@ -819,17 +803,14 @@ -- The default value is `true`. -- @field undo_collection (bool) -- Collect undo information. --- When setting to `false`, call --- [`buffer:empty_undo_buffer()`](#empty_undo_buffer) to synchronize the undo --- buffer with the buffer text. +-- When setting to `false`, call [`buffer.empty_undo_buffer()`]() to +-- synchronize the undo buffer with the buffer text. -- The default value is `true`. -- @field use_tabs (bool) -- Use tabs instead of spaces in indentation. Changing the current setting -- does not convert any of the buffer's existing indentation. Use --- [`textadept.editing.convert_indentation()`][] to do so. +-- [`textadept.editing.convert_indentation()`]() to do so. -- The default value is `true`. --- --- [`textadept.editing.convert_indentation()`]: textadept.editing.html#convert_indentation -- @field v_scroll_bar (bool) -- Display the vertical scroll bar. -- The default value is `true`. @@ -862,7 +843,7 @@ -- The default value is `buffer.VS_NONE`. -- @field whitespace_chars (string) -- The string set of characters recognized as whitespace characters. --- Set this only after setting [`buffer.word_chars`](#word_chars). +-- Set this only after setting [`buffer.word_chars`](). -- The default value is a string that contains all non-newline characters less -- than ASCII value 33. -- @field whitespace_size (number) @@ -877,7 +858,7 @@ -- The wrapped line indent mode. -- -- * `buffer.WRAPINDENT_FIXED` --- Indent wrapped lines by [`buffer.wrap_start_indent`](#wrap_start_indent). +-- Indent wrapped lines by [`buffer.wrap_start_indent`](). -- * `buffer.WRAPINDENT_SAME` -- Indent wrapped lines the same amount as the first line. -- * `buffer.WRAPINDENT_INDENT` @@ -899,8 +880,7 @@ -- The default value is `buffer.WRAP_NONE`. -- @field wrap_start_indent (number) -- The number of spaces of indentation to display wrapped lines with if --- [`buffer.wrap_indent_mode`](#wrap_indent_mode) is --- `buffer.WRAP_INDENT_FIXED`. +-- [`buffer.wrap_indent_mode`]() is `buffer.WRAP_INDENT_FIXED`. -- The default value is `0`. -- @field wrap_visual_flags (number) -- The wrapped line visual flag display mode. @@ -1284,11 +1264,12 @@ module('buffer') -- Selects the range of text between positions *start_pos* to *end_pos* as the -- main selection, retaining all other selections as additional selections. -- Since an empty selection still counts as a selection, use --- `buffer:set_selection()` first when setting a list of selections. +-- `buffer.set_selection()` first when setting a list of selections. -- @param buffer A buffer. -- @param end_pos The caret position of the range of text to select in *buffer*. -- @param start_pos The anchor position of the range of text to select in -- *buffer*. +-- @see set_selection function add_selection(buffer, end_pos, start_pos) end --- @@ -1363,6 +1344,8 @@ function auto_c_select(buffer, prefix) end -- the context. -- @param items The sorted string of words to show, separated by -- `buffer.auto_c_separator` characters (initially spaces). +-- @see auto_c_separator +-- @see auto_c_order function auto_c_show(buffer, len_entered, items) end --- @@ -1543,8 +1526,8 @@ function clear_all(buffer) end function clear_document_style(buffer) end --- --- Clears all images registered using `buffer:register_image()` and --- `buffer:register_rgba_image()`. +-- Clears all images registered using `buffer.register_image()` and +-- `buffer.register_rgba_image()`. -- @param buffer A buffer. function clear_registered_images(buffer) end @@ -1749,7 +1732,7 @@ function ensure_visible(buffer, line) end --- -- Ensures line number *line* is visible by expanding any fold points hiding it -- based on the vertical caret policy previously defined in --- `buffer:set_visible_policy()`. +-- `buffer.set_visible_policy()`. -- @param buffer A buffer. -- @param line The line number in *buffer* to ensure visible. function ensure_visible_enforce_policy(buffer, line) end @@ -1927,7 +1910,7 @@ function home_rect_extend(buffer) end function home_wrap(buffer) end --- --- Like `buffer:home_wrap()`, but extends the selected text to the new position. +-- Like `buffer.home_wrap()`, but extends the selected text to the new position. -- @param buffer A buffer. function home_wrap_extend(buffer) end @@ -2060,7 +2043,7 @@ function line_end_rect_extend(buffer) end function line_end_wrap(buffer) end --- --- Like `buffer:line_end_wrap()`, but extends the selected text to the new +-- Like `buffer.line_end_wrap()`, but extends the selected text to the new -- position. -- @param buffer A buffer. function line_end_wrap_extend(buffer) end @@ -2078,7 +2061,7 @@ function line_from_position(buffer, pos) end -- Returns the number of bytes on line number *line*, including end of line -- characters. -- To get line length excluding end of line characters, use --- `buffer.line_end_position[line] - buffer:position_from_line(line)`. +-- `buffer.line_end_position[line] - buffer.position_from_line(line)`. -- @param buffer A buffer. -- @param line The line number in *buffer* to get the length of. -- @return number @@ -2151,7 +2134,7 @@ function margin_text_clear_all(buffer) end --- -- Adds marker number *marker*, in the range of `0` to `31`, to line number -- *line*, returning the added marker's handle which can be used in --- `buffer:marker_delete_handle()` and `buffer:marker_line_from_handle()`, or +-- `buffer.marker_delete_handle()` and `buffer.marker_line_from_handle()`, or -- `0` if *line* is invalid. -- @param buffer A buffer. -- @param line The line number to add the marker on. @@ -2234,9 +2217,9 @@ function marker_delete(buffer, line, marker) end function marker_delete_all(buffer, marker) end --- --- Deletes the marker with handle *handle* returned by `buffer:marker_add()`. +-- Deletes the marker with handle *handle* returned by `buffer.marker_add()`. -- @param buffer A buffer. --- @param handle The identifier of a marker returned by `buffer:marker_add()`. +-- @param handle The identifier of a marker returned by `buffer.marker_add()`. function marker_delete_handle(buffer, handle) end --- @@ -2258,9 +2241,9 @@ function marker_get(buffer, line) end --- -- Returns the line number that marker handle *handle*, returned by --- `buffer:marker_add()`, was added to, or `-1` if the line was not found. +-- `buffer.marker_add()`, was added to, or `-1` if the line was not found. -- @param buffer A buffer. --- @param handle The identifier of a marker returned by `buffer:marker_add()`. +-- @param handle The identifier of a marker returned by `buffer.marker_add()`. -- @return number function marker_line_from_handle(buffer, handle) end @@ -2290,8 +2273,8 @@ function marker_previous(buffer, line, marker_mask) end --- -- Returns the symbol assigned to marker number *marker*, in the range of `0` to --- `31`, used in `buffer:marker_define()`, --- `buffer:marker_define_pixmap()`, or `buffer:marker_define_rgba_image()`. +-- `31`, used in `buffer.marker_define()`, +-- `buffer.marker_define_pixmap()`, or `buffer.marker_define_rgba_image()`. -- @param buffer A buffer. -- @param marker The marker number in the range of `0` to `31` to get the symbol -- of. @@ -2314,8 +2297,7 @@ function move_selected_lines_down(buffer) end function move_selected_lines_up(buffer) end --- --- Types a new line at the caret position according to --- [`buffer.eol_mode`](#eol_mode). +-- Types a new line at the caret position according to [`buffer.eol_mode`](). -- @param buffer A buffer. function new_line(buffer) end @@ -2432,7 +2414,7 @@ function redo(buffer) end -- autocompletion and user lists. -- @param buffer A buffer. -- @param type Integer type to register the image with. --- @param xpm_data The XPM data as described in `buffer:marker_define_pixmap()`. +-- @param xpm_data The XPM data as described in `buffer.marker_define_pixmap()`. function register_image(buffer, type, xpm_data) end --- @@ -2445,11 +2427,11 @@ function register_image(buffer, type, xpm_data) end -- @param buffer A buffer. -- @param type Integer type to register the image with. -- @param pixels The RGBA data as described in --- `buffer:marker_define_rgba_image()`. +-- `buffer.marker_define_rgba_image()`. function register_rgba_image(buffer, type, pixels) end --- --- Releases all styles allocated with `buffer:allocate_extended_styles()`. +-- Releases all styles allocated with `buffer.allocate_extended_styles()`. -- @param buffer A buffer. -- @see allocate_extended_styles function release_all_extended_styles(buffer) end @@ -2487,7 +2469,7 @@ function rotate_selection(buffer) end --- -- Scrolls the caret into view based on the policies previously defined in --- `buffer:set_x_caret_policy()` and `buffer:set_y_caret_policy()`. +-- `buffer.set_x_caret_policy()` and `buffer.set_y_caret_policy()`. -- @param buffer A buffer. -- @see set_x_caret_policy -- @see set_y_caret_policy @@ -2496,7 +2478,7 @@ function scroll_caret(buffer) end --- -- Scrolls into view the range of text between positions *primary_pos* and -- *secondary_pos*, with priority given to *primary_pos*. --- Similar to `buffer:scroll_caret()`, but with *primary_pos* instead of +-- Similar to `buffer.scroll_caret()`, but with *primary_pos* instead of -- `buffer.current_pos`. -- This is useful for scrolling search results into view. -- @param buffer A buffer. @@ -2515,7 +2497,7 @@ function scroll_to_end(buffer) end function scroll_to_start(buffer) end --- --- Anchors the position that `buffer:search_next()` and `buffer:search_prev()` +-- Anchors the position that `buffer.search_next()` and `buffer.search_prev()` -- start at to the caret position. -- @param buffer A buffer. function search_anchor(buffer) end @@ -2675,8 +2657,8 @@ function set_text(buffer, text) end --- -- Defines scrolling policy bit-mask *policy* as the policy for keeping the -- caret *y* number of lines away from the vertical margins as --- `buffer:ensure_visible_enforce_policy()` redisplays hidden or folded lines. --- It is similar in operation to `buffer:set_y_caret_policy()`. +-- `buffer.ensure_visible_enforce_policy()` redisplays hidden or folded lines. +-- It is similar in operation to `buffer.set_y_caret_policy()`. -- @param buffer A buffer. -- @param policy The combination of `buffer.VISIBLE_SLOP` and -- `buffer.VISIBLE_STRICT` policy flags to set. @@ -2728,7 +2710,7 @@ function show_lines(buffer, start_line, end_line) end --- -- Begins styling at position *position* with styling bit-mask *styling_mask*. -- *styling_mask* specifies which style bits can be set with --- `buffer:set_styling()`. +-- `buffer.set_styling()`. -- @param buffer A buffer. -- @param position The position in *buffer* to start styling at. -- @param styling_mask The bit mask of style bits that can be set when styling. @@ -2742,7 +2724,7 @@ function start_styling(buffer, position, style_mask) end function stuttered_page_down(buffer) end --- --- Like `buffer:stuttered_page_down()`, but extends the selected text to the new +-- Like `buffer.stuttered_page_down()`, but extends the selected text to the new -- position. -- @param buffer A buffer. function stuttered_page_down_extend(buffer) end @@ -2753,7 +2735,7 @@ function stuttered_page_down_extend(buffer) end function stuttered_page_up(buffer) end --- --- Like `buffer:stuttered_page_up()`, but extends the selected text to the new +-- Like `buffer.stuttered_page_up()`, but extends the selected text to the new -- position. -- @param buffer A buffer. function stuttered_page_up_extend(buffer) end @@ -2853,18 +2835,18 @@ function vc_home(buffer) end function vc_home_display(buffer) end --- --- Like `buffer:vc_home_display()`, but extends the selected text to the new +-- Like `buffer.vc_home_display()`, but extends the selected text to the new -- position. -- @param buffer A buffer. function vc_home_display_extend(buffer) end --- --- Like `buffer:vc_home()`, but extends the selected text to the new position. +-- Like `buffer.vc_home()`, but extends the selected text to the new position. -- @param buffer A buffer. function vc_home_extend(buffer) end --- --- Like `buffer:vc_home()`, but extends the rectangular selection to the new +-- Like `buffer.vc_home()`, but extends the rectangular selection to the new -- position. -- @param buffer A buffer. function vc_home_rect_extend(buffer) end @@ -2876,7 +2858,7 @@ function vc_home_rect_extend(buffer) end function vc_home_wrap(buffer) end --- --- Like `buffer:vc_home_wrap()`, but extends the selected text to the new +-- Like `buffer.vc_home_wrap()`, but extends the selected text to the new -- position. -- @param buffer A buffer. function vc_home_wrap_extend(buffer) end @@ -2924,7 +2906,7 @@ function word_left(buffer) end function word_left_end(buffer) end --- --- Like `buffer:word_left_end()`, but extends the selected text to the new +-- Like `buffer.word_left_end()`, but extends the selected text to the new -- position. -- @param buffer A buffer. function word_left_end_extend(buffer) end @@ -2984,7 +2966,7 @@ function word_right(buffer) end function word_right_end(buffer) end --- --- Like `buffer:word_right_end()`, but extends the selected text to the new +-- Like `buffer.word_right_end()`, but extends the selected text to the new -- position. -- @param buffer A buffer. function word_right_end_extend(buffer) end @@ -3077,7 +3059,7 @@ function get_lexer(buffer, current) end -- @param buffer A buffer. -- @param lexer Optional string lexer name to set. If `nil`, attempts to -- auto-detect the buffer's lexer. --- @usage buffer.set_lexer(buffer, 'lexer_name') +-- @usage buffer:set_lexer('lexer_name') function set_lexer(buffer, lexer) end -- Unused Fields. diff --git a/core/.view.luadoc b/core/.view.luadoc index ecdc4061..c38a8485 100644 --- a/core/.view.luadoc +++ b/core/.view.luadoc @@ -8,7 +8,7 @@ module('view') --- --- The [buffer](buffer.html) the view contains. (Read-only) +-- The [buffer](#buffer) the view contains. (Read-only) -- @class table -- @name buffer local buffer @@ -35,14 +35,14 @@ function unsplit(view) end --- -- Switches to buffer number *n* in the view. -- *relative* indicates whether or not *n* is an index relative to the current --- buffer's index in `_G._BUFFERS` instead of an absolute index. +-- buffer's index in `_BUFFERS` instead of an absolute index. -- Emits `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events. -- @param view The view to switch buffers in. --- @param n A relative or absolute buffer index in `_G._BUFFERS`. An absolute --- index of `-1` goes to the last buffer. +-- @param n A relative or absolute buffer index in `_BUFFERS`. An absolute index +-- of `-1` goes to the last buffer. -- @param relative Optional flag indicating whether *n* is a relative or -- absolute index. The default value is `false`, for an absolute index. --- @see _G._G._BUFFERS +-- @see _G._BUFFERS -- @see events.BUFFER_BEFORE_SWITCH -- @see events.BUFFER_AFTER_SWITCH function goto_buffer(view, n, relative) end diff --git a/core/args.lua b/core/args.lua index cc34e837..d33191a4 100644 --- a/core/args.lua +++ b/core/args.lua @@ -43,7 +43,7 @@ end -- Emits an `ARG_NONE` event when no arguments are present. -- @param arg Argument table. -- @see register --- @see events +-- @see _G.events -- @name process function M.process(arg) local no_args = true diff --git a/core/events.lua b/core/events.lua index a79be38b..ebd3388a 100644 --- a/core/events.lua +++ b/core/events.lua @@ -13,7 +13,7 @@ local M = {} -- event has a set of event handlers, which are simply Lua functions called in -- the order they were connected to an event. For example, if you created a -- module that needs to do something each time Textadept creates a new buffer, --- connect a Lua function to the [BUFFER_NEW](#BUFFER_NEW) event: +-- connect a Lua function to the [`events.BUFFER_NEW`]() event: -- -- events.connect(events.BUFFER_NEW, function() -- -- Do something here. @@ -42,23 +42,23 @@ local M = {} -- Emitted after selecting an item from an autocompletion list, but before -- inserting that item into the buffer. -- Automatic insertion can be cancelled by calling --- [`buffer:auto_c_cancel()`][] before returning from the event handler. +-- [`buffer:auto_c_cancel()`]() before returning from the event handler. -- Arguments: -- -- * _`text`_: The selection's text. -- * _`position`_: The autocompleted word's beginning position. -- @field BUFFER_AFTER_SWITCH (string) -- Emitted right after switching to another buffer. --- Emitted by [`view:goto_buffer()`][]. +-- Emitted by [`view.goto_buffer()`](). -- @field BUFFER_BEFORE_SWITCH (string) -- Emitted right before switching to another buffer. --- Emitted by [`view:goto_buffer()`][]. +-- Emitted by [`view.goto_buffer()`](). -- @field BUFFER_DELETED (string) -- Emitted after deleting a buffer. --- Emitted by [`buffer:delete()`][]. +-- Emitted by [`buffer.delete()`](). -- @field BUFFER_NEW (string) -- Emitted after creating a new buffer. --- Emitted on startup and by [`buffer.new()`][]. +-- Emitted on startup and by [`buffer.new()`](). -- @field CALL_TIP_CLICK (string) -- Emitted when clicking on a calltip. -- Arguments: @@ -100,7 +100,7 @@ local M = {} -- * _`x`_: The x-coordinate of the mouse in the view. -- * _`y`_: The y-coordinate of the mouse in the view. -- @field DWELL_START (string) --- Emitted when the mouse is stationary for [`buffer.mouse_dwell_time`][] +-- Emitted when the mouse is stationary for [`buffer.mouse_dwell_time`]() -- milliseconds. -- Arguments: -- @@ -192,12 +192,12 @@ local M = {} -- Emitted after selecting a menu item. -- Arguments: -- --- * _`menu_id`_: The numeric ID of the menu item set in [`ui.menu()`][]. +-- * _`menu_id`_: The numeric ID of the menu item set in [`ui.menu()`](). -- @field QUIT (string) -- Emitted when quitting Textadept. -- When connecting to this event, connect with an index of 1 or the handler -- will be ignored. --- Emitted by [`quit()`][]. +-- Emitted by [`quit()`](). -- @field REPLACE (string) -- Emitted to replace selected (found) text. -- Arguments: @@ -211,10 +211,10 @@ local M = {} -- * _`repl_text`_: The replacement text. -- @field RESET_AFTER (string) -- Emitted after resetting the Lua state. --- Emitted by [`reset()`][]. +-- Emitted by [`reset()`](). -- @field RESET_BEFORE (string) -- Emitted before resetting the Lua state. --- Emitted by [`reset()`][]. +-- Emitted by [`reset()`](). -- @field SAVE_POINT_LEFT (string) -- Emitted after leaving a save point. -- @field SAVE_POINT_REACHED (string) @@ -242,30 +242,18 @@ local M = {} -- Emitted after selecting an item in a user list. -- Arguments: -- --- * _`id`_: The *id* from [`buffer:user_list_show()`][]. +-- * _`id`_: The *id* from [`buffer.user_list_show()`](). -- * _`text`_: The selection's text. -- * _`position`_: The position the list was displayed at. -- @field VIEW_NEW (string) -- Emitted after creating a new view. --- Emitted on startup and by [`view:split()`][]. +-- Emitted on startup and by [`view.split()`](). -- @field VIEW_BEFORE_SWITCH (string) -- Emitted right before switching to another view. --- Emitted by [`ui.goto_view()`][]. +-- Emitted by [`ui.goto_view()`](). -- @field VIEW_AFTER_SWITCH (string) -- Emitted right after switching to another view. --- Emitted by [`ui.goto_view()`][]. --- --- [`buffer:auto_c_cancel()`]: buffer.html#auto_c_cancel --- [`view:goto_buffer()`]: view.html#goto_buffer --- [`buffer.new()`]: buffer.html#new --- [`buffer:delete()`]: buffer.html#delete --- [`buffer.mouse_dwell_time`]: buffer.html#mouse_dwell_time --- [`ui.menu()`]: ui.html#menu --- [`quit()`]: _G.html#quit --- [`reset()`]: _G.html#reset --- [`buffer:user_list_show()`]: buffer.html#user_list_show --- [`view:split()`]: view.html#split --- [`ui.goto_view()`]: ui.html#goto_view +-- Emitted by [`ui.goto_view()`](). module('events')]] local handlers = {} diff --git a/core/file_io.lua b/core/file_io.lua index eb91ed2a..8c861bd5 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -5,25 +5,25 @@ -- Extends Lua's `io` library with Textadept functions for working with files. -- @field _G.events.FILE_OPENED (string) -- Emitted after opening a file in a new buffer. --- Emitted by [`open_file()`](#open_file). +-- Emitted by [`io.open_file()`](). -- Arguments: -- -- * _`filename`_: The opened file's filename. -- @field _G.events.FILE_BEFORE_SAVE (string) -- Emitted right before saving a file to disk. --- Emitted by [`io.save_file()`](#save_file). +-- Emitted by [`io.save_file()`](). -- Arguments: -- -- * _`filename`_: The filename of the file being saved. -- @field _G.events.FILE_AFTER_SAVE (string) -- Emitted right after saving a file to disk. --- Emitted by [`io.save_file()`](#save_file). +-- Emitted by [`io.save_file()`](). -- Arguments: -- -- * _`filename`_: The filename of the file being saved. -- @field _G.events.FILE_SAVED_AS (string) -- Emitted after saving a file under a different filename. --- Emitted by [`io.save_file_as()`](#save_file_as). +-- Emitted by [`io.save_file_as()`](). -- Arguments: -- -- * _`filename`_: The new filename. diff --git a/core/init.lua b/core/init.lua index 23d64b40..b2ca7e0e 100644 --- a/core/init.lua +++ b/core/init.lua @@ -57,7 +57,7 @@ end -- */Users/username/* respectively). -- @field _CHARSET (string) -- The filesystem's character encoding. --- This is used when [working with files](io.html). +-- This is used when [working with files](#io). -- @field WIN32 (bool) -- Whether or not Textadept is running on Windows. -- @field OSX (bool) @@ -66,7 +66,7 @@ end -- Whether or not Textadept is running in the terminal. -- Curses feature incompatibilities are listed in the [Appendix][]. -- --- [Appendix]: ../14_Appendix.html#Curses.Compatibility +-- [Appendix]: manual.html#Curses.Compatibility module('_G')]] --[[ The tables below were defined in C. @@ -74,7 +74,7 @@ module('_G')]] --- -- Table of command line parameters passed to Textadept. -- @class table --- @see _G.args +-- @see args -- @name arg local arg @@ -101,13 +101,13 @@ local _BUFFERS local _VIEWS --- --- The current [buffer](buffer.html) in the current [view](#view). +-- The current [buffer](#buffer) in the [current view](#_G.view). -- @class table -- @name buffer local buffer --- --- The current [view](view.html). +-- The current [view](#view). -- @class table -- @name view local view diff --git a/core/keys.lua b/core/keys.lua index 7d658a57..0761cfa1 100644 --- a/core/keys.lua +++ b/core/keys.lua @@ -47,7 +47,7 @@ local M = {} -- keyboard, since the combination of `Ctrl+Shift+,` has the key sequence `c<` -- (`Shift+,` inserts a `<`), Textadept recognizes the key binding as `Ctrl+<`. -- This allows key bindings to be language and layout agnostic. For key values --- greater than 255, Textadept uses the [`KEYSYMS`](#KEYSYMS) lookup table. +-- greater than 255, Textadept uses the [`keys.KEYSYMS`]() lookup table. -- Therefore, `Ctrl+Right Arrow` has the key sequence `cright`. Uncommenting the -- `print()` statements in *core/keys.lua* causes Textadept to print key -- sequences to standard out (stdout) for inspection. @@ -63,13 +63,11 @@ local M = {} -- keys['a('] = {textadept.editing.enclose, '(', ')'} -- keys['cu'] = function() io.snapopen(_USERHOME) end -- --- Textadept handles [`buffer`][] references properly in static contexts. --- --- [`buffer`]: buffer.html +-- Textadept handles [`buffer`]() references properly in static contexts. -- -- ## Modes -- --- Modes are groups of key bindings such that when a key [mode](#MODE) is +-- Modes are groups of key bindings such that when a key [mode](#keys.MODE) is -- active, Textadept ignores all key bindings defined outside the mode until the -- mode is unset. Here is a simple vi mode example: -- @@ -94,9 +92,10 @@ local M = {} -- -- Key chains are a powerful concept. They allow you to assign multiple key -- bindings to one key sequence. Language modules --- [use key chains](#LANGUAGE_MODULE_PREFIX) for their functions. By default, --- the `Esc` (`⎋` on Mac OSX | `Esc` in curses) key cancels a key chain, but you --- can redefine it via [`CLEAR`](#CLEAR). An example key chain looks like: +-- [use key chains](#keys.LANGUAGE_MODULE_PREFIX) for their functions. By +-- default, the `Esc` (`⎋` on Mac OSX | `Esc` in curses) key cancels a key +-- chain, but you can redefine it via [`keys.CLEAR`](). An example key chain +-- looks like: -- -- keys['aa'] = { -- a = function1, diff --git a/core/lfs_ext.lua b/core/lfs_ext.lua index a1d9c523..b43d8cc5 100644 --- a/core/lfs_ext.lua +++ b/core/lfs_ext.lua @@ -44,7 +44,7 @@ end -- Iterates over all files and sub-directories in directory *dir*, calling -- function *f* with each file found. -- Files passed to *f* do not match any pattern in string or table *filter*, --- and, unless *exclude_FILTER* is `true`, `FILTER` as well. A filter table +-- and, unless *exclude_FILTER* is `true`, `lfs.FILTER` as well. A filter table -- contains Lua patterns that match filenames to exclude, an optional `folders` -- sub-table that contains patterns matching directories to exclude, and an -- optional `extensions` sub-table that contains raw file extensions to exclude. @@ -55,7 +55,7 @@ end -- `false` explicitly, iteration ceases. -- @param filter Optional filter for files and directories to exclude. -- @param exclude_FILTER Optional flag indicating whether or not to exclude the --- default filter `FILTER` in the search. If `false`, adds `FILTER` to +-- default filter `lfs.FILTER` in the search. If `false`, adds `lfs.FILTER` to -- *filter*. -- The default value is `false` to include the default filter. -- @param recursing Utility flag indicating whether or not this function has diff --git a/core/ui.lua b/core/ui.lua index e78e6c29..df495476 100644 --- a/core/ui.lua +++ b/core/ui.lua @@ -8,13 +8,13 @@ local ui = ui -- @field title (string, Write-only) -- The title text of Textadept's window. -- @field context_menu (userdata) --- The buffer's context menu, a [`ui.menu()`](#menu). +-- The buffer's context menu, a [`ui.menu()`](). -- This is a low-level field. You probably want to use the higher-level --- `textadept.menu.context_menu`. +-- [`textadept.menu.context_menu`](). -- @field tab_context_menu (userdata) --- The context menu for the buffer's tab, a [`ui.menu()`](#menu). +-- The context menu for the buffer's tab, a [`ui.menu()`](). -- This is a low-level field. You probably want to use the higher-level --- `textadept.menu.tab_context_menu`. +-- [`textadept.menu.tab_context_menu`](). -- @field clipboard_text (string) -- The text on the clipboard. -- @field statusbar_text (string, Write-only) @@ -413,16 +413,15 @@ local size The functions below are Lua C functions. --- --- Low-level function for prompting the user with a [gtdialog][]s of kind *kind* +-- Low-level function for prompting the user with a [gtdialog][] of kind *kind* -- with the given string and table arguments, returning a formatted string of -- the dialog's output. --- You probably want to use the higher-level functions in the [`ui.dialogs`][] +-- You probably want to use the higher-level functions in the [`ui.dialogs`]() -- module. -- Table arguments containing strings are allowed and expanded in place. This is -- useful for filtered list dialogs with many items. -- -- [gtdialog]: http://foicica.com/gtdialog/02_Usage.html --- [`ui.dialogs`]: ui.dialogs.html -- @param kind The kind of gtdialog. -- @param ... Parameters to the gtdialog. -- @return string gtdialog result. @@ -445,12 +444,12 @@ local get_split_table --- -- Shifts to view number *n*. -- *relative* indicates whether or not *n* is an index relative to the current --- view's index in `_G._VIEWS` instead of an absolute index. +-- view's index in `_VIEWS` instead of an absolute index. -- Emits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events. --- @param n A relative or absolute view index in `_G._VIEWS`. +-- @param n A relative or absolute view index in `_VIEWS`. -- @param relative Optional flag that indicates whether *n* is a relative or -- absolute index. The default value is `false`, for an absolute index. --- @see _G._G._VIEWS +-- @see _G._VIEWS -- @see events.VIEW_BEFORE_SWITCH -- @see events.VIEW_AFTER_SWITCH -- @class function diff --git a/doc/.api_index.md b/doc/.api_index.md deleted file mode 100644 index 3a9fb25d..00000000 --- a/doc/.api_index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Lua API - -The Lua API documentation is a complement to the [manual][]. Please ensure you -are familiar with the basic concepts presented in the manual before proceeding. - -[manual]: ../01_Introduction.html diff --git a/doc/.header.md b/doc/.header.md index 22b11635..fbece29c 100644 --- a/doc/.header.md +++ b/doc/.header.md @@ -3,8 +3,8 @@ * [Home](http://foicica.com/textadept) | * [Download](http://foicica.com/textadept/download) | * [Book](http://foicica.com/textadept/MEDIA.html#book) | -* [Manual](http://foicica.com/textadept/01_Introduction.html) | -* [API](http://foicica.com/textadept/api) | +* [Manual](http://foicica.com/textadept/manual.html) | +* [API](http://foicica.com/textadept/api.html) | * [Source](http://foicica.com/hg/textadept) | * [Language Modules](http://foicica.com/hg) | * [Stats](http://foicica.com/stats.html#Textadept) | diff --git a/doc/01_Introduction.md b/doc/01_Introduction.md deleted file mode 100644 index 6c73f9ea..00000000 --- a/doc/01_Introduction.md +++ /dev/null @@ -1,68 +0,0 @@ -# Introduction - -## Overview - -![Textadept](images/textadept.png) - -Textadept is a fast, minimalist, and remarkably extensible cross-platform text -editor for programmers. Written in a combination of C and [Lua][] and -relentlessly optimized for speed and minimalism over the years, Textadept is an -ideal editor for programmers who want endless extensibility without sacrificing -speed or succumbing to code bloat and featuritis. - -[Lua]: http://lua.org - -### Fast - -Textadept is _fast_. It starts up instantly and has a very responsive user -interface. Even though the editor consists primarily of Lua, Lua is one of the -fastest scripting languages available. With the optional [LuaJIT][] version, -Textadept runs faster than ever before. - -[LuaJIT]: http://luajit.org - -### Minimalist - -Textadept is minimalist. Not only does its appearance exhibit this, but the -editor's C core pledges to never exceed 2000 lines of code and its Lua extension -code avoids going beyond 4000 lines. After more than 5 years of development, -Textadept contains the same amount of code since its inception while evolving -into a vastly superior editor. - -### Remarkably Extensible - -Textadept is remarkably extensible. Designed to be that way from the very -beginning, the editor's features came later. Most of Textadept's internals use -Lua, from syntax highlighting to opening and saving files to searching and -replacing and more. Textadept gives you complete control over the entire -application using Lua. Everything from moving the caret to changing menus and -key commands on-the-fly to handling core events is possible. Its potential is -vast. - -![Split Views](images/splitviews.png) - -## Manual Notation - -The manual represents directories and file paths like this: */path/to/dir/* and -*/path/to/file*. (Windows machines use '/' and '\' interchangeably as directory -separators.) Paths that do not begin with '/' or "C:\", are relative to the -location of Textadept. *~/* denotes the user's home directory. On Windows -machines this is the value of the "USERHOME" environment variable, typically -*C:\Users\username\\* or *C:\Documents and Settings\username\\*. On Linux, BSD, -and Mac OSX machines it is the value of "$HOME", typically */home/username/* and -*/Users/username/*, respectively. - -The manual expresses key bindings like this: `Ctrl+N`. They are not case -sensitive. `Ctrl+N` stands for pressing the "N" key while only holding down the -"Control" modifier key, not the "Shift" modifier key. `Ctrl+Shift+N` stands for -pressing the "N" key while holding down both the "Control" and "Shift" -modifiers. The same notation applies to key chains like `Ctrl+N, N` and -`Ctrl+N, Shift+N`. The first key chain represents pressing "Control" and "N" -followed by "N" with no modifiers. The second represents pressing "Control" and -"N" followed by "Shift" and "N". - -When mentioning key bindings, the manual often shows the Mac OSX and curses -equivalents in parenthesis. It may be tempting to assume that some Windows/Linux -keys map to Mac OSX's (e.g. `Ctrl` to `⌘`) or curses' (e.g. `Ctrl` to `^`), but -this is not always the case. To minimize confusion, view key equivalents as -separate entities, not as translations of one another. diff --git a/doc/02_Installation.md b/doc/02_Installation.md deleted file mode 100644 index 3363f135..00000000 --- a/doc/02_Installation.md +++ /dev/null @@ -1,194 +0,0 @@ -# Installation - -## Requirements - -In its bid for minimalism, Textadept also depends on very little to run. The GUI -version needs only [GTK+][], a cross-platform GUI toolkit, version 2.18 or later -on Linux and BSD systems. The application already bundles a GTK+ runtime into -the Windows and Mac OSX packages. The terminal, or curses, version of Textadept -only depends on a curses implementation like [ncurses][] on Linux, Mac OSX, and -BSD systems. The Windows binary includes a precompiled version of [pdcurses][]. -Textadept also incorporates its own [copy of Lua][] on all platforms. - -[GTK+]: http://gtk.org -[copy of Lua]: 11_Scripting.html#Lua.Configuration -[ncurses]: http://invisible-island.net/ncurses/ncurses.html -[pdcurses]: http://pdcurses.sourceforge.net - -### Linux and BSD - -Most Linux and BSD systems already have GTK+ installed. If not, your package -manager probably makes it available. Otherwise, compile and install GTK+from the -[GTK+ website][]. - -The Linux binaries for the GUI versions of Textadept require GLib version 2.28 -or later to support [single-instance](#Single.Instance) functionality. However, -Textadept compiles with versions of GLib as early as 2.22. For reference, Ubuntu -11.04, Debian Wheezy, Fedora 15, and openSUSE 11.4 support GLib 2.28 or later. - -Most Linux and BSD systems already have a curses implementation like ncurses -installed. If not, look for one in your package manager, or compile and install -ncurses from the [ncurses website][]. Ensure it is the wide-character version of -ncurses, which handles multibyte characters. Debian-based distributions like -Ubuntu typically call the package "libncursesw5". - -[GTK+ website]: http://www.gtk.org/download-linux.html -[ncurses website]: http://invisible-island.net/ncurses/#download_ncurses - -### Mac OSX - -No requirements other than Mac OSX 10.5 (Leopard) or higher with an Intel CPU. - -### Windows - -No requirements. - -## Download - -Download Textadept from the project's [download page][] by selecting the -appropriate package for your platform. For the Windows and Mac OSX packages, the -bundled GTK+ runtime accounts for more than 3/4 of the download and unpackaged -application sizes. Textadept itself is much smaller. - -You also have the option of downloading an official set of [language modules][] -from the download page. Textadept itself includes C/C++ and Lua language modules -by default. - -[download page]: http://foicica.com/textadept/download -[language modules]: 07_Modules.html#Language.Modules - -## Installation - -Installing Textadept is simple and easy. You do not need administrator -privileges. - -### Linux and BSD - -Unpack the archive anywhere. - -If you downloaded the set of language modules, unpack it where you unpacked the -Textadept archive. The modules are located in the -*/path/to/textadept_x.x/modules/* directory. - -### Mac OSX - -Unpack the archive and move *Textadept.app* to your user or system -*Applications/* directory like any other Mac OSX application. The package -contains an optional *ta* script for launching Textadept from the command line -that you can put in a directory in your "$PATH" (e.g. */usr/local/bin/*). - -If you downloaded the set of language modules, unpack it, right-click -*Textadept.app*, select "Show Package Contents", navigate to -*Contents/Resources/modules/*, and move the unpacked modules there. - -### Windows - -Unpack the archive anywhere. - -If you downloaded the set of language modules, unpack it where you unpacked the -Textadept archive. The modules are located in the *textadept_x.x\modules\\* -directory. - -## Running - -### Linux and BSD - -Run Textadept by running */path/to/textadept_x.x/textadept* from the terminal -You can also create a symbolic link to the executable in a directory in your -"$PATH" (e.g. */usr/local/bin/*) or make a GNOME, KDE, XFCE, etc. button or menu -launcher. - -The package also contains a *textadeptjit* executable for running Textadept with -[LuaJIT][]. Due to potential [compatibility issues][], use the *textadept* -executable wherever possible. - -The *textadept-curses* and *textadeptjit-curses* executables are the terminal -versions of Textadept. Run them as you would run the *textadept* and -*textadeptjit* executables, but from a terminal instead. - -[LuaJIT]: http://luajit.org -[compatibility issues]: 11_Scripting.html#LuaJIT - -#### Problems - -Providing a single binary that runs on all Linux platforms proves challenging, -since the versions of software installed vary widely from distribution to -distribution. Because the Linux version of Textadept uses the version of GTK+ -installed on your system, an error like: - - error while loading shared libraries: : cannot open shared object - file: No such file or directory - -may occur when trying to run the program. The solution is actually quite -painless even though it requires recompiling Textadept. The [compiling][] page -has more information. - -[compiling]: 12_Compiling.html - -### Mac OSX - -Run Textadept by double-clicking *Textadept.app*. You can also pin it to your -dock. - -*Textadept.app* also contains an executable for running Textadept with -[LuaJIT][]. Enable it by setting a "TEXTADEPTJIT" -[environment variable](#Environment.Variables) or by typing -`export TEXTADEPTJIT=1` in the terminal. Due to potential -[compatibility issues][], use the non-LuaJIT executable wherever possible. - -[LuaJIT]: http://luajit.org -[compatibility issues]: 11_Scripting.html#LuaJIT - -#### Environment Variables - -By default, Mac OSX GUI apps like Textadept do not see shell environment -variables like "$PATH". Consequently, any [modules][] that utilize programs -contained in "$PATH" (e.g. the progams in */usr/local/bin/*) for run and compile -commands will not find those programs. The solution is to create a -*~/.textadept/osx_env.sh* file that exports all of the environment variables you -need Textadept to see. For example: - - export PATH=$PATH - -[modules]: 07_Modules.html - -### Windows - -Run Textadept by double-clicking *textadept.exe*. You can also create shortcuts -to the executable in your Start Menu, Quick Launch toolbar, Desktop, etc. - -The package also contains a *textadeptjit.exe* executable for running Textadept -with [LuaJIT][]. Due to potential [compatibility issues][], use the -*textadept.exe* executable wherever possible. - -[LuaJIT]: http://luajit.org -[compatibility issues]: 11_Scripting.html#LuaJIT - -### *~/.textadept* - -Textadept stores all of your preferences and user-data in your *~/.textadept/* -directory. If this directory does not exist, Textadept creates it on startup. -The manual gives more information on this folder later. - -## Single Instance - -Textadept is a single-instance application on Linux, BSD, and Mac OSX. This -means that after starting Textadept, running `textadept file.ext` (`ta file.ext` -on Mac OSX) from the command line or opening a file with Textadept from a file -manager opens *file.ext* in the original Textadept instance. Passing a `-f` or -`--force` switch to Textadept overrides this behavior and opens the file in a -new instance: `textadept -f file.ext` (`ta -f file.ext`). Without the force -switch, the original Textadept instance opens files, regardless of the number of -instances open. - -The Windows and terminal versions of Textadept do not support single instance. - - -![Linux](images/linux.png) -   -![Mac OSX](images/macosx.png) -   -![Win32](images/win32.png) -   -![curses](images/ncurses.png) - diff --git a/doc/03_UserInterface.md b/doc/03_UserInterface.md deleted file mode 100644 index 19e28534..00000000 --- a/doc/03_UserInterface.md +++ /dev/null @@ -1,55 +0,0 @@ -# User Interface - -![UI](images/ui.png) - -Textadept's user interface is sleek and simple. It consists of a menu (GUI -version only), editor view, and statusbar. There is also a find & replace pane -and a command entry, but Textadept initially hides them both. The manual briefly -describes these features below, but provides more details later. - -## Menu - -The completely customizable menu provides access to all of Textadept's features. -Only the GUI version implements it, though. The terminal version furnishes the -[command selection][] dialog instead. Textadept is very keyboard-driven and -assigns key shortcuts to most menu items. Your [key preferences][] can change -these shortcuts and reflect in the menu. Here is a [complete list][] of default -key bindings. - -[command selection]: 10_Advanced.html#Command.Selection -[key preferences]: 08_Preferences.html#Key.Bindings -[complete list]: api/textadept.keys.html#Key.Bindings - -## Tab Bar - -The tab bar displays all of Textadept's open buffers, although it's only visible -when two or more buffers are open. While only the GUI version supports tabs, -Textadept's [buffer browser][] is always available and far more powerful. - -[buffer browser]: 04_WorkingWithFiles.html#Buffers - -## Editor View - -Most of your time spent with Textadept is in the editor view. Both the GUI -version and the terminal version feature unlimited vertical and horizontal view -splitting. Lua also has complete control over all views. - -## Find & Replace Pane - -This compact pane is a great way to slice and dice through your document or a -directory of files. It even supports finding and replacing text using Lua -patterns and Lua code. The pane is available only when you need it and quickly -gets out of your way when you do not, minimizing distractions. - -## Command Entry - -The versatile command entry functions as, among other things, a place to execute -Lua commands with Textadept's internal Lua state, find text incrementally, and -execute shell commands. Lua extensions allow it to do even more. Like the Find & -Replace pane, the command entry pops in and out as you wish. - -## Statusbar - -The statusbar actually consists of two statusbars. The one on the left-hand -side displays temporary status messages while the one on the right-hand side -persistently shows the current buffer status. diff --git a/doc/04_WorkingWithFiles.md b/doc/04_WorkingWithFiles.md deleted file mode 100644 index 0aba401d..00000000 --- a/doc/04_WorkingWithFiles.md +++ /dev/null @@ -1,167 +0,0 @@ -# Working with Files - -## Buffers - -Despite the fact that Textadept can display multiple buffers with a tab bar, the -buffer browser is usually a faster way to switch between buffers or quickly -assess which files are open. Press `Ctrl+B` (`⌘B` on Mac OSX | `M-B` or `M-S-B` -in curses) to display this browser. - -![Buffer Browser](images/bufferbrowser.png) - -The buffer browser displays a list of currently open buffers, the most recent -towards the bottom. Typing part of any filename filters the list. Spaces are -wildcards. The arrow keys move the selection up and down. Pressing `Enter`, -selecting `OK`, or double-clicking a buffer in the list switches to the selected -buffer. - -![Buffer Browser Filtered](images/bufferbrowserfiltered.png) - -Textadept shows the name of the active buffer in its titlebar. Pressing -`Ctrl+Tab` (`^⇥` on Mac OSX | `M-N` in curses) cycles to the next buffer and -`Ctrl+Shift+Tab` (`^⇧⇥` | `M-P`) cycles to the previous one. - -### Settings - -Individual files have three configurable settings: indentation, line endings, -and encoding. Indentation consists of an indentation character and an -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 - -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`) -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 module]: 07_Modules.html#Buffer.Properties -[user settings]: 08_Preferences.html#Buffer.Properties - -#### Line Endings - -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 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 -encoding and performs the conversion. Textadept saves new files as UTF-8 by -default, but does not alter the encoding of existing ones. - -[`io.encodings`]: api/io.html#encodings -[preferences]: 08_Preferences.html - -### Recent Files - -Pressing `Ctrl+Alt+O` (`^⌘O` on Mac OSX | `M-^O` in curses) brings up a dialog -that behaves like the buffer browser, but displays a list of recently opened -files to reopen. - -### Sessions - -By default, Textadept saves its state when quitting in order to restore it the -next time the editor starts up. Passing the `-n` or `--nosession` switch to -Textadept on startup disables this feature. The "File -> Save Session..." and -"File -> Load Session..." menus manually save and open sessions while the `-s` -and `--session` switches load a session on startup. The switches accept the path -of a session file or the name of a session in *~/.textadept/*. Session files -store information such as open buffers, current split views, caret and scroll -positions in each buffer, Textadept's window size, and recently opened files. -Tampering with session files may have unintended consequences. - -### Snapopen - -A quicker, though slightly more limited alternative to the standard file -selection dialog is snapopen. It too behaves like the buffer browser, but -displays a list of files to open, including files in sub-directories. Pressing -`Ctrl+Alt+Shift+O` (`^⌘⇧O` on Mac OSX | `M-S-O` in curses) snaps open the -current file's directory, `Ctrl+U` (`⌘U` | `^U`) snaps open *~/.textadept/*, and -`Ctrl+Alt+Shift+P` (`^⌘⇧P` | `M-^P`) snaps open the current project (which must -be under version control). Snapopen is pretty limited from the -"Tools -> Snapopen" menu, but more versatile in [scripts][]. - -[scripts]: api/io.html#snapopen - -![Snapopen](images/snapopen.png) - -## Views - -### Split Views - -Textadept allows you to split the editor window an unlimited number of times -both horizontally and vertically. `Ctrl+Alt+S` or `Ctrl+Alt+H` splits -horizontally into top and bottom views and `Ctrl+Alt+V` splits vertically (`^S` -and `^V`, respectively on Mac OSX | `M-^V S` and `M-^V V` in curses) into -side-by-side views. Clicking and dragging on the splitter bar with the mouse or -pressing `Ctrl+Alt++` and `Ctrl+Alt+-` (`^+` and `^-` | `M-^V +` and `M-^V -`) -resizes the split. Textadept supports viewing a single buffer in two or more -views. - -Pressing `Ctrl+Alt+N` (`^⌥⇥` on Mac OSX | `M-^V N` in curses) jumps to the next -view and `Ctrl+Alt+P` (`^⌥⇧⇥` | `M-^V P`) jumps the previous one. However, -depending on the split sequence, the order when cycling between views may not be -linear. - -To unsplit a view, enter the view to keep open and press `Ctrl+Alt+W` (`^W` on -Mac OSX | `M-^V W` in curses). To unsplit all views, use `Ctrl+Alt+Shift+W` -(`^⇧W` | `M-^V S-W`). - -Note: Textadept curses uses the `M-^V` key prefix for split views. - -### Settings - -Individual views have many configurable settings. Among the more useful settings -are viewing line endings, handling long lines, viewing indentation guides, and -viewing whitespace. These options change how to display buffers in the _current_ -view. Changing a setting in one view does not change that setting in -any other split view. You must do it manually. - -#### Line Endings - -Normally, EOL characters ("\r" and "\n") are invisible. Pressing -`Ctrl+Alt+Enter` (`^↩` on Mac OSX | none in curses) toggles their visibility. - -#### Long Lines - -By default, lines with more characters than the view can show do not wrap into -view. `Ctrl+Alt+\` (`^\` on Mac OSX | none in curses) toggles line wrapping. - -#### Indentation Guides - -Views show small guiding lines based on indentation level by default. -`Ctrl+Alt+Shift+I` (`^⇧I` on Mac OSX | N/A in curses) toggles the visibility of -these guides. - -Textadept curses does not support indentation guides. - -#### Whitespace - -Normally, whitespace characters, tabs and spaces, are invisible. Pressing -`Ctrl+Alt+Shift+S` (`^⇧S` on Mac OSX | none in curses) toggles their visibility. -Visible spaces show up as dots and visible tabs show up as arrows. - -### Zoom - -To temporarily increase or decrease the font size in a view, press `Ctrl+=` -(`⌘=` on Mac OSX | N/A in curses) and `Ctrl+-` (`⌘-` | N/A) respectively. -`Ctrl+0` (`⌘0` | N/A) resets the zoom. - -Textadept curses does not support zooming. diff --git a/doc/05_FileNavigation.md b/doc/05_FileNavigation.md deleted file mode 100644 index 47f65618..00000000 --- a/doc/05_FileNavigation.md +++ /dev/null @@ -1,36 +0,0 @@ -# File Navigation - -## Basic Movements - -Textadept implements the customary key bindings for navigating text fields on -the current platform. The arrow keys move the caret in a particular direction, -`Ctrl+Left` and `Ctrl+Right` (`^⇠` and `^⇢` on Mac OSX | `^Left` and `^Right` in -curses) move by words, `PgUp` and `PgDn` (`⇞` and `⇟` | `PgUp` and `PgDn`) move -by pages, etc. Mac OSX and curses also handle some Bash-style bindings like -`^B`, `^F`, `^P`, `^N`, `^A`, and `^E`. The "Movement" section of the -[key bindings list][] lists all movement bindings. - -[key bindings list]: api/textadept.keys.html#Key.Bindings - -## Brace Match - -By default, Textadept highlights the matching brace characters under the caret: -'(', ')', '[', ']', '{', and '}'. Pressing `Ctrl+M` (`^M` on Mac OSX | `M-M` in -curses) moves the caret to the matching brace. - -![Matching Braces](images/matchingbrace.png) - -## Bookmarks - -Textadept supports bookmarking buffer lines to jump back to them later. -`Ctrl+F2` (`⌘F2` on Mac OSX | `F1` in curses) toggles a bookmark on the current -line, `F2` jumps to the next bookmarked line, `Shift+F2` (`⇧F2` | `F3`) jumps to -the previously bookmarked line, `Alt+F2` (`⌥F2` | `F4`) jumps to the bookmark -selected from a list, and `Ctrl+Shift+F2` (`⌘⇧F2` | `F6`) clears all bookmarks -in the current buffer. - -## Goto Line - -To jump to a specific line in a file, press `Ctrl+J` (`⌘J` on Mac OSX | `^J` in -curses), specify the line number in the prompt, and press `Enter` (`↩` | -`Enter`) or click `Ok`. diff --git a/doc/06_AdeptEditing.md b/doc/06_AdeptEditing.md deleted file mode 100644 index 51c3115b..00000000 --- a/doc/06_AdeptEditing.md +++ /dev/null @@ -1,324 +0,0 @@ -# Adept Editing - -## Basic Editing - -Textadept features many common, basic editing features: inserting text, -undo/redo, manipulating the clipboard, deleting characters and words, -duplicating lines, joining lines, and transposing characters. The top-level -"Edit" menu contains these actions and lists their associated key bindings. The -manual discusses more elaborate editing features below. - -### Autopaired Characters - -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 typed one. The -[preferences][] page details how to configure or disable these features. - -[preferences]: 08_Preferences.html#Generic - -### Word Completion - -Textadept provides buffer-based word completion. Start typing a word and press -`Ctrl+Enter` (`^⎋` on Mac OSX | `M-Enter` in curses) to display a list of -suggested completions based on words in the current buffer. Continuing to type -changes the suggestion. Press `Enter` (`↩` | `Enter`) to complete the selected -word. - -![Word Completion](images/wordcompletion.png) - -### Virtual Space Mode - -Pressing `Ctrl+Alt+Shift+V` (`^⇧V` in Mac OSX | none in curses) enables and -disables Virtual space (freehand) mode. When virtual space is enabled, the caret -may move into the space past the ends of lines. - -### Overwrite Mode - -Enable and disable overwrite mode with the `Insert` key. When enabled, typing -overwrites existing characters in the buffer rather than inserting the typed -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 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 -effort, but has powerful uses. - -### Multiple 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 - -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) -     -![Rectangular Edit](images/rectangularselection2.png) - -Note: In some Linux environments, the window manager consumes `Alt+Shift+Arrow` -combinations so Textadept may need reconfiguring. Also, Textadept uses -`Super+Mouse` because `Alt+Mouse` generally moves windows. (Your window manager -usually defines the `Super` modifier key as the left "Windows" key.) If you -prefer to use `Alt`, change [`buffer.rectangular_selection_modifier`][] in your -[settings][]. - -Textadept curses does not support creating rectangular selections with the -mouse. - -[`buffer.rectangular_selection_modifier`]: api/buffer.html#rectangular_selection_modifier -[settings]: 08_Preferences.html#Buffer.Properties - -### Select to Matching Brace - -Putting the caret over a brace character ('(', ')', '[', ']', '{', or '}') and -pressing `Ctrl+Shift+M` (`^⇧M` on Mac OSX| `M-S-M` in curses) extends the -selection to the brace character's matching brace. - -### Entity Selection - -Textadept allows the selection of many different entities from the caret. For -example, `Ctrl+"` (`^"` on Mac OSX | `M-"` in curses) selects all characters in -a double-quoted range. Typing it again selects the double-quotes too. The -"Edit -> Select In..." menu lists all selectable entities with their key -bindings. - -### Marks - -In curses, since some terminals do not recognize certain key combinations like -`Shift+Arrow` for making selections, marks can create selections. Create a mark -at the current caret position with `^^`. Then use regular movement keys like the -arrows, page up/down, and home/end to extend the selection in one direction. -Pressing `^]` swaps the current caret position with the original mark position -in order to extend the selection in the opposite direction. Typing text, -deleting text, or running a command that does either, removes the mark and -restores ordinary navigation. Pressing `^^` again also stops selecting text. - -Only Textadept curses supports marks. - -### Transforms - -#### Enclose Entities - -As a complement to selecting entities, Textadept allows the enclosure of text in -entities. The "Edit -> Selection -> Enclose In..." menu lists all enclosing -entities with their key bindings. Each action encloses either the currently -selected text or the word to the left of the caret. For example, pressing -`Alt+<` (`^<` on Mac OSX | `M->` in curses) at the end of a word encloses it in -XML tags. - -#### Change Case - -Pressing `Ctrl+Alt+U` or `Ctrl+Alt+Shift+U` (`^U` or `^⇧U` on Mac OSX | `M-^U` -or `M-^L` in curses) converts selected text to upper case letters or lower case -letters, respectively. - -#### Change Indent Level - -Increase the amount of indentation for a selected set of lines by pressing `Tab` -(`⇥` on Mac OSX | `Tab` in curses). `Shift+Tab` (`⇧⇥` | `S-Tab`) decreases it. -You do not have to select whole lines. Selecting any part of a line renders the -entire line eligible for indenting/dedenting. Using these key sequences when no -selection is present does not have the same effect. - -#### Move Lines - -Move selected lines up and down with the `Ctrl+Shift+Up` and `Ctrl+Shift+Down` -(`^⇧⇡` and `^⇧⇣` on Mac OSX | `S-^Up` and `S-^Down` in curses) keys, -respectively. Like with changing indent level, selecting any part of a line -renders the entire line eligible for moving. - -## Find & Replace - -`Ctrl+F` (`⌘F` on Mac OSX | `M-F` or `M-S-F` in curses) brings up the Find & -Replace pane. In addition to offering the usual find and replace with "Match -Case" and "Whole Word" options and find/replace history, Textadept supports -finding with [Lua patterns][] and replacing with Lua captures and even Lua code! -For example: replacing all `%w+` with `%(string.upper('%0'))` upper cases all -words in the buffer. Replacement text only recognizes Lua captures (`%`_`n`_) -from a Lua pattern search, but always allows embedded Lua code enclosed in -`%()`. - -Note the `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, `Ctrl+Alt+Shift+R` key bindings -for find next, find previous, replace, and replace all (`⌘G`, `⌘⇧G`, `^R`, and -`^⇧R`, respectively on Mac OSX | `M-G`, `M-S-G`, `M-R`, `M-S-R` in curses) only -work after hiding the Find & Replace pane. For at least the English locale in -the GUI version, use the button mnemonics: `Alt+N`, `Alt+P`, `Alt+R`, and -`Alt+A` (`⌘N`, `⌘P`, `⌘R`, `⌘A` | N/A) after bringing up the pane. - -In the curses version, `Tab` and `S-Tab` toggles between the find next, find -previous, replace, and replace all buttons; `Up` and `Down` arrows switch -between the find and replace text fields; `^P` and `^N` cycles through history; -and `F1-F4` toggles find options. - -Pressing `Esc` (`⎋` | `Esc`) hides the pane after you finish with it. - -[Lua patterns]: 14_Appendix.html#Lua.Patterns - -### Replace in Selection - -By default, "Replace All" replaces all text in the buffer. Selecting a block of -text and then "Replace All" replaces all text in the selection. - -### Find in Files - -`Ctrl+Shift+F` brings up Find in Files (`⌘⇧F` on Mac OSX | none in curses) and -prompts for a directory to search. A new buffer lists the search results. -Double-clicking a search result jumps to it in the file, as do the the -`Ctrl+Alt+G` and `Ctrl+Alt+Shift+G` (`^⌘G` and `^⌘⇧G` | none) key bindings. -Textadept does not support replacing in files directly. You must "Find in Files" -first, and then "Replace All" for each file containing a result. The "Match -Case", "Whole Word", and "Lua pattern" flags still apply. - -_Warning_: currently, the [find API][] provides the only means to specify a -file-type filter. While the default filter excludes many common binary files -and version control folders from searches, Find in Files could still scan -unrecognized binary files or large, unwanted sub-directories. Searches also -block Textadept from receiving additional input, making the interface -temporarily unresponsive. Searching large directories or projects can be very -time consuming and frustrating, so you may prefer to use a specialized, external -tool such as [ack][]. - -![Find in Files](images/findinfiles.png) - -[find API]: api/ui.find.html#FILTER -[ack]: http://betterthangrep.com/ - -### Incremental Find - -Start an incremental search by pressing `Ctrl+Alt+F` (`^⌘F` on Mac OSX | `M-^F` -in curses). Incremental search searches the buffer as you type, but only -recognizes the "Match Case" find option. Pressing `Esc` (`⎋` | `Esc`) stops the -search. - -## Source Code Editing - -Being a programmer's editor, Textadept excels at editing source code. It -understands the syntax and structure of more than 90 different programming -languages and recognizes hundreds of file types. Textadept uses this knowledge -to make viewing and editing code faster and easier. It can also compile and run -simple source files. - -### Lexers - -Upon opening a file, Textadept attempts to identify the programming language -associated with it and set a "lexer" to highlight syntactic elements of the -code. Pressing `Ctrl+Shift+L` (`⌘⇧L` on Mac OSX | `M-S-L` in curses) and -selecting a lexer from the list manually sets the lexer instead. Your -[file type preferences][] customize how Textadept recognizes files. - -Occasionally while you edit, lexers may lose track of their context and -highlight syntax incorrectly. Pressing `F5` triggers a full redraw. - -[file type preferences]: 08_Preferences.html#File.Types - -### Code Folding - -Some lexers support "code folding", the act of temporarily hiding blocks of 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. - -![Folding](images/folding.png) - -### Word Highlight - -To highlight all occurrences of a given word, such as a variable name, put the -caret over the word and press `Ctrl+Alt+Shift+H` (`⌘⇧H` on Mac OSX | N/A in -curses). This feature also works for plain text. - -![Word Highlight](images/wordhighlight.png) - -### Autocompletion and Documentation - -Textadept has the capability to autocomplete symbols for programming languages -and display API documentation. Pressing `Ctrl+Space` (`⌥⎋` on Mac OSX | `^Space` -in curses) completes the current symbol and `Ctrl+H` (`^H` | `M-H` or `M-S-H`) -shows any known documentation on the current symbol. Note: In order for these -features to work, the language you are working with must have an -[autocompleter][] and [API file(s)][], respectively. [Language modules][] -usually [define these][]. Most of the [official][] Textadept language modules -support autocompletion and documentation. - -![Autocomplete Lua](images/adeptsense_lua.png) -     -![Autocomplete Lua String](images/adeptsense_string.png) - -![Documentation](images/adeptsense_doc.png) - -[Language modules]: 07_Modules.html#Language.Modules -[autocompleter]: api/textadept.editing.html#autocompleters -[API file(s)]: api/textadept.editing.html#api_files -[define these]: api/_M.html#Autocompletion.and.Documentation -[official]: http://foicica.com/hg - -### Snippets - -Snippets are essentially pieces of text inserted into source code or plain text. -However, snippets are not bound to static text. They can be dynamic templates -which contain placeholders for further user input, can mirror or transform those -user inputs, and/or can execute arbitrary code. Snippets are useful for rapidly -constructing blocks of code such as control structures, method calls, and -function declarations. Press `Ctrl+K` (`⌥⇥` on Mac OSX | `M-K` in curses) for a -list of available snippets. A snippet consists of a trigger word and snippet -text. Instead of manually selecting a snippet to insert, type its trigger word -followed by the `Tab` (`⇥` | `Tab`) key. Subsequent presses of `Tab` (`⇥` | -`Tab`) cause the caret to enter placeholders in sequential order, `Shift+Tab` -(`⇧⇥` | `S-Tab`) goes back to the previous placeholder, and `Ctrl+Shift+K` -(`⌥⇧⇥` | `M-S-K`) cancels the current snippet. Textadept supports nested -snippets, snippets inserted from within another snippet. Language modules -usually define their [own set][] of snippets, but your [snippet preferences][] -can define some too. - -![Snippet](images/snippet.png) -     -![Snippet Expanded](images/snippet2.png) - -[own set]: api/_M.html#Snippets -[snippet preferences]: 08_Preferences.html#Snippets - -### Toggle Comments - -Pressing `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in curses) comments or uncomments the -code on the selected lines. Selecting any part of a line renders the entire line -eligible for commenting or uncommenting. - -### Compile, Run, and Build - -Textadept knows most of the commands that compile and/or run code in source -files. It can also sometimes detect your project's build file and run that. -Pressing `Ctrl+Shift+R` (`⌘⇧R` on Mac OSX | `M-^R` in curses) executes the -command for compiling code in the current file, `Ctrl+R` (`⌘R` | `^R`) executes -the command for running code, and `Ctrl+Shift+B` (`⌘⇧B` on Mac OSX | `M-^B` in -curses) executes the command for building a project. `Ctrl+Shift+X` (`⌘⇧X` | -`N/A`) stops the currently running process. A new buffer shows the output from -the command and marks any recognized warnings and errors. Pressing `Ctrl+Alt+E` -(`^⌘E` | `M-X`) attempts to jump to the source of the next recognized warning or -error and `Ctrl+Alt+Shift+E` (`^⌘⇧E` | `M-S-X`) attempts to jump to the previous -one. Double-clicking on warnings and errors also jumps to their sources. If -Textadept does not know the correct commands for compiling and/or running your -language's source code, if it does not know how to build your project, or if it -does not detect warning or error messages properly, you can [make changes][] in -your [user-init file][]. - -![Runtime Error](images/runerror.png) - -[make changes]: api/_M.html#Compile.and.Run -[user-init file]: 08_Preferences.html#User.Init diff --git a/doc/07_Modules.md b/doc/07_Modules.md deleted file mode 100644 index 3f929ec9..00000000 --- a/doc/07_Modules.md +++ /dev/null @@ -1,81 +0,0 @@ -# Modules - -Most of Textadept's functionality comes from Lua modules loaded on startup. An -example is the [textadept module][] which implements most of Textadept's -functionality (find & replace, key bindings, menus, snippets, etc.) See the -[preferences][] page for instructions on how to load your own modules on -startup. - -Textadept also recognizes a special kind of module: a language module. Language -modules provide functionality specific to their respective programming -languages. - -[textadept module]: api/textadept.html -[preferences]: 08_Preferences.html#Loading.Modules - -## Language Modules - -Language modules have a scope limited to a single programming language. The -module's name matches the language's lexer in the *lexers/* directory. Textadept -automatically loads the module when editing source code in that particular -language. In addition to the source code editing features discussed previously, -these kinds of modules typically also define indentation settings, custom key -bindings, and perhaps a custom context menu. The manual discusses these features -below. - -### Buffer Properties - -Some programming languages have style guidelines for indentation and/or line -endings which differ from Textadept's defaults. In this case, language modules -[set][] these preferences. You can do so manually with your -[language module preferences][]. - -[set]: api/_M.html#Buffer.Properties -[language module preferences]: 08_Preferences.html#Language - -### Key Bindings - -Most language modules assign a set of key bindings to [custom commands][]. The -module's [LuaDoc][] or code lists which key bindings map to which commands. The -`Ctrl+L` (`⌘L` on Mac OSX | `M-L` in curses) key chain prefix typically houses -them. - -[custom commands]: api/_M.html#Commands -[LuaDoc]: api/index.html - -### Context Menu - -Some language modules add extra actions to the context menu. Right-click inside -the view to bring up this menu. - -## Getting Modules - -Textadept has a set of officially supported language modules available as a -separate download from the Textadept downloads page with their sources hosted -[here][]. To upgrade to the most recent version of a module, either use -[Mercurial][] (run `hg pull` and then `hg update` on or from within the module) -or download a zipped version from the module's repository homepage and overwrite -the existing one. - -For now, the [wiki][] hosts third-party, user-created modules. - -[here]: http://foicica.com/hg -[Mercurial]: http://mercurial.selenic.com -[wiki]: http://foicica.com/wiki/textadept - -## Installing Modules - -If you do not have write permissions in Textadept's installed location, place -the module in your *~/.textadept/modules/* folder and replace all instances of -`_HOME` with `_USERHOME` in the module's *init.lua*. Putting all custom or -user-created modules in your *~/.textadept/modules/* directory prevents the -possibility of overwriting them when you update Textadept. Also, modules in that -directory override any modules in Textadept's *modules/* directory. This means -that if you have your own *lua* module, Textadept loads that one instead of its -own. - -## Developing Modules - -See the [module LuaDoc][]. - -[module LuaDoc]: api/_M.html diff --git a/doc/08_Preferences.md b/doc/08_Preferences.md deleted file mode 100644 index 80fe37ed..00000000 --- a/doc/08_Preferences.md +++ /dev/null @@ -1,192 +0,0 @@ -# Preferences - -At this point the manual assumes you are at least familiar with the basics of -[Lua][]. You do not have to know a lot of the language to configure Textadept. - -[Lua]: http://www.lua.org - -## User Init - -Textadept executes a *~/.textadept/init.lua*, your user-init file, on startup. -If this file does not exist, Textadept creates it for you. This file allows you -to indicate what you want Textadept to do when the application starts. Examples -include changing the settings of existing modules, loading new modules, and -running arbitrary Lua code. - -### Modules - -Try to refrain from modifying the default modules that come with Textadept, even -if you just want to change an option in a generic module, modify the buffer -settings for a language module, edit file types, or add a small bit of custom -code. Upgrading Textadept to a new version may overwrite those changes. Instead -you have two options: load your own module instead of the default one, or run -your custom module code after the default module loads. For the most part, use -the second option because it is simpler and more compatible with future -releases. The manual discusses both options below in the context of generic and -language modules. - -#### Generic - -Many of Textadept's generic modules have configurable settings changeable from -*~/.textadept/init.lua* after Textadept loads the module. The module's -[LuaDoc][] lists these settings. For example, to disable character autopairing -with typeover and strip trailing whitespace on save, add the -following to your *~/.textadept/init.lua*: - - textadept.editing.AUTOPAIR = false - textadept.editing.TYPEOVER_CHARS = false - textadept.editing.STRIP_TRAILING_SPACES = true - -To always hide the tab bar: - - ui.tabs = false - -Now suppose you want to load all of Textadept's default modules except for the -menu. You cannot do this after-the-fact from *~/.textadept/init.lua*. Instead -you need Textadept to load your own module rather than the default one. Copy the -`textadept` module's *init.lua* (located in the *modules/textadept/* directory) -to *~/.textadept/modules/textadept/* and change - - M.menu = require 'textadept.menu' - -to - - --M.menu = require 'textadept.menu' - -Now when Textadept looks for *modules/textadept/init.lua*, it loads yours in -place of its own, thus loading everything but the menu. If instead you want to -completely change the menu structure, first create a new *menu.lua* and then put -it in *~/.textadept/modules/textadept/*. Textadept now loads your *menu.lua* -rather than its own. - -[LuaDoc]: api/index.html - -#### Language - -Similar to generic modules, putting your own language module in -*~/.textadept/modules/* causes Textadept to load that module for editing the -language's code instead of the default one in *modules/* (if the latter exists). -For example, copying the default Lua language module from *modules/lua/* to -*~/.textadept/modules/* results in Textadept loading that module for editing Lua -code in place of its own. However, if you make custom changes to that module and -upgrade Textadept later, the module may no longer be compatible. Rather than -potentially wasting time merging changes, run custom code independent of a -module in the module's *post_init.lua* file. In this case, instead of copying -the `lua` module and creating an `events.LEXER_LOADED` event handler to use -tabs, simply put the event handler in *~/.textadept/modules/lua/post_init.lua*: - - events.connect(events.LEXER_LOADED, function(lang) - if lang == 'lua' then buffer.use_tabs = true end - end) - -Similarly, use *post_init.lua* to change the module's [compile and run][] -commands, load more Autocompletion tags, and add additional -[key bindings](#Key.Bindings) and [snippets](#Snippets) (instead of in -*~/.textadept/init.lua*). For example: - - textadept.run.run_commands.lua = 'lua5.2' - _M.lua.tags[#_M.lua.tags + 1] = '/path/to/my/projects/tags' - keys.lua['c\n'] = function() - buffer:line_end() buffer:add_text('end') buffer:new_line() - end - snippets.lua['ver'] = '%<_VERSION>' - -[compile and run]: 07_Modules.html#Compile.and.Run - -### Loading Modules - -After creating or downloading a generic module called `foo` that you want to -load along with the default modules, simply add the following to your -*~/.textadept/init.lua*: - - foo = require('foo') - -Textadept automatically loads language modules when opening a source file of -that language, so simply installing the language module is sufficient. - -### Key Bindings - -For simple changes to key bindings, *~/.textadept/init.lua* is a good place to -put them. For example, maybe you want `Ctrl+Shift+C` to create a new buffer -instead of `Ctrl+N`: - - keys.cC = buffer.new - keys.cn = nil - -If you plan on redefining most key bindings, copy or create a new *keys.lua* and -put it in *~/.textadept/modules/textadept/* to get Textadept to load your set -instead of its own. Learn more about key bindings and how to define them in the -[key bindings LuaDoc][]. - -[key bindings LuaDoc]: api/keys.html - -### Snippets - -Define your own global snippets in *~/.textadept/init.lua*, such as: - - snippets['file'] = '%' - snippets['path'] = "%<(buffer.filename or ''):match('^.+[/\\]')>" - -So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX | `Tab` in -curses) inserts the snippet, regardless of the current programming language. -Learn more about snippet syntax in the [snippets LuaDoc][]. - -[snippets LuaDoc]: api/textadept.snippets.html - -### File Types - -Textadept recognizes a wide range of programming language files either by file -extension, by a keyword in the shebang ("#!/path/to/exe") line, or by a -[Lua pattern][] that matches the text of the first line. The editor does this by -consulting a set of tables in [`textadept.file_types`][] that are modifiable -from *~/.textadept/init.lua*. For example: - - -- Recognize .luadoc files as Lua code. - textadept.file_types.extensions.luadoc = 'lua' - -- Change .html files to be recognized as XML files. - textadept.file_types.extensions.html = 'xml' - -- Recognize a shebang line like "#!/usr/bin/zsh" as shell code. - textadept.file_types.shebangs.zsh = 'bash' - -[Lua pattern]: 14_Appendix.html#Lua.Patterns -[`textadept.file_types`]: api/textadept.file_types.html - -## Buffer Properties - -Since Textadept runs *~/.textadept/init.lua* only once on startup, it is not the -appropriate place to set per-buffer properties (like indentation size) or -view-related properties (like the behaviors for scrolling and autocompletion). -If you do set such properties in *~/.textadept/init.lua*, those settings only -apply to the first buffer and view -- subsequent buffers and split views will -not inherit those settings. Instead, put your settings in a -*~/.textadept/properties.lua* file which runs after creating a new buffer or -split view. Any settings there override Textadept's default *properties.lua* -settings. For example, to use tabs rather than spaces and have a tab size of 4 -spaces by default, your *~/.textadept/properties.lua* would contain: - - buffer.use_tabs = true - buffer.tab_width = 4 - -(Remember that in order to have per-filetype properties, you need to have a -[language module][].) - -Textadept's *properties.lua* is a good "quick reference" for configurable -properties. It also has many commented out properties that you can copy to your -*~/.textadept/properties.lua* and uncomment to turn on or change the value of. -You can view a property's documentation by pressing `Ctrl+H` (`^H` on Mac OSX | -`M-H` or `M-S-H` in curses) or by reading the [LuaDoc][]. - -[language module]: 07_Modules.html#Buffer.Properties -[LuaDoc]: api/buffer.html - -## Locale - -Textadept attempts to auto-detect your locale settings using the "$LANG" -environment variable, falling back on the English locale. To set the locale -manually, copy the desired locale file from the *core/locales/* folder to -*~/.textadept/locale.conf*. If Textadept does not support your language yet, -please translate the English messages in *core/locale.conf* to your language and -send the modified *locale.conf* file to [me][]. I will include it in a future -release. - -[me]: README.html#Contact diff --git a/doc/09_Themes.md b/doc/09_Themes.md deleted file mode 100644 index 95611798..00000000 --- a/doc/09_Themes.md +++ /dev/null @@ -1,103 +0,0 @@ -# Themes - -Themes customize Textadept's look and feel. The editor's built-in themes are -"light", "dark", and "term". The GUI version uses "light" as its default and the -terminal version uses "term". - - - -![Light Theme](images/lighttheme.png) -   -![Dark Theme](images/darktheme.png) -   -![Term Theme](images/termtheme.png) - -Each theme is a single Lua file. It contains color and style definitions for -displaying syntactic elements like comments, strings, and keywords in -programming language source files. These [definitions][] apply universally to -all programming language elements, resulting in a single, unified theme. Themes -also set view-related editor properties like caret and selection colors. - -Note: The only colors that the terminal version of Textadept recognizes are the -standard black, red, green, yellow, blue, magenta, cyan, white, and bold -variants of those colors. Your terminal emulator's settings determine how to -display these standard colors. - -[definitions]: api/lexer.html#Styles.and.Styling - -## Setting Themes - -Override the default theme in your [*~/.textadept/init.lua*][] using the -[`ui.set_theme()`][] function. For example: - - ui.set_theme(not CURSES and 'dark' or 'custom_term') - -Either restart Textadept for changes to take effect or type [`reset()`][] in the -[command entry][]. - -[*~/.textadept/init.lua*]: 08_Preferences.html#User.Init -[`ui.set_theme()`]: api/ui.html#set_theme -[`reset()`]: api/_G.html#reset -[command entry]: 10_Advanced.html#Command.Entry - -## Customizing Themes - -Like with modules, try to refrain from editing Textadept's default themes. -Instead, put custom or downloaded themes in your *~/.textadept/themes/* -directory. Doing this not only prevents you from overwriting your themes when -you update Textadept, but causes the editor to load your themes instead of the -default ones in *themes/*. For example, having your own *light.lua* theme -results in Textadept loading that theme in place of its own. - -There are two ways to go about customizing themes. You can create a new one from -scratch or tweak an existing one. Creating a new one is straightforward -- all -you need to do is define a set of colors and a set of styles. Just follow the -example of existing themes. If instead you want to use an existing theme like -"light" but only change the font face and font size, you have two options: call -[`ui.set_theme()`][] from your *~/.textadept/init.lua* with additional -parameters, or create an abbreviated *~/.textadept/themes/light.lua* using Lua's -`dofile()` function. For example: - - -- File *~/.textadept/init.lua* - ui.set_theme('light', {font = 'Monospace', fontsize = 12}) - - -- File *~/.textadept/themes/light.lua* - dofile(_HOME..'/themes/light.lua') - buffer.property['font'] = 'Monospace' - buffer.property['fontsize'] = 12 - -Either one loads Textadept's "light" theme, but applies your font preferences. -The same techniques work for tweaking individual theme colors and/or styles, but -managing more changes is probably easier with the latter. - -[`ui.set_theme()`]: api/ui.html#set_theme - -### Language - -Textadept also allows you to customize themes per-language through the -`events.LEXER_LOADED` event. For example, changing the color of functions in -Java from orange to black in the "light" theme looks like this: - - events.connect(events.LEXER_LOADED, function(lang) - if lang == 'java' then - buffer.property['style.function'] = 'fore:%(color.light_black)' - end - end) - -## GUI Theme - -There is no way to theme GUI controls like text fields and buttons from within -Textadept. Instead, use [GTK+ Resource files][]. The "GtkWindow" name is -"textadept". For example, style all text fields with a "textadept-entry-style" -like this: - - widget "textadept*GtkEntry*" style "textadept-entry-style" - -[GTK+ Resource files]: http://library.gnome.org/devel/gtk/stable/gtk-Resource-Files.html - -## Getting Themes - -For now, the [wiki][] hosts third-party, user-created themes. The classic -"dark", "light", and "scite" themes prior to version 4.3 are there too. - -[wiki]: http://foicica.com/wiki/textadept diff --git a/doc/10_Advanced.md b/doc/10_Advanced.md deleted file mode 100644 index 415be4e2..00000000 --- a/doc/10_Advanced.md +++ /dev/null @@ -1,89 +0,0 @@ -# Advanced - -## Command Entry - -The command entry grants access to Textadept's Lua state. Press `Ctrl+E` (`⌘E` -on Mac OSX | `M-C` in curses) to display the entry. It is useful for debugging, -inspecting, and entering `buffer` or `view` commands. If you try to cause -instability in Textadept's Lua state, you will probably succeed so be careful. -The [Lua API][] lists available commands. The command entry provides abbreviated -commands for [`buffer`][], [`view`][] and [`ui`][]: you may reduce the -`buffer:append_text('foo')` command to `append_text('foo')`. Therefore, use -`_G.print()` for Lua's `print()` since `print()` expands to [`ui.print()`][]. -These commands are runnable on startup using the `-e` and `--execute` command -line switches. - -![Command Entry](images/commandentry.png) - -[Lua API]: api/index.html -[`buffer`]: api/buffer.html -[`view`]: api/view.html -[`ui`]: api/ui.html -[`ui.print()`]: api/ui.html#print - -### Tab Completion - -The command entry also provides tab-completion for functions, variables, tables, -etc. Press the `Tab` (`⇥` on Mac OSX | `Tab` in curses) key to display a list of -available completions. Use the arrow keys to make a selection and press `Enter` -(`↩` | `Enter`) to insert it. - -![Command Completion](images/commandentrycompletion.png) - -### Extending - -Executing Lua commands is just one of the many tools the command entry functions -as. For example, *modules/textadept/find.lua* and *modules/textadept/keys.lua* -extend it to implement [incremental search][]. - -[incremental search]: api/ui.find.html#find_incremental - -## Command Selection - -If you did not disable the menu in your [preferences][], then pressing -`Ctrl+Shift+E` (`⌘⇧E` on Mac OSX | `M-S-C` in curses) brings up the command -selection dialog. Typing part of any command filters the list, with spaces being -wildcards. This is an easy way to run commands without navigating the menus, -using the mouse, or remembering key bindings. It is also useful for looking up -particular key bindings quickly. Note: the key bindings in the dialog do not -look like those in the menu. Textadept uses this different notation internally. -Learn more about it in the [keys LuaDoc][]. - -[preferences]: 08_Preferences.html#User.Init -[keys LuaDoc]: api/keys.html - -## Shell Commands and Filtering Text - -Sometimes using an existing shell command to manipulate text is easier than -using the command entry. An example would be sorting all text in a buffer (or a -selection). One way to do this from the command entry is: - - ls={}; for l in buffer:get_text():gmatch('[^\n]+') do ls[#ls+1]=l end; - table.sort(ls); buffer:set_text(table.concat(ls, '\n')) - -A simpler way is pressing `Ctrl+|` (`⌘|` on Mac OSX | `^\` in curses), entering -the shell command `sort`, and pressing `Enter` (`↩` | `Enter`). - -This feature determines the standard input (stdin) for shell commands as -follows: - -* If text is selected and spans multiple lines, all text on the lines containing - the selection is used. However, if the end of the selection is at the - beginning of a line, only the EOL (end of line) characters from the previous - line are included as input. The rest of the line is excluded. -* If text is selected and spans a single line, only the selected text is used. -* If no text is selected, the entire buffer is used. - -The standard output (stdout) of the command replaces the input text. - -## Remote Control - -Since Textadept executes arbitrary Lua code passed via the `-e` and `--execute` -command line switches, a side-effect of [single instance][] functionality on the -platforms that support it is that you can remotely control the original -instance. For example: - - ta ~/.textadept/init.lua & - ta -e "events.emit(events.FIND, 'require')" - -[single instance]: 02_Installation.html#Single.Instance diff --git a/doc/11_Scripting.md b/doc/11_Scripting.md deleted file mode 100644 index 5e8579f6..00000000 --- a/doc/11_Scripting.md +++ /dev/null @@ -1,103 +0,0 @@ -# Scripting - -Since Textadept is entirely scriptable with Lua, the editor has superb support -for editing Lua code. Textadept provides syntax autocompletion and documentation -for the Lua and Textadept APIs. The [`lua` module][] also has more tools for -working with Lua code. - -![ta Autocompletion](images/adeptsense_ta.png) -     -![ta Documentation](images/adeptsense_tadoc.png) - -[`lua` module]: api/_M.lua.html - -## LuaDoc and Examples - -Textadept's API is heavily documented. The [API documentation][] is the ultimate -resource on scripting Textadept. There are of course abundant scripting examples -since the editor's internals consist primarily of Lua. - -[API documentation]: api/index.html - -### Generating LuaDoc - -Generate Textadept-like API documentation for your own modules using the -*doc/markdowndoc.lua* [LuaDoc][] module (you must have [Discount][] installed): - - luadoc -d . [-t template_dir] --doclet _HOME/doc/markdowndoc [module(s)] - -where `_HOME` is the path where you installed Textadept and `template_dir` is an -optional template directory that contains two Markdown files: *.header.md* and -*.footer.md*. (See *doc/.header.md* and *doc/.footer.md* for examples.) LuaDoc -creates an *api/* directory in the current directory that contains the generated -API documentation HTML files. - -[LuaDoc]: http://keplerproject.github.com/luadoc/ -[Discount]: http://www.pell.portland.or.us/~orc/Code/discount/ - -## Lua Configuration - -Textadept contains its own copy of [Lua 5.2][] which has the same configuration -(*luaconf.h*) as vanilla Lua with the following exceptions: - -* `TA_LUA_PATH` and `TA_LUA_CPATH` replace the `LUA_PATH` and `LUA_CPATH` - environment variables. -* `LUA_ROOT` is "/usr/" in Linux systems instead of "/usr/local/". -* `LUA_PATH` and `LUA_CPATH` do not have "./?.lua" and "./?.so" in them. -* No Lua 5.1 compatibility flags are set. - -[Lua 5.2]: http://www.lua.org/manual/5.2/ - -### LuaJIT - -Even though Textadept runs with [LuaJIT][], LuaJIT does not fully support -Lua 5.2. Therefore, try to write your modules and scripts to be compatible with -both versions. For the most part, LuaJIT only lacks Lua 5.2's new `_ENV`. - -[LuaJIT]: http://luajit.org - -## Scintilla - -Textadept uses the [Scintilla][] editing component. The [buffer][] part of -Textadept's API emulates the [Scintilla API][] so porting any C/C++ Scintilla -calls to Lua should not be difficult. - -[Scintilla]: http://scintilla.org -[buffer]: api/buffer.html -[Scintilla API]: http://scintilla.org/ScintillaDoc.html - -## Textadept Structure - -Because Textadept consists mainly of Lua, its Lua scripts have to be stored in -an organized folder structure. - -### Core - -The *core/* directory contains Textadept's core Lua modules. These modules are -essential for the application to run. They provide Textadept's Lua to C -interface, event structure, file interactions, and localization. - -### Lexers - -Lexer modules analyze source code for syntax highlighting. *lexers/* houses -them. - -### Modules - -*modules/* contains generic and language modules for editing text and source -code. - -### Themes - -*themes/* has built-in themes that customize the look and feel of Textadept. - -### User - -The *~/.textadept/* folder houses your preferences, Lua modules, themes, and -user-data. This folder may contain *lexers/*, *modules/*, and *themes/* -sub-directories. - -### GTK+ - -GTK+ uses the *etc/*, *lib/*, and *share/* directories, which only appear in the -Win32 and Mac OSX packages. diff --git a/doc/12_Compiling.md b/doc/12_Compiling.md deleted file mode 100644 index 8cac40c7..00000000 --- a/doc/12_Compiling.md +++ /dev/null @@ -1,190 +0,0 @@ -# Compiling - -## Requirements - -Unfortunately, the requirements for building Textadept are not quite as minimal -as running it. - -### Linux and BSD - -First, Linux and BSD systems need the [GNU C compiler][] (*gcc*) and -[GNU Make][] (*make*). BSD users additionally need to have [libiconv][] -installed. These should be available for your distribution through a package -manager. For example, Ubuntu includes these tools in the "build-essential" -package. - -Next, the GUI version of Textadept requires the GTK+ development libraries. -Again, your package manager should allow you to install them. Debian-based Linux -distributions like Ubuntu typically call the package "libgtk2.0-dev". Otherwise, -compile and install GTK+ from the [GTK+ website][]. - -The optional terminal version of Textadept depends on the development library -for a curses implementation like ncurses. Similarly, your package manager should -provide one. Debian-based Linux distributions like Ubuntu typically call the -ncurses package "libncurses5-dev". Otherwise, compile and install ncurses from -the [ncurses website][]. Note: you need the wide-character development version -of ncurses installed, which handles multibyte sequences. (Therefore, Debian -users _also_ need "libncursesw5-dev".) - -[GNU C compiler]: http://gcc.gnu.org -[GNU Make]: http://www.gnu.org/software/make/ -[libiconv]: http://www.gnu.org/software/libiconv/ -[GTK+ website]: http://www.gtk.org/download/linux.php -[ncurses website]: http://invisible-island.net/ncurses/#download_ncurses - -### Windows - -Compiling Textadept on Windows is no longer supported. The preferred way to -compile for Windows is cross-compiling from Linux. To do so, you need [MinGW][] -with the Windows header files. Your package manager should offer them. - -Note: compiling on Windows requires a C compiler that supports the C99 standard, -the [GTK+ for Windows bundle][] (2.24 is recommended), and -[libiconv for Windows][] (the "Developer files" and "Binaries" zip files). The -terminal (pdcurses) version requires my [win32curses bundle][] instead of GTK+ -and libiconv. - -[MinGW]: http://mingw.org -[GTK+ for Windows bundle]: http://www.gtk.org/download/win32.php -[libiconv for Windows]: http://gnuwin32.sourceforge.net/packages/libiconv.htm -[win32curses bundle]: download/win32curses.zip - -### Mac OSX - -Compiling Textadept on Mac OSX is no longer supported. The preferred way is -cross-compiling from Linux. To do so, you need the [Apple Cross-compiler][] -binaries. - -[Apple Cross-compiler]: https://launchpad.net/~flosoft/+archive/cross-apple - -## Compiling - -### Linux and BSD - -For Linux and BSD systems, simply run `make deps` in the *src/* directory to -prepare the build environment followed by `make` to build the *textadept* and -*textadeptjit* executables in the root directory. Make a symlink from them to -*/usr/bin/* or elsewhere in your `PATH`. - -Similarly, `make curses` builds *textadept-curses* and *textadeptjit-curses*. - -Note: you may have to run - - make CFLAGS="-I/usr/local/include" \ - CXXFLAGS="-I/usr/local/include -L/usr/local/lib" - -if the prefix where any dependencies are installed is */usr/local/* and your -compiler flags do not include them by default. - -#### Installing - -Textadept is self-contained, meaning you do not have to install it, and runs -from its current location. Should you choose to install Textadept like a normal -Linux application, run `make deps` and then the usual `make` and `make install` -or `sudo make install` commands depending on your privileges. The default prefix -is */usr/local* but setting `DESTDIR` (e.g. -`make install DESTDIR=/prefix/to/install/to`) changes it. - -Similarly, `make curses` and `make curses install` installs the curses version. - -### Cross Compiling for Windows - -When cross-compiling from within Linux, first make a note of your MinGW -compiler names. You may have to either modify the `CROSS` variable in the -"win32" block of *src/Makefile* or append something like "CROSS=i486-mingw32-" -when running `make`. After considering your MinGW compiler names, run -`make win32-deps` or `make CROSS=i486-mingw32- win32-deps` to prepare the build -environment followed by `make win32` or `make CROSS=i486-mingw32- win32` to -build *../textadept.exe* and *../textadeptjit.exe*. Finally, copy the dll files -from *src/win32gtk/bin/* to the directory containing the Textadept executables. - -Similarly for the terminal version, run `make win32-curses` or its variant as -suggested above to build *../textadept-curses.exe* and -*../textadeptjit-curses.exe*. - -Please note the build process produces a *lua51.dll* for _only_ -*textadeptjit.exe* and *textadeptjit-curses.exe* because limitations on external -Lua library loading do not allow statically linking LuaJIT to Textadept. - -### Cross Compiling for Mac OSX - -When cross-compiling from within Linux, run `make osx-deps` to prepare the build -environment followed by `make osx` to build *../textadept.osx* and -*../textadeptjit.osx*. - -Similarly, `make osx-curses` builds *../textadept-curses.osx* and -*../textadeptjit-curses.osx*. - -Build a new *Textadept.app* with `make osx-app`. - -#### Compiling on OSX (Legacy) - -Textadept requires [XCode][] as well as [jhbuild][] (for GTK+). After building -"meta-gtk-osx-bootstrap" and "meta-gtk-osx-core", build "meta-gtk-osx-themes". -Note that the entire compiling process can easily take 30 minutes or more and -ultimately consume nearly 1GB of disk space. - -After using *jhbuild*, GTK+ is in *~/gtk/* so make a symlink from *~/gtk/inst* -to *src/gtkosx* in Textadept. Then open *src/Makefile* and uncomment the -"Darwin" block. Finally, run `make osx` to build *../textadept.osx* and -*../textadeptjit.osx*. - -Note: to build a GTK+ for OSX bundle, run the following from the *src/* -directory before zipping up *gtkosx/include/* and *gtkosx/lib/*: - - sed -i -e 's|libdir=/Users/username/gtk/inst/lib|libdir=${prefix}/lib|;' \ - gtkosx/lib/pkgconfig/*.pc - -where `username` is your username. - -Compiling the terminal version is not so expensive and requires no additional -libraries. After uncommenting the "Darwin" block mentioned above, simply run -`make osx-curses` to build *../textadept-curses.osx* and -*../textadeptjit-curses.osx*. - -[XCode]: http://developer.apple.com/TOOLS/xcode/ -[jhbuild]: http://sourceforge.net/apps/trac/gtk-osx/wiki/Build - -### Notes on LuaJIT - -[LuaJIT][] is a Just-In-Time Compiler for Lua and can boost the speed of Lua -programs. I have noticed that syntax highlighting can be up to 2 times faster -with LuaJIT than with vanilla Lua. This difference is largely unnoticable on -modern computers and usually only discernable when initially loading large -files. Other than syntax highlighting, LuaJIT offers no real benefit -performance-wise to justify it being Textadept's default runtime. LuaJIT's -[ffi library][], however, appears to be useful for interfacing with external, -non-Lua, libraries. - -[LuaJIT]: http://luajit.org -[ffi library]: http://luajit.org/ext_ffi.html - -### Notes on CDK - -[CDK][] is a library of curses widgets. The terminal version of Textadept -includes a slightly modified, stripped down version of this library. The changes -made to CDK are in *src/cdk.patch* and listed as follows: - -* Excluded the following source files: *alphalist.c*, *calendar.c*, - *cdk_compat.{c,h}*, *cdk_test.h*, *dialog.c*, *{d,f}scale.{c,h}*, - *fslider.{c,h}*, *gen-{scale,slider}.{c,h}*, *get_index.c*, *get_string.c*, - *graph.c*, *histogram.c*, *marquee.c*, *matrix.c*, *popup_dialog.c*, - *radio.c*, *scale.{c,h}*, *slider.{c,h}*, *swindow.c*, *template.c*, - *u{scale,slider}.{c,h}*, *view_{file,info}.c*, and *viewer.c*. -* *cdk.h* does not `#include` "matrix.h", "viewer.h", and any headers labeled - "Generated headers" due to their machine-dependence. It also `#define`s - `boolean` as `CDKboolean` on Windows platforms since the former is already - `typedef`ed. -* *cdk_config.h* no longer defines `HAVE_SETLOCALE` since Textadept handles - locale settings, no longer defines `HAVE_NCURSES_H` and `NCURSES` since - Textadept supports multiple curses implementations (not just ncurses), - conditionally enables `HAVE_GRP_H`, `HAVE_LSTAT`, and `HAVE_PWD_H` definitions - on \*nix platforms since Windows does not have them, and explicitly undefines - `NCURSES_OPAQUE` since newer versions of ncurses on Mac OSX define it. -* *cdk_util.h* `#define`s `Beep` as `CDKBeep` on Windows platforms since Windows - already defines Beep. -* The `baseName` and `dirName` functions in *cdk.c* recognize Window's '\' - directory separator. -* Deactivated the `deleteFileCB` function in *fselect.c*. - -[CDK]: http://invisible-island.net/cdk/ diff --git a/doc/13_Help.md b/doc/13_Help.md deleted file mode 100644 index 8e75fff9..00000000 --- a/doc/13_Help.md +++ /dev/null @@ -1,29 +0,0 @@ -# Help - -## Command Line Parameters - -Passing `-h` or `--help` to Textadept shows a list of available command line -parameters. - -Switch |Arguments|Description --------------------|:-------:|----------- -`-e`, `--execute` | 1 |Run Lua [code][]. -`-f`, `--force` | 0 |Forces [unique instance][]. -`-h`, `--help` | 0 |Shows this. -`-n`, `--nosession`| 0 |No [session][] functionality. -`-s`, `--session` | 1 |Loads [session][] on startup. -`-u`, `--userhome` | 1 |Sets alternate [`_USERHOME`][]. - -Textadept curses does not support the help switch. - -[code]: 10_Advanced.html#Command.Entry -[unique instance]: 02_Installation.html#Single.Instance -[session]: 04_WorkingWithFiles.html#Sessions -[`_USERHOME`]: api/_G.html#_USERHOME - -## Online Help - -Textadept has a [mailing list][] and a [wiki][]. - -[mailing list]: http://foicica.com/lists -[wiki]: http://foicica.com/wiki/textadept diff --git a/doc/14_Appendix.md b/doc/14_Appendix.md deleted file mode 100644 index 7ab00297..00000000 --- a/doc/14_Appendix.md +++ /dev/null @@ -1,691 +0,0 @@ -# Appendix - -## Lua Patterns - -The following is from the [Lua 5.2 Reference Manual][]. - -_Character Class:_ - -A character class is used to represent a set of characters. The following -combinations are allowed in describing a character class: - -* **_`x`_:** (where _x_ is not one of the magic characters `^%()%.[]*+-?`) - represents the character _x_ itself. -* **`.`:** (a dot) represents all characters. -* **`%a`:** represents all letters. -* **`%c`:** represents all control characters. -* **`%d`:** represents all digits. -* **`%g`:** represents all printable characters except space. -* **`%l`:** represents all lowercase letters. -* **`%p`:** represents all punctuation characters. -* **`%s`:** represents all space characters. -* **`%u`:** represents all uppercase letters. -* **`%w`:** represents all alphanumeric characters. -* **`%x`:** represents all hexadecimal digits. -* **`%`_`x`_:** (where _x_ is any non-alphanumeric character) represents the - character _x_. This is the standard way to escape the magic characters. Any - punctuation character (even the non magic) can be preceded by a '`%`' when - used to represent itself in a pattern. -* **`[set]`:** represents the class which is the union of all characters in set. - A range of characters can be specified by separating the end characters of the - range with a '`-`'. All classes `%`_x_ described above can also be used as - components in set. All other characters in set represent themselves. For - example, `[%w_]` (or `[_%w]`) represents all alphanumeric characters plus the - underscore, `[0-7]` represents the octal digits, and `[0-7%l%-]` represents - the octal digits plus the lowercase letters plus the '`-`' character. -

- The interaction between ranges and classes is not defined. Therefore, patterns - like `[%a-z]` or `[a-%%]` have no meaning. -* **`[^set]`:** represents the complement of _set_, where _set_ is interpreted - as above. - -For all classes represented by single letters (`%a`, `%c`, etc.), the -corresponding uppercase letter represents the complement of the class. For -instance, `%S` represents all non-space characters. - -The definitions of letter, space, and other character groups depend on the -current locale. In particular, the class `[a-z]` may not be equivalent to `%l`. - -_Pattern Item:_ - -A _pattern item_ can be - -* a single character class, which matches any single character in the class; -* a single character class followed by '`*`', which matches 0 or more - repetitions of characters in the class. These repetition items will always - match the longest possible sequence; -* a single character class followed by '`+`', which matches 1 or more - repetitions of characters in the class. These repetition items will always - match the longest possible sequence; -* a single character class followed by '`-`', which also matches 0 or more - repetitions of characters in the class. Unlike '`*`', these repetition items - will always match the _shortest_ possible sequence; -* a single character class followed by '`?`', which matches 0 or 1 occurrence of - a character in the class; -* `%n`, for _n_ between 1 and 9; such item matches a substring equal to the - _n_-th captured string (see below); -* `%bxy`, where _x_ and _y_ are two distinct characters; such item matches - strings that start with _x_, end with _y_, and where the _x_ and _y_ are - balanced. This means that, if one reads the string from left to right, - counting +_1_ for an _x_ and -_1_ for a _y_, the ending _y_ is the first _y_ - where the count reaches 0. For instance, the item `%b()` matches expressions - with balanced parentheses. -* `%f[set]`, a _frontier pattern_; such item matches an empty string at any - position such that the next character belongs to _set_ and the previous - character does not belong to _set_. The set _set_ is interpreted as previously - described. The beginning and the end of the subject are handled as if they - were the character `'\0'`. - -_Pattern:_ - -A _pattern_ is a sequence of pattern items. A '`^`' at the beginning of a -pattern anchors the match at the beginning of the subject string. A '`$`' at the -end of a pattern anchors the match at the end of the subject string. At other -positions, '`^`' and '`$`' have no special meaning and represent themselves. - -_Captures:_ - -A pattern can contain sub-patterns enclosed in parentheses; they describe -_captures_. When a match succeeds, the substrings of the subject string that -match captures are stored (_captured_) for future use. Captures are numbered -according to their left parentheses. For instance, in the pattern -`"(a*(.)%w(%s*))"`, the part of the string matching `"a*(.)%w(%s*)"` is stored -as the first capture (and therefore has number 1); the character matching "`.`" -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 - -## Curses Compatibility - -Textadept 5.5 beta introduced a curses version that is capable of running in a -terminal emulator. However, it lacks some GUI features due to curses' -non-existant graphics capabilities: - -* No alpha values or transparency. -* No images in autocompletion lists. Instead, autocompletion lists show the - first character in the string passed to [`buffer:register_image()`][]. -* No buffered or two-phase drawing. -* No arrows on call tips. -* Carets cannot have a period, line style, or width. -* Edge lines may be obscured by text. -* Extra line ascent or descent renders improperly. -* No fold lines. -* No indentation guides. -* No indicators other than `INDIC_ROUNDBOX` and `INDIC_STRAIGHTBOX`, although - neither has translucent drawing and `INDIC_ROUNDBOX` does not have rounded - corners. -* When scrolling to the right, long lines overwrite margins. -* No marker symbols other than `MARK_CHARACTER`. -* No mouse interactions, cursor types, or hotspots. -* Only up to 16 colors recognized, regardless of how many colors the terminal - supports. They are: black (`0x000000`), red (`0x800000`), green (`0x008000`), - yellow (`0x808000`), blue (`0x000080`), magenta (`0x800080`), cyan - (`0x008080`), white (`0xC0C0C0`), light black (`0x404040`), light red - (`0xFF0000`), light green (`0x00FF00`), light yellow (`0xFFFF00`), light blue - (`0x0000FF`), light magenta (`0xFF00FF`), light cyan (`0x00FFFF`), and light - white (`0xFFFFFF`). Even if your terminal uses a different color map, you must - use these color values. Your terminal will remap them automatically. - Unrecognized colors default to white. For some terminals, you may need to set - a lexer style's `bold` attribute to use the light color variant. -* No scroll bars. -* Not all key sequences recognized properly. -* No style settings like font name, font size, or italics. -* No tab character arrows when viewing whitespace. -* No visual wrap flags. -* No X selection, primary or secondary, integration with the clipboard. -* No zoom. - -[`buffer:register_image()`]: api/buffer.html#buffer.register_image - -## Migration Guides - -### Textadept 6 to 7 - -Textadept 7 introduces API changes, a change in module mentality and filename -encodings, and a completely new theme implementation. - -#### API Changes - -Old API |Change |New API -----------------------------------|:------:|------- -**_G** | | -RESETTING |Removed |N/Aa -buffer\_new() |Renamed |\_G.[buffer.new()][] -**_M.textadept** |Renamed |[textadept][] -filter\_through |Removed |N/A -filter\_through.filter\_through() |Renamed |editing.[filter\_through()][] -mime\_types |Renamed |[file\_types][]b -**_M.textadept.bookmark** | | -N/A |New |[goto\_mark()][] -N/A |New |[MARK\_BOOKMARK][] -MARK\_BOOKMARK\_COLOR |Removed |N/Ac -goto\_bookmark |Replaced|goto\_mark() -goto\_next |Replaced|goto\_mark(true) -goto\_prev |Replaced|goto\_mark(false) -**_M.textadept.editing** | | -N/A |New |[INDIC\_BRACEMATCH][] -N/A |New |[INDIC\_HIGHLIGHT][] -INDIC\_HIGHLIGHT\_BACK |Removed |N/Ad -autocomplete\_word(chars, default)|Changed |[autocomplete\_word][](default) -grow\_selection() |Replaced|[select\_enclosed()][] -**_M.textadept.menu** | | -menubar |Removed |N/A -contextmenu |Removed |N/A -**_M.textadept.run** | | -N/A |New |[MARK\_WARNING][] -N/A |New |[MARK\_ERROR][] -MARK\_ERROR\_BACK |Removed |N/Ac -compile\_command |Renamed |[compile\_commands][] -run\_command |Renamed |[run\_commands][] -error\_detail |Renamed |[error\_patterns][]e -**_M.textadept.snapopen** |Removed |N/A -open |Changed |\_G.[io.snapopen()][]f -**_SCINTILLA.constants** | | -SC\_\* |Renamed |Removed "SC\_" prefix. -SC(FIND\|MOD\|VS\|WS) |Renamed |Removed "SC" prefix. -**buffer** | | -check\_global() |Removed | -get\_style\_name(buffer, n) |Renamed |[style\_name][]\[n\] -reload() |Renamed |[io.reload\_file()][] -save() |Renamed |[io.save\_file()][] -save\_as() |Renamed |[io.save\_file\_as()][] -close() |Renamed |[io.close\_buffer()][] -set\_encoding() |Renamed |[io.set\_buffer\_encoding()][] -convert\_eo\_ls() |Renamed |[buffer.convert\_eols()][] -dirty |Replaced|[buffer.modify][] -**events** | | -N/A |New |[INITIALIZED][] -handlers |Removed |N/A -**gui** |Renamed |[ui][] -docstatusbar\_text |Renamed |[bufstatusbar\_text][] -N/A |New |[maximized][] -find.goto\_file\_in\_list() |Renamed |find.[goto\_file\_found()][] -select\_theme |Removed |N/A -N/A |New |[dialogs][] -filteredlist |Removed |N/A -set\_theme(name, ...) |Changed |[set\_theme][](name, table) -**io** | | -try\_encodings |Renamed |[encodings][] -open\_file(string) |Changed |[open\_file][](string or table) -snapopen(string, ...) |Changed |[snapopen][](string or table, ...) -save\_all() |Renamed |[save\_all\_files()][] -close\_all() |Renamed |[close\_all\_buffers()][] - -a`arg` is `nil` when resetting. - -bRemoved *mime_types.conf* files. Interact with Lua tables directly. - -cSet [`buffer.marker_back`][] in [`events.VIEW_NEW`][]. - -dSet [`buffer.indic_fore`][] in [`events.VIEW_NEW`][]. - -eChanged structure too. - -fChanged arguments too. - -[buffer.new()]: api/buffer.html#new -[textadept]: api/textadept.html -[filter\_through()]: api/textadept.editing.html#filter_through -[file\_types]: api/textadept.file_types.html -[goto\_mark()]: api/textadept.bookmarks.html#goto_mark -[MARK\_BOOKMARK]: api/textadept.bookmarks.html#MARK_BOOKMARK -[INDIC\_BRACEMATCH]: api/textadept.editing.html#INDIC_BRACEMATCH -[INDIC\_HIGHLIGHT]: api/textadept.editing.html#INDIC_HIGHLIGHT -[autocomplete\_word]: api/textadept.editing.html#autocomplete_word -[select\_enclosed()]: api/textadept.editing.html#select_enclosed -[MARK\_WARNING]: api/textadept.run.html#MARK_WARNING -[MARK\_ERROR]: api/textadept.run.html#MARK_ERROR -[compile\_commands]: api/textadept.run.html#compile_commands -[run\_commands]: api/textadept.run.html#run_commands -[error\_patterns]: api/textadept.run.html#error_patterns -[io.snapopen()]: api/io.html#snapopen -[style\_name]: api/buffer.html#style_name -[io.reload\_file()]: api/io.html#reload_file -[io.save\_file()]: api/io.html#save_file -[io.save\_file\_as()]: api/io.html#save_file_as -[io.close\_buffer()]: api/io.html#close_buffer -[io.set\_buffer\_encoding()]: api/io.html#set_buffer_encoding -[buffer.convert\_eols()]: api/buffer.html#convert_eols -[buffer.modify]: api/buffer.html#modify -[INITIALIZED]: api/events.html#INITIALIZED -[ui]: api/ui.html -[bufstatusbar\_text]: api/ui.html#bufstatusbar_text -[maximized]: api/ui.html#maximized -[goto\_file\_found()]: api/ui.find.html#goto_file_found -[dialogs]: api/ui.dialogs.html -[set\_theme]: api/ui.html#set_theme -[encodings]: api/io.html#encodings -[open\_file]: api/io.html#open_file -[snapopen]: api/io.html#snapopen -[save\_all\_files()]: api/io.html#save_all_files -[close\_all\_buffers()]: api/io.html#close_all_buffers -[`buffer.marker_back`]: api/buffer.html#marker_back -[`events.VIEW_NEW`]: api/events.html#VIEW_NEW -[`buffer.indic_fore`]: api/buffer.html#indic_fore - -#### Module Mentality - -Prior to Textadept 7, the `_M` table held all loaded modules (regardless of -whether they were generic modules or language modules) and Textadept encouraged -users to load custom modules into `_M` even though Lua has no such restriction. -The `_M` prefix no longer makes much sense for generic modules like -[`textadept`][], so only language modules are automatically loaded into -[`_M`][]. Textadept 7 does not encourage any prefix for custom, generic modules; -the user is free to choose. - -[`textadept`]: api/textadept.html -[`_M`]: api/_M.html - -#### Filename Encodings - -Prior to Textadept 7, `buffer.filename` was encoded in UTF-8 and any functions -that accepted filenames (such as `io.open_file()`) required the filenames to -also be encoded in UTF-8. This is no longer the case in Textadept 7. -`buffer.filename` is encoded in `_CHARSET` and any filenames passed to functions -should also remain encoded in `_CHARSET`. No more superfluous encoding -conversions. You should only convert to and from UTF-8 when displaying or -retrieving displayed filenames from buffers and/or dialogs. - -#### Theme Changes - -You can use the following as a reference for converting your Textadept 6 themes -to Textadept 7: - - -- File *theme/lexer.lua* | -- File *theme.lua* - -- Textadept 6 | -- Textadept 7 - local l = lexer | local buffer = buffer - local color = l.color | local prop = buffer.property - local style = l.style | local prop_int = - | buffer.property_int - | - l.colors = { | - ... | ... - red = color('99', '4D', '4D'), | prop['color.red'] = 0x4D4D99 - yellow = color('99', '99', '4D'), | prop['color.yellow'] = 0x4D9999 - ... | ... - } | - | - l.style_nothing = style{} | prop['style.nothing'] = '' - l.style_class = style{ | prop['style.class'] = - fore = l.colors.yellow | 'fore:%(color.yellow)' - } | ... - ... | prop['style.identifier'] = - l.style_identifier = l.style_nothing | '%(style.nothing)' - | - ... | ... - | - | prop['font'] = 'Monospace' - local font, size = 'Monospace', 10 | prop['fontsize'] = 10 - l.style_default = style{ | prop['style.default'] = - font = font, size = size, | 'font:%(font),'.. - fore = l.colors.light_black | 'size:%(fontsize),'.. - back = l.colors.white | 'fore:%(color.light_black),'.. - } | 'back:%(color.white)' - ... | ... - - -- File *theme/view.lua* | -- Same file *theme.lua*! - | - ... | ... - -- Caret and Selection Styles. | -- Caret and Selection Styles. - buffer:set_sel_fore(true, 0x333333) | buffer:set_sel_fore(true, - | prop_int['color.light_black']) - buffer:set_sel_back(true, 0x999999) | buffer:set_sel_back(true, - | prop_int['color.light_grey']) - --buffer.sel_alpha = | --buffer.sel_alpha = - --buffer.sel_eol_filled = true | - buffer.caret_fore = 0x4D4D4D | buffer.caret_fore = - | prop_int['color.grey_black'] - ... | ... - -Notes: - -1. Textadept 7's themes share its Lua state and set lexer colors and styles - through named buffer properties. -2. Convert colors from "RRGGBB" string format to the "0xBBGGRR" number format - that Textadept's API documentation uses consistently. -3. The only property names that matter are the "style._name_" ones. Other - property names are arbitrary. -4. Instead of using variables, which are evaluated immediately, use "%(key)" - notation, which substitutes the value of property "key" at a later point in - time. This means you do not have to define properties before use. You can - also modify existing properties without redefining the properties that depend - on them. See the [customizing themes][] section for an example. -5. Set view properties related to colors directly in *theme.lua* now instead of - a separate *view.lua*. You may use color properties defined earlier. Try to - refrain from setting properties like `buffer.sel_eol_filled` which belong in - a [*properties.lua*][] file. -6. The separate *buffer.lua* is gone. Use [*properties.lua*][] or a - [language module][]. - -[customizing themes]: 09_Themes.html#Customizing.Themes -[*properties.lua*]: 08_Preferences.html#Buffer.Properties -[language module]: 07_Modules.html#Buffer.Properties - -##### Theme Preference - -Textadept 7 ignores the *~/.textadept/theme* and *~/.textadept/theme_term* files -that specified your preferred Textadept 6 theme. Use *~/.textadept/init.lua* to -[set a preferred theme][] instead. For example, if you had custom GUI and -terminal themes: - - -- File *~/.textadept/init.lua* - ui.set_theme(not CURSES and 'custom' or 'custom_term') - -You may still use absolute paths for themes instead of names. - -[set a preferred theme]: 09_Themes.html#Setting.Themes - -### Textadept 5 to 6 - -Textadept 6 introduces some API changes. These changes affect themes in -particular, so your themes may require upgrading. - -Old API | Change | New API --------------------------------------|:------:|-------- -**buffer** | | -annotation\_get\_text(line) |Renamed |annotation\_text[line] -annotation\_set\_text(line, text) |Renamed |annotation\_text[line] = text -auto\_c\_get\_current() |Renamed |auto\_c\_current -auto\_c\_get\_current\_text() |Renamed |auto\_c\_current\_text -get\_lexer\_language() |Renamed |lexer\_language -get\_property(key) |Renamed |property[key] -get\_property\_expanded(key) |Renamed |property\_expanded[key] -get\_tag(n) |Renamed |tag[n] -margin\_get\_text(line) |Renamed |margin\_text[line] -margin\_set\_text(line, text) |Renamed |margin\_text[line] = text -marker\_set\_alpha(n, alpha) |Renamed |marker\_alpha[n] = alpha -marker\_set\_back(n, color) |Renamed |marker\_back[n] = color -marker\_set\_back\_selected(n, color)|Renamed |marker\_back\_selected[n] = color -marker\_set\_fore(n, color) |Renamed |marker\_fore[n] = color -set\_fold\_flags(flags) |Renamed |fold\_flags = flags -set\_lexer\_language(name) |Renamed |lexer\_language = name -style\_get\_font(n) |Renamed |style\_font[n] -**gui** | | -gtkmenu() |Renamed |[menu()][] -**_G** | | -user\_dofile(file) |Renamed |dofile(\_USERHOME..'/'..file) -**_M** | | -lua.goto\_required() |Removed |N/A -php.goto\_required() |Removed |N/A -ruby.goto\_required() |Removed |N/A -**_M.textadept.adeptsense** | | -complete\_symbol() |Replaced|complete() -show\_documentation() |Replaced|show\_apidoc() -**_M.textadept.bookmarks** | | -N/A |New |[toggle()][] -add() |Renamed |toggle(true) -remove() |Renamed |toggle(false) -**_M.textadept.editing** | | -prepare\_for\_save() |Removed |N/A -**_M.textadept.menu** | | -rebuild\_command\_tables() |Replaced|set\_menubar() -**_M.textadept.run** | | -execute() |Replaced|[run()][] and [compile()][] -**_M.textadept.session** | | -prompt\_load() |Replaced|[load()][] -prompt\_save() |Replaced|[save()][] - -[menu()]: api/ui.html#menu -[toggle()]: api/textadept.bookmarks.html#toggle -[run()]: api/textadept.run.html#run -[compile()]: api/textadept.run.html#compile -[load()]: api/textadept.session.html#load -[save()]: api/textadept.session.html#save - -### Textadept 4 to 5 - -Textadept 5 upgraded its copy of Lua from [5.1 to 5.2][]. Many old scripts are -not compatible and need to be upgraded. 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 make to Textadept's internals. - -[5.1 to 5.2]: http://www.lua.org/manual/5.2/manual.html#8 - -#### API Changes - -Old API |Change |New API ----------------|:------:|------- -**_G** | | -getfenv(f) |Removed |N/A. Use:
debug.getupvalue(f, 1) -loadstring() |Replaced|load() -module() |Removed |N/A -setfenv(f, env)|Removed |N/A. Use:
debug.setupvalue(f, 1, env)a -unpack() |Renamed |table.unpack() -xpcall(f, msgh)|Changed |xpcall(f, msgh, ...) -**\_m** |Renamed |**[\_M][]**b -**_m.textadept.editing**| | -current\_word(action) |Renamed|[select\_word()][]c -**locale** |Removed|N/A -localize(message) |Renamed|\_G.[\_L][][message] -**os** | | -code = execute(cmd) |Changed|ok, status, code = execute(cmd) - -aIn some cases, use `load()` with an environment instead: - - setfenv(loadstring(str), env)() --> load(str, nil, 'bt', env)() - -bIn Textadept, search for "\_m" and replace with "\_M" with the -"Match Case" and "Whole Words" options checked -- this is what I did when -upgrading Textadept's internals. - -cTo delete, call `_M.textadept.keys.utils.delete_word()` or define -your own: - - local function delete_word() - _M.textadept.editing.select_word() - buffer:delete_back() - end - -[\_M]: api/_M.html -[select\_word()]: api/textadept.editing.html#select_word -[\_L]: api/_L.html - -#### Module Changes - -You can use the following as a reference for converting your Lua 5.1 modules to -Lua 5.2: - - -- File *~/.textadept/modules/foo.lua* - -- Lua 5.1 | -- Lua 5.2 - | - | local M = {} - | --[[ This comment is for LuaDoc - --- | --- - -- This is the documentation | -- This is the documentation - -- for module foo. | -- for module foo. - module('foo', package.seeall) | module('foo')]] - | - --- | --- - -- Documentation for bar. | -- Documentation for bar. - -- ... | -- ... - -- | -- @name bar - function bar() | function M.bar() - ... | ... - end | end - | - function baz() | function M.baz() - bar() | M.bar() - end | end - | - | return M - - -- File *~/.textadept/init.lua* - -- Lua 5.1 | -- Lua 5.2 - | - require 'textadept' | _M.textadept = require 'textadept' - require 'foo' | foo = require 'foo' - -Notes: - -1. Even though Lua 5.2 deprecates Lua 5.1's `module()`, Textadept 5 removes it. -2. Prefix all intern module tables and function calls with `M`. -3. Also, replace all instances (if any) of `_M` (a references created by - `module()` that holds the current module table) with `M`. -4. You can use your existing LuaDoc comments by keeping the `module()` call - commented out and adding `@name` tags. - -#### Theme Changes - -You can use the following as a reference for converting your Lua 5.1 themes to -Lua 5.2: - - -- File *~/.textadept/themes/theme/lexer.lua* - -- Lua 5.1 | -- Lua 5.2 - | - | local l = lexer - module('lexer', package.seeall) | local color = l.color - | local style = l.style - | - colors = { | l.colors = { - ... | ... - } | } - | - style_nothing = style{} | l.style_nothing = style{...} - style_class = style{ | l.style_class = style{ - fore = colors.light_yellow | fore = l.colors.light_yellow - } | } - ... | ... - style_identifier = style_nothing | l.style_identifier = l.style_nothing - | - ... | ... - | - style_default = style{ | l.style_default = style{ - ... | ... - } | } - style_line_number = { | l.style_line_number = { - fore = colors.dark_grey, | fore = l.colors.dark_grey, - back = colors.black | back = l.colors.black - } | } - ... | ... - -Note the `l.` prefix before most identifiers. - -### Textadept 3 to 4 - -#### Key and Menu Changes - -Textadept 4 features a brand new set of key bindings and menu structure. It also -shows simple key bindings (not keychains) in menus. In order for key bindings to -appear in menus, `_m.textadept.menu` must know which commands map to which keys. -Therefore, the menu module needs to be `require`d *after* `_m.textadept.keys`. -If your *~/.textadept/init.lua* calls `require 'textadept'`, you do not have to -make any changes. If you load individual modules from `_m.textadept`, ensure -`_m.textadept.menu` loads after `_m.textadept.keys`. - -Mac OSX has different modifier key definitions. A new `m` indicates ⌘ (command) -and `a` changed from ⌘ to ⌥ (alt/option). `c` remains ^ (control). Keep in mind -that ⌥ functions as a compose key for locale-dependent characters. - -#### API Changes - -Old API |Change | New API --------------------------|:-----:|-------- -**\_m.textadept.editing**| | -select\_scope() |Renamed|select\_style() -SAVE\_STRIPS\_WS |Renamed|STRIP\_WHITESPACE\_ON\_SAVE - -### Textadept 2 to 3 - -#### Module Changes - -##### Core Extensions - -The core extention modules moved from *core/ext/* to *modules/textadept/*. -Putting - - require 'textadept' - -in your *~/.textadept/init.lua* loads all the modules you would expect. The -[preferences][] page has instructions on how to load specific modules. - -[preferences]: 08_Preferences.html#User.Init - -##### Autoloading - -Key bindings in *~/.textadept/key_commands.lua* and snippets in -*~/.textadept/snippets.lua* no longer auto-load. Move them to your -*~/.textadept/init.lua* or a file loaded by *~/.textadept/init.lua*. - -#### API Changes - -Textadept has a brand new Lua [API][]. Old scripts and themes are likely not -compatible and need to be upgraded. - -Old API |Change | New API ---------------------------|:-----:|-------- -**_G** | | -N/A |New |[\_SCINTILLA][] -N/A |New |[events][] -N/A |New |[gui][] -**_m.textadept.lsnippets**|Renamed|**[_m.textadept.snippets][]** -**textadept** |Removed|N/A -\_print() |Renamed|\_G.[gui.\_print()][] -buffer\_functions |Renamed|\_G.[\_SCINTILLA.functions][] -buffer\_properties |Renamed|\_G.[\_SCINTILLA.properties][] -buffers |Renamed|\_G.[\_BUFFERS][] -check\_focused\_buffer() |Renamed|\_G.gui.check\_focused\_buffer() -clipboard\_text |Renamed|\_G.[gui.clipboard\_text][] -command\_entry |Renamed|\_G.[gui.command\_entry][] -constants |Renamed|\_G.[\_SCINTILLA.constants][] -context\_menu |Renamed|\_G.[gui.context\_menu][] -dialog |Renamed|\_G.[gui.dialog()][] -docstatusbar\_text |Renamed|\_G.[gui.docstatusbar\_text][] -events |Renamed|\_G.[events][] -events.add\_handler() |Renamed|\_G.[events.connect()][] -events.handle() |Renamed|\_G.[events.emit()][] -find |Renamed|\_G.[gui.find][] -focused\_doc\_pointer |Renamed|\_G.gui.focused\_doc\_pointer -get\_split\_table() |Renamed|\_G.[gui.get\_split\_table()][] -goto\_view() |Renamed|\_G.[gui.goto\_view()][] -gtkmenu() |Renamed|\_G.[gui.gtkmenu()][] -iconv() |Renamed|\_G.[string.iconv()][] -menubar |Renamed|\_G.[gui.menubar][] -new\_buffer() |Renamed|\_G.[new\_buffer()][] -print() |Renamed|\_G.[gui.print()][] -quit() |Renamed|\_G.[quit()][] -reset() |Renamed|\_G.[reset()][] -session\_file |Renamed|\_G.\_SESSIONFILE -size |Renamed|\_G.[gui.size][] -statusbar\_text |Renamed|\_G.[gui.statusbar\_text][] -switch\_buffer() |Renamed|\_G.[gui.switch\_buffer()][] -title |Renamed|\_G.[gui.title][] -user\_dofile() |Renamed|\_G.user\_dofile() -views |Renamed|\_G.[\_VIEWS][] - -[API]: api -[\_SCINTILLA]: api/_SCINTILLA.html -[events]: api/events.html -[gui]: api/ui.html -[_m.textadept.snippets]: api/textadept.snippets.html -[gui.\_print()]: api/ui.html#_print -[\_SCINTILLA.functions]: api/_SCINTILLA.html#functions -[\_SCINTILLA.properties]: api/_SCINTILLA.html#properties -[\_BUFFERS]: api/_G.html#_BUFFERS -[gui.clipboard\_text]: api/ui.html#clipboard_text -[gui.command\_entry]: api/ui.command_entry.html -[\_SCINTILLA.constants]: api/_SCINTILLA.html#constants -[gui.context\_menu]: api/ui.html#context_menu -[gui.dialog()]: api/ui.html#dialog -[gui.docstatusbar\_text]: api/ui.html#docstatusbar_text -[events.connect()]: api/events.html#connect -[events.emit()]: api/events.html#emit -[gui.find]: api/ui.find.html -[gui.get\_split\_table()]: api/ui.html#get_split_table -[gui.goto\_view()]: api/ui.html#goto_view -[gui.gtkmenu()]: api/ui.html#gtkmenu -[string.iconv()]: api/string.html#iconv -[gui.menubar]: api/ui.html#menubar -[new\_buffer()]: api/_G.html#new_buffer -[gui.print()]: api/ui.html#print -[quit()]: api/_G.html#quit -[reset()]: api/_G.html#reset -[gui.size]: api/ui.html#size -[gui.statusbar\_text]: api/ui.html#statusbar_text -[gui.switch\_buffer()]: api/ui.html#switch_buffer -[gui.title]: api/ui.html#title -[\_VIEWS]: api/_G.html#_VIEWS diff --git a/doc/index.html b/doc/index.html index cf43c089..7e314a1c 100644 --- a/doc/index.html +++ b/doc/index.html @@ -56,8 +56,8 @@

Support

@@ -195,19 +195,19 @@

Textadept comes with a comprehensive user manual in the application’s doc/ directory. This manual is also available - online. It covers all of - Textadept’s main features, including installation, usage, - configuration, theming, scripting, and compilation. + online. It covers all of Textadept’s main + features, including installation, usage, configuration, theming, + scripting, and compilation.

Exhaustive API Documentation

Since Textadept is entirely scriptable with Lua, its API is heavily - documented. This documentation is located in the doc/api/ - directory (also available online), and is the - ultimate resource on scripting Textadept. (The editor’s Lua - internals also provide abundant scripting examples.) + documented. This documentation is also located in doc/, is + available online, and is the ultimate + resource on scripting Textadept. (The editor’s Lua internals also + provide abundant scripting examples.)

diff --git a/doc/manual.md b/doc/manual.md new file mode 100644 index 00000000..a0b4716d --- /dev/null +++ b/doc/manual.md @@ -0,0 +1,2370 @@ +# Textadept Manual + +**Contents** + +1. [Introduction](#Introduction) +2. [Installation](#Installation) +3. [User Interface](#User.Interface) +4. [Working with Files](#Working.With.Files) +5. [File Navigation](#File.Navigation) +6. [Adept Editing](#Adept.Editing) +7. [Modules](#Modules) +8. [Preferences](#Preferences) +9. [Themes](#Themes) +10. [Advanced](#Advanced) +11. [Scripting](#Scripting) +12. [Compiling](#Compiling) +13. [Help](#Help) +14. [Appendix](#Appendix) + +- - - + +# Introduction + +- - - + +## Overview + +![Textadept](images/textadept.png) + +Textadept is a fast, minimalist, and remarkably extensible cross-platform text +editor for programmers. Written in a combination of C and [Lua][] and +relentlessly optimized for speed and minimalism over the years, Textadept is an +ideal editor for programmers who want endless extensibility without sacrificing +speed or succumbing to code bloat and featuritis. + +[Lua]: http://www.lua.org + +### Fast + +Textadept is _fast_. It starts up instantly and has a very responsive user +interface. Even though the editor consists primarily of Lua, Lua is one of the +fastest scripting languages available. With the optional [LuaJIT][] version, +Textadept runs faster than ever before. + +[LuaJIT]: http://luajit.org + +### Minimalist + +Textadept is minimalist. Not only does its appearance exhibit this, but the +editor's C core pledges to never exceed 2000 lines of code and its Lua extension +code avoids going beyond 4000 lines. After more than 5 years of development, +Textadept contains the same amount of code since its inception while evolving +into a vastly superior editor. + +### Remarkably Extensible + +Textadept is remarkably extensible. Designed to be that way from the very +beginning, the editor's features came later. Most of Textadept's internals use +Lua, from syntax highlighting to opening and saving files to searching and +replacing and more. Textadept gives you complete control over the entire +application using Lua. Everything from moving the caret to changing menus and +key commands on-the-fly to handling core events is possible. Its potential is +vast. + +![Split Views](images/splitviews.png) + +## Manual Notation + +The manual represents directories and file paths like this: */path/to/dir/* and +*/path/to/file*. (Windows machines use '/' and '\' interchangeably as directory +separators.) Paths that do not begin with '/' or "C:\", are relative to the +location of Textadept. *~/* denotes the user's home directory. On Windows +machines this is the value of the "USERHOME" environment variable, typically +*C:\Users\username\\* or *C:\Documents and Settings\username\\*. On Linux, BSD, +and Mac OSX machines it is the value of "$HOME", typically */home/username/* and +*/Users/username/*, respectively. + +The manual expresses key bindings like this: `Ctrl+N`. They are not case +sensitive. `Ctrl+N` stands for pressing the "N" key while only holding down the +"Control" modifier key, not the "Shift" modifier key. `Ctrl+Shift+N` stands for +pressing the "N" key while holding down both the "Control" and "Shift" +modifiers. The same notation applies to key chains like `Ctrl+N, N` and +`Ctrl+N, Shift+N`. The first key chain represents pressing "Control" and "N" +followed by "N" with no modifiers. The second represents pressing "Control" and +"N" followed by "Shift" and "N". + +When mentioning key bindings, the manual often shows the Mac OSX and curses +equivalents in parenthesis. It may be tempting to assume that some Windows/Linux +keys map to Mac OSX's (e.g. `Ctrl` to `⌘`) or curses' (e.g. `Ctrl` to `^`), but +this is not always the case. To minimize confusion, view key equivalents as +separate entities, not as translations of one another. + +- - - + +# Installation + +- - - + +## Requirements + +In its bid for minimalism, Textadept also depends on very little to run. The GUI +version needs only [GTK+][], a cross-platform GUI toolkit, version 2.18 or later +on Linux and BSD systems. The application already bundles a GTK+ runtime into +the Windows and Mac OSX packages. The terminal, or curses, version of Textadept +only depends on a curses implementation like [ncurses][] on Linux, Mac OSX, and +BSD systems. The Windows binary includes a precompiled version of [pdcurses][]. +Textadept also incorporates its own [copy of Lua](#Lua.Configuration) on all +platforms. + +[GTK+]: http://gtk.org +[ncurses]: http://invisible-island.net/ncurses/ncurses.html +[pdcurses]: http://pdcurses.sourceforge.net + +### Requirements for Linux and BSD + +Most Linux and BSD systems already have GTK+ installed. If not, your package +manager probably makes it available. Otherwise, compile and install GTK+from the +[GTK+ website][]. + +The Linux binaries for the GUI versions of Textadept require GLib version 2.28 +or later to support [single-instance](#Single.Instance) functionality. However, +Textadept compiles with versions of GLib as early as 2.22. For reference, Ubuntu +11.04, Debian Wheezy, Fedora 15, and openSUSE 11.4 support GLib 2.28 or later. + +Most Linux and BSD systems already have a curses implementation like ncurses +installed. If not, look for one in your package manager, or compile and install +ncurses from the [ncurses website][]. Ensure it is the wide-character version of +ncurses, which handles multibyte characters. Debian-based distributions like +Ubuntu typically call the package "libncursesw5". + +[GTK+ website]: http://www.gtk.org/download/linux.php +[ncurses website]: http://invisible-island.net/ncurses/#download_ncurses + +### Requirements for Mac OSX + +No requirements other than Mac OSX 10.5 (Leopard) or higher with an Intel CPU. + +### Requirements for Windows + +No requirements. + +## Download + +Download Textadept from the project's [download page][] by selecting the +appropriate package for your platform. For the Windows and Mac OSX packages, the +bundled GTK+ runtime accounts for more than 3/4 of the download and unpackaged +application sizes. Textadept itself is much smaller. + +You also have the option of downloading an official set of +[language modules](#Language.Modules) from the download page. Textadept itself +includes C/C++ and Lua language modules by default. + +[download page]: http://foicica.com/textadept/download + +## Installation + +Installing Textadept is simple and easy. You do not need administrator +privileges. + +### Installing on Linux and BSD + +Unpack the archive anywhere. + +If you downloaded the set of language modules, unpack it where you unpacked the +Textadept archive. The modules are located in the +*/path/to/textadept_x.x/modules/* directory. + +### Installing on Mac OSX + +Unpack the archive and move *Textadept.app* to your user or system +*Applications/* directory like any other Mac OSX application. The package +contains an optional *ta* script for launching Textadept from the command line +that you can put in a directory in your "$PATH" (e.g. */usr/local/bin/*). + +If you downloaded the set of language modules, unpack it, right-click +*Textadept.app*, select "Show Package Contents", navigate to +*Contents/Resources/modules/*, and move the unpacked modules there. + +### Installing on Windows + +Unpack the archive anywhere. + +If you downloaded the set of language modules, unpack it where you unpacked the +Textadept archive. The modules are located in the *textadept_x.x\modules\\* +directory. + +## Running + +### Running on Linux and BSD + +Run Textadept by running */path/to/textadept_x.x/textadept* from the terminal +You can also create a symbolic link to the executable in a directory in your +"$PATH" (e.g. */usr/local/bin/*) or make a GNOME, KDE, XFCE, etc. button or menu +launcher. + +The package also contains a *textadeptjit* executable for running Textadept with +[LuaJIT][]. Due to potential [compatibility issues](#LuaJIT), use the +*textadept* executable wherever possible. + +The *textadept-curses* and *textadeptjit-curses* executables are the terminal +versions of Textadept. Run them as you would run the *textadept* and +*textadeptjit* executables, but from a terminal instead. + +[LuaJIT]: http://luajit.org + +#### Runtime Problems + +Providing a single binary that runs on all Linux platforms proves challenging, +since the versions of software installed vary widely from distribution to +distribution. Because the Linux version of Textadept uses the version of GTK+ +installed on your system, an error like: + + error while loading shared libraries: : cannot open shared object + file: No such file or directory + +may occur when trying to run the program. The solution is actually quite +painless even though it requires [recompiling](#Compiling) Textadept. + +### Running on Mac OSX + +Run Textadept by double-clicking *Textadept.app*. You can also pin it to your +dock. + +*Textadept.app* also contains an executable for running Textadept with +[LuaJIT][]. Enable it by setting a "TEXTADEPTJIT" +[environment variable](#Mac.OSX.Environment.Variables) or by typing +`export TEXTADEPTJIT=1` in the terminal. Due to potential +[compatibility issues](#LuaJIT), use the non-LuaJIT executable wherever +possible. + +[LuaJIT]: http://luajit.org + +#### Mac OSX Environment Variables + +By default, Mac OSX GUI apps like Textadept do not see shell environment +variables like "$PATH". Consequently, any [modules](#Modules) that utilize +programs contained in "$PATH" (e.g. the progams in */usr/local/bin/*) for run +and compile commands will not find those programs. The solution is to create a +*~/.textadept/osx_env.sh* file that exports all of the environment variables you +need Textadept to see. For example: + + export PATH=$PATH + +### Running on Windows + +Run Textadept by double-clicking *textadept.exe*. You can also create shortcuts +to the executable in your Start Menu, Quick Launch toolbar, Desktop, etc. + +The package also contains a *textadeptjit.exe* executable for running Textadept +with [LuaJIT][]. Due to potential [compatibility issues](#LuaJIT), use the +*textadept.exe* executable wherever possible. + +[LuaJIT]: http://luajit.org + +### *~/.textadept* + +Textadept stores all of your preferences and user-data in your *~/.textadept/* +directory. If this directory does not exist, Textadept creates it on startup. +The manual gives more information on this folder later. + +## Single Instance + +Textadept is a single-instance application on Linux, BSD, and Mac OSX. This +means that after starting Textadept, running `textadept file.ext` (`ta file.ext` +on Mac OSX) from the command line or opening a file with Textadept from a file +manager opens *file.ext* in the original Textadept instance. Passing a `-f` or +`--force` switch to Textadept overrides this behavior and opens the file in a +new instance: `textadept -f file.ext` (`ta -f file.ext`). Without the force +switch, the original Textadept instance opens files, regardless of the number of +instances open. + +The Windows and terminal versions of Textadept do not support single instance. + + +![Linux](images/linux.png) +   +![Mac OSX](images/macosx.png) +   +![Win32](images/win32.png) +   +![curses](images/ncurses.png) + + +- - - + +# User Interface + +- - - + +![UI](images/ui.png) + +Textadept's user interface is sleek and simple. It consists of a menu (GUI +version only), editor view, and statusbar. There is also a find & replace pane +and a command entry, but Textadept initially hides them both. The manual briefly +describes these features below, but provides more details later. + +## Menu + +The completely customizable menu provides access to all of Textadept's features. +Only the GUI version implements it, though. The terminal version furnishes the +[command selection](#Command.Selection) dialog instead. Textadept is very +keyboard-driven and assigns key shortcuts to most menu items. Your +[key preferences](#Key.Bindings) can change these shortcuts and reflect in the +menu. Here is a [complete list][] of default key bindings. + +[complete list]: api.html#textadept.keys + +## Tab Bar + +The tab bar displays all of Textadept's open buffers, although it's only visible +when two or more buffers are open. While only the GUI version supports tabs, +Textadept's [buffer browser](#Buffers) is always available and far more +powerful. + +## Editor View + +Most of your time spent with Textadept is in the editor view. Both the GUI +version and the terminal version feature unlimited vertical and horizontal view +splitting. Lua also has complete control over all views. + +## Find & Replace Pane + +This compact pane is a great way to slice and dice through your document or a +directory of files. It even supports finding and replacing text using Lua +patterns and Lua code. The pane is available only when you need it and quickly +gets out of your way when you do not, minimizing distractions. + +## Command Entry + +The versatile command entry functions as, among other things, a place to execute +Lua commands with Textadept's internal Lua state, find text incrementally, and +execute shell commands. Lua extensions allow it to do even more. Like the Find & +Replace pane, the command entry pops in and out as you wish. + +## Statusbar + +The statusbar actually consists of two statusbars. The one on the left-hand +side displays temporary status messages while the one on the right-hand side +persistently shows the current buffer status. + +- - - + +# Working with Files + +- - - + +## Buffers + +Despite the fact that Textadept can display multiple buffers with a tab bar, the +buffer browser is usually a faster way to switch between buffers or quickly +assess which files are open. Press `Ctrl+B` (`⌘B` on Mac OSX | `M-B` or `M-S-B` +in curses) to display this browser. + +![Buffer Browser](images/bufferbrowser.png) + +The buffer browser displays a list of currently open buffers, the most recent +towards the bottom. Typing part of any filename filters the list. Spaces are +wildcards. The arrow keys move the selection up and down. Pressing `Enter`, +selecting `OK`, or double-clicking a buffer in the list switches to the selected +buffer. + +![Buffer Browser Filtered](images/bufferbrowserfiltered.png) + +Textadept shows the name of the active buffer in its titlebar. Pressing +`Ctrl+Tab` (`^⇥` on Mac OSX | `M-N` in curses) cycles to the next buffer and +`Ctrl+Shift+Tab` (`^⇧⇥` | `M-P`) cycles to the previous one. + +### Typical Buffer Settings + +Individual files have three configurable settings: indentation, line endings, +and encoding. Indentation consists of an indentation character and an +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) + +#### Buffer Indentation + +Normally, a [language module](#Language-Specific.Buffer.Settings) or the +[user settings](#Buffer.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`) 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. + +#### Buffer Line Endings + +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. + +#### Buffer Encodings + +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](#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 +encoding and performs the conversion. Textadept saves new files as UTF-8 by +default, but does not alter the encoding of existing ones. + +[`io.encodings`]: api.html#io.encodings + +### Recent Files + +Pressing `Ctrl+Alt+O` (`^⌘O` on Mac OSX | `M-^O` in curses) brings up a dialog +that behaves like the buffer browser, but displays a list of recently opened +files to reopen. + +### Sessions + +By default, Textadept saves its state when quitting in order to restore it the +next time the editor starts up. Passing the `-n` or `--nosession` switch to +Textadept on startup disables this feature. The "File -> Save Session..." and +"File -> Load Session..." menus manually save and open sessions while the `-s` +and `--session` switches load a session on startup. The switches accept the path +of a session file or the name of a session in *~/.textadept/*. Session files +store information such as open buffers, current split views, caret and scroll +positions in each buffer, Textadept's window size, and recently opened files. +Tampering with session files may have unintended consequences. + +### Snapopen + +A quicker, though slightly more limited alternative to the standard file +selection dialog is snapopen. It too behaves like the buffer browser, but +displays a list of files to open, including files in sub-directories. Pressing +`Ctrl+Alt+Shift+O` (`^⌘⇧O` on Mac OSX | `M-S-O` in curses) snaps open the +current file's directory, `Ctrl+U` (`⌘U` | `^U`) snaps open *~/.textadept/*, and +`Ctrl+Alt+Shift+P` (`^⌘⇧P` | `M-^P`) snaps open the current project (which must +be under version control). Snapopen is pretty limited from the +"Tools -> Snapopen" menu, but more versatile in [scripts][]. + +[scripts]: api.html#io.snapopen + +![Snapopen](images/snapopen.png) + +## Views + +### Split Views + +Textadept allows you to split the editor window an unlimited number of times +both horizontally and vertically. `Ctrl+Alt+S` or `Ctrl+Alt+H` splits +horizontally into top and bottom views and `Ctrl+Alt+V` splits vertically (`^S` +and `^V`, respectively on Mac OSX | `M-^V S` and `M-^V V` in curses) into +side-by-side views. Clicking and dragging on the splitter bar with the mouse or +pressing `Ctrl+Alt++` and `Ctrl+Alt+-` (`^+` and `^-` | `M-^V +` and `M-^V -`) +resizes the split. Textadept supports viewing a single buffer in two or more +views. + +Pressing `Ctrl+Alt+N` (`^⌥⇥` on Mac OSX | `M-^V N` in curses) jumps to the next +view and `Ctrl+Alt+P` (`^⌥⇧⇥` | `M-^V P`) jumps the previous one. However, +depending on the split sequence, the order when cycling between views may not be +linear. + +To unsplit a view, enter the view to keep open and press `Ctrl+Alt+W` (`^W` on +Mac OSX | `M-^V W` in curses). To unsplit all views, use `Ctrl+Alt+Shift+W` +(`^⇧W` | `M-^V S-W`). + +Note: Textadept curses uses the `M-^V` key prefix for split views. + +### View Settings + +Individual views have many configurable settings. Among the more useful settings +are viewing line endings, handling long lines, viewing indentation guides, and +viewing whitespace. These options change how to display buffers in the _current_ +view. Changing a setting in one view does not change that setting in +any other split view. You must do it manually. + +#### View Line Endings + +Normally, EOL characters ("\r" and "\n") are invisible. Pressing +`Ctrl+Alt+Enter` (`^↩` on Mac OSX | none in curses) toggles their visibility. + +#### View Long Lines + +By default, lines with more characters than the view can show do not wrap into +view. `Ctrl+Alt+\` (`^\` on Mac OSX | none in curses) toggles line wrapping. + +#### View Indentation Guides + +Views show small guiding lines based on indentation level by default. +`Ctrl+Alt+Shift+I` (`^⇧I` on Mac OSX | N/A in curses) toggles the visibility of +these guides. + +Textadept curses does not support indentation guides. + +#### View Whitespace + +Normally, whitespace characters, tabs and spaces, are invisible. Pressing +`Ctrl+Alt+Shift+S` (`^⇧S` on Mac OSX | none in curses) toggles their visibility. +Visible spaces show up as dots and visible tabs show up as arrows. + +### Zoom + +To temporarily increase or decrease the font size in a view, press `Ctrl+=` +(`⌘=` on Mac OSX | N/A in curses) and `Ctrl+-` (`⌘-` | N/A) respectively. +`Ctrl+0` (`⌘0` | N/A) resets the zoom. + +Textadept curses does not support zooming. + +- - - + +# File Navigation + +- - - + +## Basic Movements + +Textadept implements the customary key bindings for navigating text fields on +the current platform. The arrow keys move the caret in a particular direction, +`Ctrl+Left` and `Ctrl+Right` (`^⇠` and `^⇢` on Mac OSX | `^Left` and `^Right` in +curses) move by words, `PgUp` and `PgDn` (`⇞` and `⇟` | `PgUp` and `PgDn`) move +by pages, etc. Mac OSX and curses also handle some Bash-style bindings like +`^B`, `^F`, `^P`, `^N`, `^A`, and `^E`. The "Movement" section of the +[key bindings list][] lists all movement bindings. + +[key bindings list]: api.html#textadept.keys + +## Brace Match + +By default, Textadept highlights the matching brace characters under the caret: +'(', ')', '[', ']', '{', and '}'. Pressing `Ctrl+M` (`^M` on Mac OSX | `M-M` in +curses) moves the caret to the matching brace. + +![Matching Braces](images/matchingbrace.png) + +## Bookmarks + +Textadept supports bookmarking buffer lines to jump back to them later. +`Ctrl+F2` (`⌘F2` on Mac OSX | `F1` in curses) toggles a bookmark on the current +line, `F2` jumps to the next bookmarked line, `Shift+F2` (`⇧F2` | `F3`) jumps to +the previously bookmarked line, `Alt+F2` (`⌥F2` | `F4`) jumps to the bookmark +selected from a list, and `Ctrl+Shift+F2` (`⌘⇧F2` | `F6`) clears all bookmarks +in the current buffer. + +## Goto Line + +To jump to a specific line in a file, press `Ctrl+J` (`⌘J` on Mac OSX | `^J` in +curses), specify the line number in the prompt, and press `Enter` (`↩` | +`Enter`) or click `Ok`. + +- - - + +# Adept Editing + +- - - + +## Basic Editing + +Textadept features many common, basic editing features: inserting text, +undo/redo, manipulating the clipboard, deleting characters and words, +duplicating lines, joining lines, and transposing characters. The top-level +"Edit" menu contains these actions and lists their associated key bindings. The +manual discusses more elaborate editing features below. + +### Autopaired Characters + +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 typed one. The +[module preferences](#Generic.Module.Preferences) section details how to +configure or disable these features. + +### Word Completion + +Textadept provides buffer-based word completion. Start typing a word and press +`Ctrl+Enter` (`^⎋` on Mac OSX | `M-Enter` in curses) to display a list of +suggested completions based on words in the current buffer. Continuing to type +changes the suggestion. Press `Enter` (`↩` | `Enter`) to complete the selected +word. + +![Word Completion](images/wordcompletion.png) + +### Virtual Space Mode + +Pressing `Ctrl+Alt+Shift+V` (`^⇧V` in Mac OSX | none in curses) enables and +disables Virtual space (freehand) mode. When virtual space is enabled, the caret +may move into the space past the ends of lines. + +### Overwrite Mode + +Enable and disable overwrite mode with the `Insert` key. When enabled, typing +overwrites existing characters in the buffer rather than inserting the typed +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 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 +effort, but has powerful uses. + +### Multiple 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 + +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) +     +![Rectangular Edit](images/rectangularselection2.png) + +Note: In some Linux environments, the window manager consumes `Alt+Shift+Arrow` +combinations so Textadept may need reconfiguring. Also, Textadept uses +`Super+Mouse` because `Alt+Mouse` generally moves windows. (Your window manager +usually defines the `Super` modifier key as the left "Windows" key.) If you +prefer to use `Alt`, change [`buffer.rectangular_selection_modifier`][] in your +[preferences](#Buffer.Settings). + +Textadept curses does not support creating rectangular selections with the +mouse. + +[`buffer.rectangular_selection_modifier`]: api.html#buffer.rectangular_selection_modifier + +### Select to Matching Brace + +Putting the caret over a brace character ('(', ')', '[', ']', '{', or '}') and +pressing `Ctrl+Shift+M` (`^⇧M` on Mac OSX| `M-S-M` in curses) extends the +selection to the brace character's matching brace. + +### Entity Selection + +Textadept allows the selection of many different entities from the caret. For +example, `Ctrl+"` (`^"` on Mac OSX | `M-"` in curses) selects all characters in +a double-quoted range. Typing it again selects the double-quotes too. The +"Edit -> Select In..." menu lists all selectable entities with their key +bindings. + +### Marks + +In curses, since some terminals do not recognize certain key combinations like +`Shift+Arrow` for making selections, marks can create selections. Create a mark +at the current caret position with `^^`. Then use regular movement keys like the +arrows, page up/down, and home/end to extend the selection in one direction. +Pressing `^]` swaps the current caret position with the original mark position +in order to extend the selection in the opposite direction. Typing text, +deleting text, or running a command that does either, removes the mark and +restores ordinary navigation. Pressing `^^` again also stops selecting text. + +Only Textadept curses supports marks. + +### Transforms + +#### Enclose Entities + +As a complement to selecting entities, Textadept allows the enclosure of text in +entities. The "Edit -> Selection -> Enclose In..." menu lists all enclosing +entities with their key bindings. Each action encloses either the currently +selected text or the word to the left of the caret. For example, pressing +`Alt+<` (`^<` on Mac OSX | `M->` in curses) at the end of a word encloses it in +XML tags. + +#### Change Case + +Pressing `Ctrl+Alt+U` or `Ctrl+Alt+Shift+U` (`^U` or `^⇧U` on Mac OSX | `M-^U` +or `M-^L` in curses) converts selected text to upper case letters or lower case +letters, respectively. + +#### Change Indent Level + +Increase the amount of indentation for a selected set of lines by pressing `Tab` +(`⇥` on Mac OSX | `Tab` in curses). `Shift+Tab` (`⇧⇥` | `S-Tab`) decreases it. +You do not have to select whole lines. Selecting any part of a line renders the +entire line eligible for indenting/dedenting. Using these key sequences when no +selection is present does not have the same effect. + +#### Move Lines + +Move selected lines up and down with the `Ctrl+Shift+Up` and `Ctrl+Shift+Down` +(`^⇧⇡` and `^⇧⇣` on Mac OSX | `S-^Up` and `S-^Down` in curses) keys, +respectively. Like with changing indent level, selecting any part of a line +renders the entire line eligible for moving. + +## Find & Replace + +`Ctrl+F` (`⌘F` on Mac OSX | `M-F` or `M-S-F` in curses) brings up the Find & +Replace pane. In addition to offering the usual find and replace with "Match +Case" and "Whole Word" options and find/replace history, Textadept supports +finding with [Lua patterns](#Lua.Patterns) and replacing with Lua captures and +even Lua code! For example: replacing all `%w+` with `%(string.upper('%0'))` +upper cases all words in the buffer. Replacement text only recognizes Lua +captures (`%`_`n`_) from a Lua pattern search, but always allows embedded Lua +code enclosed in `%()`. + +Note the `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, `Ctrl+Alt+Shift+R` key bindings +for find next, find previous, replace, and replace all (`⌘G`, `⌘⇧G`, `^R`, and +`^⇧R`, respectively on Mac OSX | `M-G`, `M-S-G`, `M-R`, `M-S-R` in curses) only +work after hiding the Find & Replace pane. For at least the English locale in +the GUI version, use the button mnemonics: `Alt+N`, `Alt+P`, `Alt+R`, and +`Alt+A` (`⌘N`, `⌘P`, `⌘R`, `⌘A` | N/A) after bringing up the pane. + +In the curses version, `Tab` and `S-Tab` toggles between the find next, find +previous, replace, and replace all buttons; `Up` and `Down` arrows switch +between the find and replace text fields; `^P` and `^N` cycles through history; +and `F1-F4` toggles find options. + +Pressing `Esc` (`⎋` | `Esc`) hides the pane after you finish with it. + +### Replace in Selection + +By default, "Replace All" replaces all text in the buffer. Selecting a block of +text and then "Replace All" replaces all text in the selection. + +### Find in Files + +`Ctrl+Shift+F` brings up Find in Files (`⌘⇧F` on Mac OSX | none in curses) and +prompts for a directory to search. A new buffer lists the search results. +Double-clicking a search result jumps to it in the file, as do the the +`Ctrl+Alt+G` and `Ctrl+Alt+Shift+G` (`^⌘G` and `^⌘⇧G` | none) key bindings. +Textadept does not support replacing in files directly. You must "Find in Files" +first, and then "Replace All" for each file containing a result. The "Match +Case", "Whole Word", and "Lua pattern" flags still apply. + +_Warning_: currently, the [find API][] provides the only means to specify a +file-type filter. While the default filter excludes many common binary files +and version control folders from searches, Find in Files could still scan +unrecognized binary files or large, unwanted sub-directories. Searches also +block Textadept from receiving additional input, making the interface +temporarily unresponsive. Searching large directories or projects can be very +time consuming and frustrating, so you may prefer to use a specialized, external +tool such as [ack][]. + +![Find in Files](images/findinfiles.png) + +[find API]: api.html#ui.find.FILTER +[ack]: http://betterthangrep.com/ + +### Incremental Find + +Start an incremental search by pressing `Ctrl+Alt+F` (`^⌘F` on Mac OSX | `M-^F` +in curses). Incremental search searches the buffer as you type, but only +recognizes the "Match Case" find option. Pressing `Esc` (`⎋` | `Esc`) stops the +search. + +## Source Code Editing + +Being a programmer's editor, Textadept excels at editing source code. It +understands the syntax and structure of more than 90 different programming +languages and recognizes hundreds of file types. Textadept uses this knowledge +to make viewing and editing code faster and easier. It can also compile and run +simple source files. + +### Lexers + +Upon opening a file, Textadept attempts to identify the programming language +associated with it and set a "lexer" to highlight syntactic elements of the +code. Pressing `Ctrl+Shift+L` (`⌘⇧L` on Mac OSX | `M-S-L` in curses) and +selecting a lexer from the list manually sets the lexer instead. Your +[file type preferences](#File.Types) customize how Textadept recognizes files. + +Occasionally while you edit, lexers may lose track of their context and +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. 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. + +![Folding](images/folding.png) + +### Word Highlight + +To highlight all occurrences of a given word, such as a variable name, put the +caret over the word and press `Ctrl+Alt+Shift+H` (`⌘⇧H` on Mac OSX | N/A in +curses). This feature also works for plain text. + +![Word Highlight](images/wordhighlight.png) + +### Autocompletion and Documentation + +Textadept has the capability to autocomplete symbols for programming languages +and display API documentation. Pressing `Ctrl+Space` (`⌥⎋` on Mac OSX | `^Space` +in curses) completes the current symbol and `Ctrl+H` (`^H` | `M-H` or `M-S-H`) +shows any known documentation on the current symbol. Note: In order for these +features to work, the language you are working with must have an +[autocompleter][] and [API file(s)][], respectively. +[Language modules](#Language.Modules) usually [define these][]. Most of the +[official][] Textadept language modules support autocompletion and +documentation. + +![Autocomplete Lua](images/adeptsense_lua.png) +     +![Autocomplete Lua String](images/adeptsense_string.png) + +![Documentation](images/adeptsense_doc.png) + +[autocompleter]: api.html#textadept.editing.autocompleters +[API file(s)]: api.html#textadept.editing.api_files +[define these]: api.html#_M.Autocompletion.and.Documentation +[official]: http://foicica.com/hg + +### Snippets + +Snippets are essentially pieces of text inserted into source code or plain text. +However, snippets are not bound to static text. They can be dynamic templates +which contain placeholders for further user input, can mirror or transform those +user inputs, and/or can execute arbitrary code. Snippets are useful for rapidly +constructing blocks of code such as control structures, method calls, and +function declarations. Press `Ctrl+K` (`⌥⇥` on Mac OSX | `M-K` in curses) for a +list of available snippets. A snippet consists of a trigger word and snippet +text. Instead of manually selecting a snippet to insert, type its trigger word +followed by the `Tab` (`⇥` | `Tab`) key. Subsequent presses of `Tab` (`⇥` | +`Tab`) cause the caret to enter placeholders in sequential order, `Shift+Tab` +(`⇧⇥` | `S-Tab`) goes back to the previous placeholder, and `Ctrl+Shift+K` +(`⌥⇧⇥` | `M-S-K`) cancels the current snippet. Textadept supports nested +snippets, snippets inserted from within another snippet. Language modules +usually define their [own set][] of snippets, but your +[snippet preferences](#Snippet.Preferences) can define some too. + +![Snippet](images/snippet.png) +     +![Snippet Expanded](images/snippet2.png) + +[own set]: api.html#_M.Snippets + +### Toggle Comments + +Pressing `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in curses) comments or uncomments the +code on the selected lines. Selecting any part of a line renders the entire line +eligible for commenting or uncommenting. + +### Compile, Run, and Build + +Textadept knows most of the commands that compile and/or run code in source +files. It can also sometimes detect your project's build file and run that. +Pressing `Ctrl+Shift+R` (`⌘⇧R` on Mac OSX | `M-^R` in curses) executes the +command for compiling code in the current file, `Ctrl+R` (`⌘R` | `^R`) executes +the command for running code, and `Ctrl+Shift+B` (`⌘⇧B` on Mac OSX | `M-^B` in +curses) executes the command for building a project. `Ctrl+Shift+X` (`⌘⇧X` | +`N/A`) stops the currently running process. A new buffer shows the output from +the command and marks any recognized warnings and errors. Pressing `Ctrl+Alt+E` +(`^⌘E` | `M-X`) attempts to jump to the source of the next recognized warning or +error and `Ctrl+Alt+Shift+E` (`^⌘⇧E` | `M-S-X`) attempts to jump to the previous +one. Double-clicking on warnings and errors also jumps to their sources. If +Textadept does not know the correct commands for compiling and/or running your +language's source code, if it does not know how to build your project, or if it +does not detect warning or error messages properly, you can [make changes][] in +your [user-init file](#User.Init). + +![Runtime Error](images/runerror.png) + +[make changes]: api.html#_M.Compile.and.Run + +- - - + +# Modules + +- - - + +Most of Textadept's functionality comes from Lua modules loaded on startup. An +example is the [textadept module][] which implements most of Textadept's +functionality (find & replace, key bindings, menus, snippets, etc.) See the +[loading modules](#Loading.Modules) section for instructions on how to load your +own modules on startup. + +Textadept also recognizes a special kind of module: a language module. Language +modules provide functionality specific to their respective programming +languages. + +[textadept module]: api.html#textadept + +## Language Modules + +Language modules have a scope limited to a single programming language. The +module's name matches the language's lexer in the *lexers/* directory. Textadept +automatically loads the module when editing source code in that particular +language. In addition to the source code editing features discussed previously, +these kinds of modules typically also define indentation settings, custom key +bindings, and perhaps a custom context menu. The manual discusses these features +below. + +### Language-Specific Buffer Settings + +Some programming languages have style guidelines for indentation and/or line +endings which differ from Textadept's defaults. In this case, language modules +[set][] these preferences. You can do so manually with your +[preferences](#Language.Module.Preferences). + +[set]: api.html#_M.Buffer.Properties + +### Language-Specific Key Bindings + +Most language modules assign a set of key bindings to [custom commands][]. The +module's [API documentation][] or code lists which key bindings map to which +commands. The `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in curses) key chain prefix +typically houses them. + +[custom commands]: api.html#_M.Commands +[API documentation]: api.html + +### Language-Specific Context Menu + +Some language modules add extra actions to the context menu. Right-click inside +the view to bring up this menu. + +## Getting Modules + +Textadept has a set of officially supported language modules available as a +separate download from the Textadept downloads page with their sources hosted +[here][]. To upgrade to the most recent version of a module, either use +[Mercurial][] (run `hg pull` and then `hg update` on or from within the module) +or download a zipped version from the module's repository homepage and overwrite +the existing one. + +For now, the [wiki][] hosts third-party, user-created modules. + +[here]: http://foicica.com/hg +[Mercurial]: http://mercurial.selenic.com +[wiki]: http://foicica.com/wiki/textadept + +## Installing Modules + +If you do not have write permissions in Textadept's installed location, place +the module in your *~/.textadept/modules/* folder and replace all instances of +`_HOME` with `_USERHOME` in the module's *init.lua*. Putting all custom or +user-created modules in your *~/.textadept/modules/* directory prevents the +possibility of overwriting them when you update Textadept. Also, modules in that +directory override any modules in Textadept's *modules/* directory. This means +that if you have your own *lua* module, Textadept loads that one instead of its +own. + +## Developing Modules + +See the [module API documentation][]. + +[module API documentation]: api.html#_M + +- - - + +# Preferences + +- - - + +At this point the manual assumes you are at least familiar with the basics of +[Lua][]. You do not have to know a lot of the language to configure Textadept. + +[Lua]: http://www.lua.org + +## User Init + +Textadept executes a *~/.textadept/init.lua*, your user-init file, on startup. +If this file does not exist, Textadept creates it for you. This file allows you +to indicate what you want Textadept to do when the application starts. Examples +include changing the settings of existing modules, loading new modules, and +running arbitrary Lua code. + +### Module Preferences + +Try to refrain from modifying the default modules that come with Textadept, even +if you just want to change an option in a generic module, modify the buffer +settings for a language module, edit file types, or add a small bit of custom +code. Upgrading Textadept to a new version may overwrite those changes. Instead +you have two options: load your own module instead of the default one, or run +your custom module code after the default module loads. For the most part, use +the second option because it is simpler and more compatible with future +releases. The manual discusses both options below in the context of generic and +language modules. + +#### Generic Module Preferences + +Many of Textadept's generic modules have configurable settings changeable from +*~/.textadept/init.lua* after Textadept loads the module. The module's +[API documentation][] lists these settings. For example, to disable character +autopairing with typeover and strip trailing whitespace on save, add the +following to your *~/.textadept/init.lua*: + + textadept.editing.AUTOPAIR = false + textadept.editing.TYPEOVER_CHARS = false + textadept.editing.STRIP_TRAILING_SPACES = true + +To always hide the tab bar: + + ui.tabs = false + +Now suppose you want to load all of Textadept's default modules except for the +menu. You cannot do this after-the-fact from *~/.textadept/init.lua*. Instead +you need Textadept to load your own module rather than the default one. Copy the +`textadept` module's *init.lua* (located in the *modules/textadept/* directory) +to *~/.textadept/modules/textadept/* and change + + M.menu = require 'textadept.menu' + +to + + --M.menu = require 'textadept.menu' + +Now when Textadept looks for *modules/textadept/init.lua*, it loads yours in +place of its own, thus loading everything but the menu. If instead you want to +completely change the menu structure, first create a new *menu.lua* and then put +it in *~/.textadept/modules/textadept/*. Textadept now loads your *menu.lua* +rather than its own. + +[API documentation]: api.html + +#### Language Module Preferences + +Similar to generic modules, putting your own language module in +*~/.textadept/modules/* causes Textadept to load that module for editing the +language's code instead of the default one in *modules/* (if the latter exists). +For example, copying the default Lua language module from *modules/lua/* to +*~/.textadept/modules/* results in Textadept loading that module for editing Lua +code in place of its own. However, if you make custom changes to that module and +upgrade Textadept later, the module may no longer be compatible. Rather than +potentially wasting time merging changes, run custom code independent of a +module in the module's *post_init.lua* file. In this case, instead of copying +the `lua` module and creating an `events.LEXER_LOADED` event handler to use +tabs, simply put the event handler in *~/.textadept/modules/lua/post_init.lua*: + + events.connect(events.LEXER_LOADED, function(lang) + if lang == 'lua' then buffer.use_tabs = true end + end) + +Similarly, use *post_init.lua* to change the module's [compile and run][] +commands, load more Autocompletion tags, and add additional +[key bindings](#Key.Bindings) and [snippets](#Snippet.Preferences) (instead of +in *~/.textadept/init.lua*). For example: + + textadept.run.run_commands.lua = 'lua5.2' + _M.lua.tags[#_M.lua.tags + 1] = '/path/to/my/projects/tags' + keys.lua['c\n'] = function() + buffer:line_end() buffer:add_text('end') buffer:new_line() + end + snippets.lua['ver'] = '%<_VERSION>' + +[compile and run]: api.html#_M.Compile.and.Run + +### Loading Modules + +After creating or downloading a generic module called `foo` that you want to +load along with the default modules, simply add the following to your +*~/.textadept/init.lua*: + + foo = require('foo') + +Textadept automatically loads language modules when opening a source file of +that language, so simply installing the language module is sufficient. + +### Key Bindings + +For simple changes to key bindings, *~/.textadept/init.lua* is a good place to +put them. For example, maybe you want `Ctrl+Shift+C` to create a new buffer +instead of `Ctrl+N`: + + keys.cC = buffer.new + keys.cn = nil + +If you plan on redefining most key bindings, copy or create a new *keys.lua* and +put it in *~/.textadept/modules/textadept/* to get Textadept to load your set +instead of its own. Learn more about key bindings and how to define them in the +[key bindings documentation][]. + +[key bindings documentation]: api.html#keys + +### Snippet Preferences + +Define your own global snippets in *~/.textadept/init.lua*, such as: + + snippets['file'] = '%' + snippets['path'] = "%<(buffer.filename or ''):match('^.+[/\\]')>" + +So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX | `Tab` in +curses) inserts the snippet, regardless of the current programming language. +Learn more about snippet syntax in the [snippets documentation][]. + +[snippets documentation]: api.html#textadept.snippets + +### File Types + +Textadept recognizes a wide range of programming language files either by file +extension, by a keyword in the shebang ("#!/path/to/exe") line, or by a +[Lua pattern](#Lua.Patterns) that matches the text of the first line. The editor +does this by consulting a set of tables in [`textadept.file_types`][] that are +modifiable from *~/.textadept/init.lua*. For example: + + -- Recognize .luadoc files as Lua code. + textadept.file_types.extensions.luadoc = 'lua' + -- Change .html files to be recognized as XML files. + textadept.file_types.extensions.html = 'xml' + -- Recognize a shebang line like "#!/usr/bin/zsh" as shell code. + textadept.file_types.shebangs.zsh = 'bash' + +[`textadept.file_types`]: api.html#textadept.file_types + +## Buffer Settings + +Since Textadept runs *~/.textadept/init.lua* only once on startup, it is not the +appropriate place to set per-buffer properties (like indentation size) or +view-related properties (like the behaviors for scrolling and autocompletion). +If you do set such properties in *~/.textadept/init.lua*, those settings only +apply to the first buffer and view -- subsequent buffers and split views will +not inherit those settings. Instead, put your settings in a +*~/.textadept/properties.lua* file which runs after creating a new buffer or +split view. Any settings there override Textadept's default *properties.lua* +settings. For example, to use tabs rather than spaces and have a tab size of 4 +spaces by default, your *~/.textadept/properties.lua* would contain: + + buffer.use_tabs = true + buffer.tab_width = 4 + +(Remember that in order to have per-filetype properties, you need to have a +[language module](#Language-Specific.Buffer.Settings).) + +Textadept's *properties.lua* is a good "quick reference" for configurable +properties. It also has many commented out properties that you can copy to your +*~/.textadept/properties.lua* and uncomment to turn on or change the value of. +You can view a property's documentation by pressing `Ctrl+H` (`^H` on Mac OSX | +`M-H` or `M-S-H` in curses) or by reading the [buffer API documentation][]. + +[buffer API documentation]: api.html#buffer + +## Locale Preference + +Textadept attempts to auto-detect your locale settings using the "$LANG" +environment variable, falling back on the English locale. To set the locale +manually, copy the desired locale file from the *core/locales/* folder to +*~/.textadept/locale.conf*. If Textadept does not support your language yet, +please translate the English messages in *core/locale.conf* to your language and +send the modified *locale.conf* file to [me][]. I will include it in a future +release. + +[me]: README.html#Contact + +- - - + +# Themes + +- - - + +Themes customize Textadept's look and feel. The editor's built-in themes are +"light", "dark", and "term". The GUI version uses "light" as its default and the +terminal version uses "term". + + + +![Light Theme](images/lighttheme.png) +   +![Dark Theme](images/darktheme.png) +   +![Term Theme](images/termtheme.png) + +Each theme is a single Lua file. It contains color and style definitions for +displaying syntactic elements like comments, strings, and keywords in +programming language source files. These [definitions][] apply universally to +all programming language elements, resulting in a single, unified theme. Themes +also set view-related editor properties like caret and selection colors. + +Note: The only colors that the terminal version of Textadept recognizes are the +standard black, red, green, yellow, blue, magenta, cyan, white, and bold +variants of those colors. Your terminal emulator's settings determine how to +display these standard colors. + +[definitions]: api.html#lexer.Styles.and.Styling + +## Setting Themes + +Override the default theme in your [*~/.textadept/init.lua*](#User.Init) using +the [`ui.set_theme()`][] function. For example: + + ui.set_theme(not CURSES and 'dark' or 'custom_term') + +Either restart Textadept for changes to take effect or type [`reset()`][] in the +[command entry](#Lua.Command.Entry). + +[`ui.set_theme()`]: api.html#ui.set_theme +[`reset()`]: api.html#reset + +## Customizing Themes + +Like with modules, try to refrain from editing Textadept's default themes. +Instead, put custom or downloaded themes in your *~/.textadept/themes/* +directory. Doing this not only prevents you from overwriting your themes when +you update Textadept, but causes the editor to load your themes instead of the +default ones in *themes/*. For example, having your own *light.lua* theme +results in Textadept loading that theme in place of its own. + +There are two ways to go about customizing themes. You can create a new one from +scratch or tweak an existing one. Creating a new one is straightforward -- all +you need to do is define a set of colors and a set of styles. Just follow the +example of existing themes. If instead you want to use an existing theme like +"light" but only change the font face and font size, you have two options: call +[`ui.set_theme()`][] from your *~/.textadept/init.lua* with additional +parameters, or create an abbreviated *~/.textadept/themes/light.lua* using Lua's +`dofile()` function. For example: + + -- File *~/.textadept/init.lua* + ui.set_theme('light', {font = 'Monospace', fontsize = 12}) + + -- File *~/.textadept/themes/light.lua* + dofile(_HOME..'/themes/light.lua') + buffer.property['font'] = 'Monospace' + buffer.property['fontsize'] = 12 + +Either one loads Textadept's "light" theme, but applies your font preferences. +The same techniques work for tweaking individual theme colors and/or styles, but +managing more changes is probably easier with the latter. + +[`ui.set_theme()`]: api.html#ui.set_theme + +### Language-specific Themes + +Textadept also allows you to customize themes per-language through the +`events.LEXER_LOADED` event. For example, changing the color of functions in +Java from orange to black in the "light" theme looks like this: + + events.connect(events.LEXER_LOADED, function(lang) + if lang == 'java' then + buffer.property['style.function'] = 'fore:%(color.light_black)' + end + end) + +## GUI Theme + +There is no way to theme GUI controls like text fields and buttons from within +Textadept. Instead, use [GTK+ Resource files][]. The "GtkWindow" name is +"textadept". For example, style all text fields with a "textadept-entry-style" +like this: + + widget "textadept*GtkEntry*" style "textadept-entry-style" + +[GTK+ Resource files]: http://library.gnome.org/devel/gtk/stable/gtk-Resource-Files.html + +## Getting Themes + +For now, the [wiki][] hosts third-party, user-created themes. The classic +"dark", "light", and "scite" themes prior to version 4.3 are there too. + +[wiki]: http://foicica.com/wiki/textadept + +- - - + +# Advanced + +- - - + +## Lua Command Entry + +The command entry grants access to Textadept's Lua state. Press `Ctrl+E` (`⌘E` +on Mac OSX | `M-C` in curses) to display the entry. It is useful for debugging, +inspecting, and entering `buffer` or `view` commands. If you try to cause +instability in Textadept's Lua state, you will probably succeed so be careful. +The [Lua API][] lists available commands. The command entry provides abbreviated +commands for [`buffer`][], [`view`][] and [`ui`][]: you may reduce the +`buffer:append_text('foo')` command to `append_text('foo')`. Therefore, use +`_G.print()` for Lua's `print()` since `print()` expands to [`ui.print()`][]. +These commands are runnable on startup using the `-e` and `--execute` command +line switches. + +![Command Entry](images/commandentry.png) + +[Lua API]: api.html +[`buffer`]: api.html#buffer +[`view`]: api.html#view +[`ui`]: api.html#ui +[`ui.print()`]: api.html#ui.print + +### Command Entry Tab Completion + +The command entry also provides tab-completion for functions, variables, tables, +etc. Press the `Tab` (`⇥` on Mac OSX | `Tab` in curses) key to display a list of +available completions. Use the arrow keys to make a selection and press `Enter` +(`↩` | `Enter`) to insert it. + +![Command Completion](images/commandentrycompletion.png) + +### Extending the Command Entry + +Executing Lua commands is just one of the many tools the command entry functions +as. For example, *modules/textadept/find.lua* and *modules/textadept/keys.lua* +extend it to implement [incremental search][]. + +[incremental search]: api.html#ui.find.find_incremental + +## Command Selection + +If you did not disable the menu in your [preferences](#User.Init), then pressing +`Ctrl+Shift+E` (`⌘⇧E` on Mac OSX | `M-S-C` in curses) brings up the command +selection dialog. Typing part of any command filters the list, with spaces being +wildcards. This is an easy way to run commands without navigating the menus, +using the mouse, or remembering key bindings. It is also useful for looking up +particular key bindings quickly. Note: the key bindings in the dialog do not +look like those in the menu. Textadept uses this different notation internally. +Learn more about it in the [keys API documentation][]. + +[keys API documentation]: api.html#keys + +## Shell Commands and Filtering Text + +Sometimes using an existing shell command to manipulate text is easier than +using the command entry. An example would be sorting all text in a buffer (or a +selection). One way to do this from the command entry is: + + ls={}; for l in buffer:get_text():gmatch('[^\n]+') do ls[#ls+1]=l end; + table.sort(ls); buffer:set_text(table.concat(ls, '\n')) + +A simpler way is pressing `Ctrl+|` (`⌘|` on Mac OSX | `^\` in curses), entering +the shell command `sort`, and pressing `Enter` (`↩` | `Enter`). + +This feature determines the standard input (stdin) for shell commands as +follows: + +* If text is selected and spans multiple lines, all text on the lines containing + the selection is used. However, if the end of the selection is at the + beginning of a line, only the EOL (end of line) characters from the previous + line are included as input. The rest of the line is excluded. +* If text is selected and spans a single line, only the selected text is used. +* If no text is selected, the entire buffer is used. + +The standard output (stdout) of the command replaces the input text. + +## Remote Control + +Since Textadept executes arbitrary Lua code passed via the `-e` and `--execute` +command line switches, a side-effect of [single instance](#Single.Instance) +functionality on the platforms that support it is that you can remotely control +the original instance. For example: + + ta ~/.textadept/init.lua & + ta -e "events.emit(events.FIND, 'require')" + +- - - + +# Scripting + +- - - + +Since Textadept is entirely scriptable with Lua, the editor has superb support +for editing Lua code. Textadept provides syntax autocompletion and documentation +for the Lua and Textadept APIs. The [`lua` module][] also has more tools for +working with Lua code. + +![ta Autocompletion](images/adeptsense_ta.png) +     +![ta Documentation](images/adeptsense_tadoc.png) + +[`lua` module]: api.html#_M.lua + +## LuaDoc and Examples + +Textadept's API is heavily documented. The [API documentation][] is the ultimate +resource on scripting Textadept. There are of course abundant scripting examples +since the editor's internals consist primarily of Lua. + +[API documentation]: api.html + +### Generating LuaDoc + +Generate Textadept-like API documentation for your own modules using the +*doc/markdowndoc.lua* [LuaDoc][] module (you must have [Discount][] installed): + + luadoc -d . [-t template_dir] --doclet _HOME/doc/markdowndoc [module(s)] + +where `_HOME` is the path where you installed Textadept and `template_dir` is an +optional template directory that contains two Markdown files: *.header.md* and +*.footer.md*. (See *doc/.header.md* and *doc/.footer.md* for examples.) LuaDoc +creates an *api/* directory in the current directory that contains the generated +API documentation HTML files. + +[LuaDoc]: http://keplerproject.github.com/luadoc/ +[Discount]: http://www.pell.portland.or.us/~orc/Code/discount/ + +## Lua Configuration + +Textadept contains its own copy of [Lua 5.2][] which has the same configuration +(*luaconf.h*) as vanilla Lua with the following exceptions: + +* `TA_LUA_PATH` and `TA_LUA_CPATH` replace the `LUA_PATH` and `LUA_CPATH` + environment variables. +* `LUA_ROOT` is "/usr/" in Linux systems instead of "/usr/local/". +* `LUA_PATH` and `LUA_CPATH` do not have "./?.lua" and "./?.so" in them. +* No Lua 5.1 compatibility flags are set. + +[Lua 5.2]: http://www.lua.org/manual/5.2/ + +### LuaJIT + +Even though Textadept runs with [LuaJIT][], LuaJIT does not fully support +Lua 5.2. Therefore, try to write your modules and scripts to be compatible with +both versions. For the most part, LuaJIT only lacks Lua 5.2's new `_ENV`. + +[LuaJIT]: http://luajit.org + +## Scintilla + +Textadept uses the [Scintilla][] editing component. The [buffer][] part of +Textadept's API emulates the [Scintilla API][] so porting any C/C++ Scintilla +calls to Lua should not be difficult. + +[Scintilla]: http://scintilla.org +[buffer]: api.html#buffer +[Scintilla API]: http://scintilla.org/ScintillaDoc.html + +## Textadept Structure + +Because Textadept consists mainly of Lua, its Lua scripts have to be stored in +an organized folder structure. + +### The *core* Directory + +The *core/* directory contains Textadept's core Lua modules. These modules are +essential for the application to run. They provide Textadept's Lua to C +interface, event structure, file interactions, and localization. + +### The *lexers* Directory + +Lexer modules analyze source code for syntax highlighting. *lexers/* houses +them. + +### The *modules* Directory + +*modules/* contains generic and language modules for editing text and source +code. + +### The *themes* Directory + +*themes/* has built-in themes that customize the look and feel of Textadept. + +### The User Directory + +The *~/.textadept/* folder houses your preferences, Lua modules, themes, and +user-data. This folder may contain *lexers/*, *modules/*, and *themes/* +sub-directories. + +### GTK+ Directories + +GTK+ uses the *etc/*, *lib/*, and *share/* directories, which only appear in the +Win32 and Mac OSX packages. + +- - - + +# Compiling + +- - - + +## Requirements + +Unfortunately, the requirements for building Textadept are not quite as minimal +as running it. + +### Requirements for Linux and BSD + +First, Linux and BSD systems need the [GNU C compiler][] (*gcc*) and +[GNU Make][] (*make*). BSD users additionally need to have [libiconv][] +installed. These should be available for your distribution through a package +manager. For example, Ubuntu includes these tools in the "build-essential" +package. + +Next, the GUI version of Textadept requires the GTK+ development libraries. +Again, your package manager should allow you to install them. Debian-based Linux +distributions like Ubuntu typically call the package "libgtk2.0-dev". Otherwise, +compile and install GTK+ from the [GTK+ website][]. + +The optional terminal version of Textadept depends on the development library +for a curses implementation like ncurses. Similarly, your package manager should +provide one. Debian-based Linux distributions like Ubuntu typically call the +ncurses package "libncurses5-dev". Otherwise, compile and install ncurses from +the [ncurses website][]. Note: you need the wide-character development version +of ncurses installed, which handles multibyte sequences. (Therefore, Debian +users _also_ need "libncursesw5-dev".) + +[GNU C compiler]: http://gcc.gnu.org +[GNU Make]: http://www.gnu.org/software/make/ +[libiconv]: http://www.gnu.org/software/libiconv/ +[GTK+ website]: http://www.gtk.org/download/linux.php +[ncurses website]: http://invisible-island.net/ncurses/#download_ncurses + +### Requirements for Windows + +Compiling Textadept on Windows is no longer supported. The preferred way to +compile for Windows is cross-compiling from Linux. To do so, you need [MinGW][] +with the Windows header files. Your package manager should offer them. + +Note: compiling on Windows requires a C compiler that supports the C99 standard, +the [GTK+ for Windows bundle][] (2.24 is recommended), and +[libiconv for Windows][] (the "Developer files" and "Binaries" zip files). The +terminal (pdcurses) version requires my [win32curses bundle][] instead of GTK+ +and libiconv. + +[MinGW]: http://mingw.org +[GTK+ for Windows bundle]: http://www.gtk.org/download/win32.php +[libiconv for Windows]: http://gnuwin32.sourceforge.net/packages/libiconv.htm +[win32curses bundle]: download/win32curses.zip + +### Requirements for Mac OSX + +Compiling Textadept on Mac OSX is no longer supported. The preferred way is +cross-compiling from Linux. To do so, you need the [Apple Cross-compiler][] +binaries. + +[Apple Cross-compiler]: https://launchpad.net/~flosoft/+archive/cross-apple + +## Compiling + +### Compiling on Linux and BSD + +For Linux and BSD systems, simply run `make deps` in the *src/* directory to +prepare the build environment followed by `make` to build the *textadept* and +*textadeptjit* executables in the root directory. Make a symlink from them to +*/usr/bin/* or elsewhere in your `PATH`. + +Similarly, `make curses` builds *textadept-curses* and *textadeptjit-curses*. + +Note: you may have to run + + make CFLAGS="-I/usr/local/include" \ + CXXFLAGS="-I/usr/local/include -L/usr/local/lib" + +if the prefix where any dependencies are installed is */usr/local/* and your +compiler flags do not include them by default. + +#### Installing on Linux and BSD + +Textadept is self-contained, meaning you do not have to install it, and runs +from its current location. Should you choose to install Textadept like a normal +Linux application, run `make deps` and then the usual `make` and `make install` +or `sudo make install` commands depending on your privileges. The default prefix +is */usr/local* but setting `DESTDIR` (e.g. +`make install DESTDIR=/prefix/to/install/to`) changes it. + +Similarly, `make curses` and `make curses install` installs the curses version. + +### Cross Compiling for Windows + +When cross-compiling from within Linux, first make a note of your MinGW +compiler names. You may have to either modify the `CROSS` variable in the +"win32" block of *src/Makefile* or append something like "CROSS=i486-mingw32-" +when running `make`. After considering your MinGW compiler names, run +`make win32-deps` or `make CROSS=i486-mingw32- win32-deps` to prepare the build +environment followed by `make win32` or `make CROSS=i486-mingw32- win32` to +build *../textadept.exe* and *../textadeptjit.exe*. Finally, copy the dll files +from *src/win32gtk/bin/* to the directory containing the Textadept executables. + +Similarly for the terminal version, run `make win32-curses` or its variant as +suggested above to build *../textadept-curses.exe* and +*../textadeptjit-curses.exe*. + +Please note the build process produces a *lua51.dll* for _only_ +*textadeptjit.exe* and *textadeptjit-curses.exe* because limitations on external +Lua library loading do not allow statically linking LuaJIT to Textadept. + +### Cross Compiling for Mac OSX + +When cross-compiling from within Linux, run `make osx-deps` to prepare the build +environment followed by `make osx` to build *../textadept.osx* and +*../textadeptjit.osx*. + +Similarly, `make osx-curses` builds *../textadept-curses.osx* and +*../textadeptjit-curses.osx*. + +Build a new *Textadept.app* with `make osx-app`. + +#### Compiling on OSX (Legacy) + +Textadept requires [XCode][] as well as [jhbuild][] (for GTK+). After building +"meta-gtk-osx-bootstrap" and "meta-gtk-osx-core", build "meta-gtk-osx-themes". +Note that the entire compiling process can easily take 30 minutes or more and +ultimately consume nearly 1GB of disk space. + +After using *jhbuild*, GTK+ is in *~/gtk/* so make a symlink from *~/gtk/inst* +to *src/gtkosx* in Textadept. Then open *src/Makefile* and uncomment the +"Darwin" block. Finally, run `make osx` to build *../textadept.osx* and +*../textadeptjit.osx*. + +Note: to build a GTK+ for OSX bundle, run the following from the *src/* +directory before zipping up *gtkosx/include/* and *gtkosx/lib/*: + + sed -i -e 's|libdir=/Users/username/gtk/inst/lib|libdir=${prefix}/lib|;' \ + gtkosx/lib/pkgconfig/*.pc + +where `username` is your username. + +Compiling the terminal version is not so expensive and requires no additional +libraries. After uncommenting the "Darwin" block mentioned above, simply run +`make osx-curses` to build *../textadept-curses.osx* and +*../textadeptjit-curses.osx*. + +[XCode]: http://developer.apple.com/TOOLS/xcode/ +[jhbuild]: http://sourceforge.net/apps/trac/gtk-osx/wiki/Build + +### Notes on LuaJIT + +[LuaJIT][] is a Just-In-Time Compiler for Lua and can boost the speed of Lua +programs. I have noticed that syntax highlighting can be up to 2 times faster +with LuaJIT than with vanilla Lua. This difference is largely unnoticable on +modern computers and usually only discernable when initially loading large +files. Other than syntax highlighting, LuaJIT offers no real benefit +performance-wise to justify it being Textadept's default runtime. LuaJIT's +[ffi library][], however, appears to be useful for interfacing with external, +non-Lua, libraries. + +[LuaJIT]: http://luajit.org +[ffi library]: http://luajit.org/ext_ffi.html + +### Notes on CDK + +[CDK][] is a library of curses widgets. The terminal version of Textadept +includes a slightly modified, stripped down version of this library. The changes +made to CDK are in *src/cdk.patch* and listed as follows: + +* Excluded the following source files: *alphalist.c*, *calendar.c*, + *cdk_compat.{c,h}*, *cdk_test.h*, *dialog.c*, *{d,f}scale.{c,h}*, + *fslider.{c,h}*, *gen-{scale,slider}.{c,h}*, *get_index.c*, *get_string.c*, + *graph.c*, *histogram.c*, *marquee.c*, *matrix.c*, *popup_dialog.c*, + *radio.c*, *scale.{c,h}*, *slider.{c,h}*, *swindow.c*, *template.c*, + *u{scale,slider}.{c,h}*, *view_{file,info}.c*, and *viewer.c*. +* *cdk.h* does not `#include` "matrix.h", "viewer.h", and any headers labeled + "Generated headers" due to their machine-dependence. It also `#define`s + `boolean` as `CDKboolean` on Windows platforms since the former is already + `typedef`ed. +* *cdk_config.h* no longer defines `HAVE_SETLOCALE` since Textadept handles + locale settings, no longer defines `HAVE_NCURSES_H` and `NCURSES` since + Textadept supports multiple curses implementations (not just ncurses), + conditionally enables `HAVE_GRP_H`, `HAVE_LSTAT`, and `HAVE_PWD_H` definitions + on \*nix platforms since Windows does not have them, and explicitly undefines + `NCURSES_OPAQUE` since newer versions of ncurses on Mac OSX define it. +* *cdk_util.h* `#define`s `Beep` as `CDKBeep` on Windows platforms since Windows + already defines Beep. +* The `baseName` and `dirName` functions in *cdk.c* recognize Window's '\' + directory separator. +* Deactivated the `deleteFileCB` function in *fselect.c*. + +[CDK]: http://invisible-island.net/cdk/ + +- - - + +# Help + +- - - + +## Command Line Parameters + +Passing `-h` or `--help` to Textadept shows a list of available command line +parameters. + +Switch |Arguments|Description +-------------------|:-------:|----------- +`-e`, `--execute` | 1 |Run Lua [code](#Lua.Command.Entry). +`-f`, `--force` | 0 |Forces [unique instance](#Single.Instance). +`-h`, `--help` | 0 |Shows this. +`-n`, `--nosession`| 0 |No [session](#Sessions) functionality. +`-s`, `--session` | 1 |Loads [session](#Sessions) on startup. +`-u`, `--userhome` | 1 |Sets alternate [`_USERHOME`][]. + +Textadept curses does not support the help switch. + +[`_USERHOME`]: api.html#_USERHOME + +## Online Help + +Textadept has a [mailing list][] and a [wiki][]. + +[mailing list]: http://foicica.com/lists +[wiki]: http://foicica.com/wiki/textadept + +- - - + +# Appendix + +- - - + +## Lua Patterns + +The following is from the [Lua 5.2 Reference Manual][]. + +_Character Class:_ + +A character class is used to represent a set of characters. The following +combinations are allowed in describing a character class: + +* **_`x`_:** (where _x_ is not one of the magic characters `^%()%.[]*+-?`) + represents the character _x_ itself. +* **`.`:** (a dot) represents all characters. +* **`%a`:** represents all letters. +* **`%c`:** represents all control characters. +* **`%d`:** represents all digits. +* **`%g`:** represents all printable characters except space. +* **`%l`:** represents all lowercase letters. +* **`%p`:** represents all punctuation characters. +* **`%s`:** represents all space characters. +* **`%u`:** represents all uppercase letters. +* **`%w`:** represents all alphanumeric characters. +* **`%x`:** represents all hexadecimal digits. +* **`%`_`x`_:** (where _x_ is any non-alphanumeric character) represents the + character _x_. This is the standard way to escape the magic characters. Any + punctuation character (even the non magic) can be preceded by a '`%`' when + used to represent itself in a pattern. +* **`[set]`:** represents the class which is the union of all characters in set. + A range of characters can be specified by separating the end characters of the + range with a '`-`'. All classes `%`_x_ described above can also be used as + components in set. All other characters in set represent themselves. For + example, `[%w_]` (or `[_%w]`) represents all alphanumeric characters plus the + underscore, `[0-7]` represents the octal digits, and `[0-7%l%-]` represents + the octal digits plus the lowercase letters plus the '`-`' character. +

+ The interaction between ranges and classes is not defined. Therefore, patterns + like `[%a-z]` or `[a-%%]` have no meaning. +* **`[^set]`:** represents the complement of _set_, where _set_ is interpreted + as above. + +For all classes represented by single letters (`%a`, `%c`, etc.), the +corresponding uppercase letter represents the complement of the class. For +instance, `%S` represents all non-space characters. + +The definitions of letter, space, and other character groups depend on the +current locale. In particular, the class `[a-z]` may not be equivalent to `%l`. + +_Pattern Item:_ + +A _pattern item_ can be + +* a single character class, which matches any single character in the class; +* a single character class followed by '`*`', which matches 0 or more + repetitions of characters in the class. These repetition items will always + match the longest possible sequence; +* a single character class followed by '`+`', which matches 1 or more + repetitions of characters in the class. These repetition items will always + match the longest possible sequence; +* a single character class followed by '`-`', which also matches 0 or more + repetitions of characters in the class. Unlike '`*`', these repetition items + will always match the _shortest_ possible sequence; +* a single character class followed by '`?`', which matches 0 or 1 occurrence of + a character in the class; +* `%n`, for _n_ between 1 and 9; such item matches a substring equal to the + _n_-th captured string (see below); +* `%bxy`, where _x_ and _y_ are two distinct characters; such item matches + strings that start with _x_, end with _y_, and where the _x_ and _y_ are + balanced. This means that, if one reads the string from left to right, + counting +_1_ for an _x_ and -_1_ for a _y_, the ending _y_ is the first _y_ + where the count reaches 0. For instance, the item `%b()` matches expressions + with balanced parentheses. +* `%f[set]`, a _frontier pattern_; such item matches an empty string at any + position such that the next character belongs to _set_ and the previous + character does not belong to _set_. The set _set_ is interpreted as previously + described. The beginning and the end of the subject are handled as if they + were the character `'\0'`. + +_Pattern:_ + +A _pattern_ is a sequence of pattern items. A '`^`' at the beginning of a +pattern anchors the match at the beginning of the subject string. A '`$`' at the +end of a pattern anchors the match at the end of the subject string. At other +positions, '`^`' and '`$`' have no special meaning and represent themselves. + +_Captures:_ + +A pattern can contain sub-patterns enclosed in parentheses; they describe +_captures_. When a match succeeds, the substrings of the subject string that +match captures are stored (_captured_) for future use. Captures are numbered +according to their left parentheses. For instance, in the pattern +`"(a*(.)%w(%s*))"`, the part of the string matching `"a*(.)%w(%s*)"` is stored +as the first capture (and therefore has number 1); the character matching "`.`" +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 + +## Curses Compatibility + +Textadept 5.5 beta introduced a curses version that is capable of running in a +terminal emulator. However, it lacks some GUI features due to curses' +non-existant graphics capabilities: + +* No alpha values or transparency. +* No images in autocompletion lists. Instead, autocompletion lists show the + first character in the string passed to [`buffer.register_image()`][]. +* No buffered or two-phase drawing. +* No arrows on call tips. +* Carets cannot have a period, line style, or width. +* Edge lines may be obscured by text. +* Extra line ascent or descent renders improperly. +* No fold lines. +* No indentation guides. +* No indicators other than `INDIC_ROUNDBOX` and `INDIC_STRAIGHTBOX`, although + neither has translucent drawing and `INDIC_ROUNDBOX` does not have rounded + corners. +* When scrolling to the right, long lines overwrite margins. +* No marker symbols other than `MARK_CHARACTER`. +* No mouse interactions, cursor types, or hotspots. +* Only up to 16 colors recognized, regardless of how many colors the terminal + supports. They are: black (`0x000000`), red (`0x800000`), green (`0x008000`), + yellow (`0x808000`), blue (`0x000080`), magenta (`0x800080`), cyan + (`0x008080`), white (`0xC0C0C0`), light black (`0x404040`), light red + (`0xFF0000`), light green (`0x00FF00`), light yellow (`0xFFFF00`), light blue + (`0x0000FF`), light magenta (`0xFF00FF`), light cyan (`0x00FFFF`), and light + white (`0xFFFFFF`). Even if your terminal uses a different color map, you must + use these color values. Your terminal will remap them automatically. + Unrecognized colors default to white. For some terminals, you may need to set + a lexer style's `bold` attribute to use the light color variant. +* No scroll bars. +* Not all key sequences recognized properly. +* No style settings like font name, font size, or italics. +* No tab character arrows when viewing whitespace. +* No visual wrap flags. +* No X selection, primary or secondary, integration with the clipboard. +* No zoom. + +[`buffer.register_image()`]: api.html#buffer.register_image + +## Migration Guides + +### Textadept 6 to 7 + +Textadept 7 introduces API changes, a change in module mentality and filename +encodings, and a completely new theme implementation. + +#### API Changes + +Old API |Change |New API +----------------------------------|:------:|------- +**_G** | | +RESETTING |Removed |N/Aa +buffer\_new() |Renamed |\_G.[buffer.new()][] +**_M.textadept** |Renamed |[textadept][] +filter\_through |Removed |N/A +filter\_through.filter\_through() |Renamed |editing.[filter\_through()][] +mime\_types |Renamed |[file\_types][]b +**_M.textadept.bookmark** | | +N/A |New |[goto\_mark()][] +N/A |New |[MARK\_BOOKMARK][] +MARK\_BOOKMARK\_COLOR |Removed |N/Ac +goto\_bookmark |Replaced|goto\_mark() +goto\_next |Replaced|goto\_mark(true) +goto\_prev |Replaced|goto\_mark(false) +**_M.textadept.editing** | | +N/A |New |[INDIC\_BRACEMATCH][] +N/A |New |[INDIC\_HIGHLIGHT][] +INDIC\_HIGHLIGHT\_BACK |Removed |N/Ad +autocomplete\_word(chars, default)|Changed |[autocomplete\_word][](default) +grow\_selection() |Replaced|[select\_enclosed()][] +**_M.textadept.menu** | | +menubar |Removed |N/A +contextmenu |Removed |N/A +**_M.textadept.run** | | +N/A |New |[MARK\_WARNING][] +N/A |New |[MARK\_ERROR][] +MARK\_ERROR\_BACK |Removed |N/Ac +compile\_command |Renamed |[compile\_commands][] +run\_command |Renamed |[run\_commands][] +error\_detail |Renamed |[error\_patterns][]e +**_M.textadept.snapopen** |Removed |N/A +open |Changed |\_G.[io.snapopen()][]f +**_SCINTILLA.constants** | | +SC\_\* |Renamed |Removed "SC\_" prefix. +SC(FIND\|MOD\|VS\|WS) |Renamed |Removed "SC" prefix. +**buffer** | | +check\_global() |Removed | +get\_style\_name(buffer, n) |Renamed |[style\_name][]\[n\] +reload() |Renamed |[io.reload\_file()][] +save() |Renamed |[io.save\_file()][] +save\_as() |Renamed |[io.save\_file\_as()][] +close() |Renamed |[io.close\_buffer()][] +set\_encoding() |Renamed |[io.set\_buffer\_encoding()][] +convert\_eo\_ls() |Renamed |[buffer.convert\_eols()][] +dirty |Replaced|[buffer.modify][] +**events** | | +N/A |New |[INITIALIZED][] +handlers |Removed |N/A +**gui** |Renamed |[ui][] +docstatusbar\_text |Renamed |[bufstatusbar\_text][] +N/A |New |[maximized][] +find.goto\_file\_in\_list() |Renamed |find.[goto\_file\_found()][] +select\_theme |Removed |N/A +N/A |New |[dialogs][] +filteredlist |Removed |N/A +set\_theme(name, ...) |Changed |[set\_theme][](name, table) +**io** | | +try\_encodings |Renamed |[encodings][] +open\_file(string) |Changed |[open\_file][](string or table) +snapopen(string, ...) |Changed |[snapopen][](string or table, ...) +save\_all() |Renamed |[save\_all\_files()][] +close\_all() |Renamed |[close\_all\_buffers()][] + +a`arg` is `nil` when resetting. + +bRemoved *mime_types.conf* files. Interact with Lua tables directly. + +cSet [`buffer.marker_back`][] in [`events.VIEW_NEW`][]. + +dSet [`buffer.indic_fore`][] in [`events.VIEW_NEW`][]. + +eChanged structure too. + +fChanged arguments too. + +[buffer.new()]: api.html#buffer.new +[textadept]: api.html#textadept +[filter\_through()]: api.html#textadept.editing.filter_through +[file\_types]: api.html#textadept.file_types +[goto\_mark()]: api.html#textadept.bookmarks.goto_mark +[MARK\_BOOKMARK]: api.html#textadept.bookmarks.MARK_BOOKMARK +[INDIC\_BRACEMATCH]: api.html#textadept.editing.INDIC_BRACEMATCH +[INDIC\_HIGHLIGHT]: api.html#textadept.editing.INDIC_HIGHLIGHT +[autocomplete\_word]: api.html#textadept.editing.autocomplete_word +[select\_enclosed()]: api.html#textadept.editing.select_enclosed +[MARK\_WARNING]: api.html#textadept.run.MARK_WARNING +[MARK\_ERROR]: api.html#textadept.run.MARK_ERROR +[compile\_commands]: api.html#textadept.run.compile_commands +[run\_commands]: api.html#textadept.run.run_commands +[error\_patterns]: api.html#textadept.run.error_patterns +[io.snapopen()]: api.html#io.snapopen +[style\_name]: api.html#buffer.style_name +[io.reload\_file()]: api.html#io.reload_file +[io.save\_file()]: api.html#io.save_file +[io.save\_file\_as()]: api.html#io.save_file_as +[io.close\_buffer()]: api.html#io.close_buffer +[io.set\_buffer\_encoding()]: api.html#buffer.set_encoding +[buffer.convert\_eols()]: api.html#buffer.convert_eols +[buffer.modify]: api.html#buffer.modify +[INITIALIZED]: api.html#events.INITIALIZED +[ui]: api.html#ui +[bufstatusbar\_text]: api.html#ui.bufstatusbar_text +[maximized]: api.html#ui.maximized +[goto\_file\_found()]: api.html#ui.find.goto_file_found +[dialogs]: api.html#ui.dialogs +[set\_theme]: api.html#ui.set_theme +[encodings]: api.html#io.encodings +[open\_file]: api.html#io.open_file +[snapopen]: api.html#io.snapopen +[save\_all\_files()]: api.html#io.save_all_files +[close\_all\_buffers()]: api.html#io.close_all_buffers +[`buffer.marker_back`]: api.html#buffer.marker_back +[`events.VIEW_NEW`]: api.html#events.VIEW_NEW +[`buffer.indic_fore`]: api.html#buffer.indic_fore + +#### Module Mentality + +Prior to Textadept 7, the `_M` table held all loaded modules (regardless of +whether they were generic modules or language modules) and Textadept encouraged +users to load custom modules into `_M` even though Lua has no such restriction. +The `_M` prefix no longer makes much sense for generic modules like +[`textadept`][], so only language modules are automatically loaded into +[`_M`][]. Textadept 7 does not encourage any prefix for custom, generic modules; +the user is free to choose. + +[`textadept`]: api.html#textadept +[`_M`]: api.html#_M + +#### Filename Encodings + +Prior to Textadept 7, `buffer.filename` was encoded in UTF-8 and any functions +that accepted filenames (such as `io.open_file()`) required the filenames to +also be encoded in UTF-8. This is no longer the case in Textadept 7. +`buffer.filename` is encoded in `_CHARSET` and any filenames passed to functions +should also remain encoded in `_CHARSET`. No more superfluous encoding +conversions. You should only convert to and from UTF-8 when displaying or +retrieving displayed filenames from buffers and/or dialogs. + +#### Theme Changes + +You can use the following as a reference for converting your Textadept 6 themes +to Textadept 7: + + -- File *theme/lexer.lua* | -- File *theme.lua* + -- Textadept 6 | -- Textadept 7 + local l = lexer | local buffer = buffer + local color = l.color | local prop = buffer.property + local style = l.style | local prop_int = + | buffer.property_int + | + l.colors = { | + ... | ... + red = color('99', '4D', '4D'), | prop['color.red'] = 0x4D4D99 + yellow = color('99', '99', '4D'), | prop['color.yellow'] = 0x4D9999 + ... | ... + } | + | + l.style_nothing = style{} | prop['style.nothing'] = '' + l.style_class = style{ | prop['style.class'] = + fore = l.colors.yellow | 'fore:%(color.yellow)' + } | ... + ... | prop['style.identifier'] = + l.style_identifier = l.style_nothing | '%(style.nothing)' + | + ... | ... + | + | prop['font'] = 'Monospace' + local font, size = 'Monospace', 10 | prop['fontsize'] = 10 + l.style_default = style{ | prop['style.default'] = + font = font, size = size, | 'font:%(font),'.. + fore = l.colors.light_black | 'size:%(fontsize),'.. + back = l.colors.white | 'fore:%(color.light_black),'.. + } | 'back:%(color.white)' + ... | ... + + -- File *theme/view.lua* | -- Same file *theme.lua*! + | + ... | ... + -- Caret and Selection Styles. | -- Caret and Selection Styles. + buffer:set_sel_fore(true, 0x333333) | buffer:set_sel_fore(true, + | prop_int['color.light_black']) + buffer:set_sel_back(true, 0x999999) | buffer:set_sel_back(true, + | prop_int['color.light_grey']) + --buffer.sel_alpha = | --buffer.sel_alpha = + --buffer.sel_eol_filled = true | + buffer.caret_fore = 0x4D4D4D | buffer.caret_fore = + | prop_int['color.grey_black'] + ... | ... + +Notes: + +1. Textadept 7's themes share its Lua state and set lexer colors and styles + through named buffer properties. +2. Convert colors from "RRGGBB" string format to the "0xBBGGRR" number format + that Textadept's API documentation uses consistently. +3. The only property names that matter are the "style._name_" ones. Other + property names are arbitrary. +4. Instead of using variables, which are evaluated immediately, use "%(key)" + notation, which substitutes the value of property "key" at a later point in + time. This means you do not have to define properties before use. You can + also modify existing properties without redefining the properties that depend + on them. See the [customizing themes](#Customizing.Themes) section for an + example. +5. Set view properties related to colors directly in *theme.lua* now instead of + a separate *view.lua*. You may use color properties defined earlier. Try to + refrain from setting properties like `buffer.sel_eol_filled` which belong in + a [*properties.lua*](#Buffer.Settings) file. +6. The separate *buffer.lua* is gone. Use [*properties.lua*](#Buffer.Settings) + or a [language module](#Language-Specific.Buffer.Settings). + +##### Theme Preference + +Textadept 7 ignores the *~/.textadept/theme* and *~/.textadept/theme_term* files +that specified your preferred Textadept 6 theme. Use *~/.textadept/init.lua* to +[set a preferred theme](#Setting.Themes) instead. For example, if you had custom +GUI and terminal themes: + + -- File *~/.textadept/init.lua* + ui.set_theme(not CURSES and 'custom' or 'custom_term') + +You may still use absolute paths for themes instead of names. + +### Textadept 5 to 6 + +Textadept 6 introduces some API changes. These changes affect themes in +particular, so your themes may require upgrading. + +Old API | Change | New API +-------------------------------------|:------:|-------- +**buffer** | | +annotation\_get\_text(line) |Renamed |annotation\_text[line] +annotation\_set\_text(line, text) |Renamed |annotation\_text[line] = text +auto\_c\_get\_current() |Renamed |auto\_c\_current +auto\_c\_get\_current\_text() |Renamed |auto\_c\_current\_text +get\_lexer\_language() |Renamed |lexer\_language +get\_property(key) |Renamed |property[key] +get\_property\_expanded(key) |Renamed |property\_expanded[key] +get\_tag(n) |Renamed |tag[n] +margin\_get\_text(line) |Renamed |margin\_text[line] +margin\_set\_text(line, text) |Renamed |margin\_text[line] = text +marker\_set\_alpha(n, alpha) |Renamed |marker\_alpha[n] = alpha +marker\_set\_back(n, color) |Renamed |marker\_back[n] = color +marker\_set\_back\_selected(n, color)|Renamed |marker\_back\_selected[n] = color +marker\_set\_fore(n, color) |Renamed |marker\_fore[n] = color +set\_fold\_flags(flags) |Renamed |fold\_flags = flags +set\_lexer\_language(name) |Renamed |lexer\_language = name +style\_get\_font(n) |Renamed |style\_font[n] +**gui** | | +gtkmenu() |Renamed |[menu()][] +**_G** | | +user\_dofile(file) |Renamed |dofile(\_USERHOME..'/'..file) +**_M** | | +lua.goto\_required() |Removed |N/A +php.goto\_required() |Removed |N/A +ruby.goto\_required() |Removed |N/A +**_M.textadept.adeptsense** | | +complete\_symbol() |Replaced|complete() +show\_documentation() |Replaced|show\_apidoc() +**_M.textadept.bookmarks** | | +N/A |New |[toggle()][] +add() |Renamed |toggle(true) +remove() |Renamed |toggle(false) +**_M.textadept.editing** | | +prepare\_for\_save() |Removed |N/A +**_M.textadept.menu** | | +rebuild\_command\_tables() |Replaced|set\_menubar() +**_M.textadept.run** | | +execute() |Replaced|[run()][] and [compile()][] +**_M.textadept.session** | | +prompt\_load() |Replaced|[load()][] +prompt\_save() |Replaced|[save()][] + +[menu()]: api.html#ui.menu +[toggle()]: api.html#textadept.bookmarks.toggle +[run()]: api.html#textadept.run.run +[compile()]: api.html#textadept.run.compile +[load()]: api.html#textadept.session.load +[save()]: api.html#textadept.session.save + +### Textadept 4 to 5 + +Textadept 5 upgraded its copy of Lua from [5.1 to 5.2][]. Many old scripts are +not compatible and need to be upgraded. 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 make to Textadept's internals. + +[5.1 to 5.2]: http://www.lua.org/manual/5.2/manual.html#8 + +#### API Changes + +Old API |Change |New API +---------------|:------:|------- +**_G** | | +getfenv(f) |Removed |N/A. Use:
debug.getupvalue(f, 1) +loadstring() |Replaced|load() +module() |Removed |N/A +setfenv(f, env)|Removed |N/A. Use:
debug.setupvalue(f, 1, env)a +unpack() |Renamed |table.unpack() +xpcall(f, msgh)|Changed |xpcall(f, msgh, ...) +**\_m** |Renamed |**[\_M][]**b +**_m.textadept.editing**| | +current\_word(action) |Renamed|[select\_word()][]c +**locale** |Removed|N/A +localize(message) |Renamed|\_G.[\_L][][message] +**os** | | +code = execute(cmd) |Changed|ok, status, code = execute(cmd) + +aIn some cases, use `load()` with an environment instead: + + setfenv(loadstring(str), env)() --> load(str, nil, 'bt', env)() + +bIn Textadept, search for "\_m" and replace with "\_M" with the +"Match Case" and "Whole Words" options checked -- this is what I did when +upgrading Textadept's internals. + +cTo delete, call `_M.textadept.keys.utils.delete_word()` or define +your own: + + local function delete_word() + _M.textadept.editing.select_word() + buffer:delete_back() + end + +[\_M]: api.html#_M +[select\_word()]: api.html#textadept.editing.select_word +[\_L]: api.html#_L + +#### Module Changes + +You can use the following as a reference for converting your Lua 5.1 modules to +Lua 5.2: + + -- File *~/.textadept/modules/foo.lua* + -- Lua 5.1 | -- Lua 5.2 + | + | local M = {} + | --[[ This comment is for LuaDoc + --- | --- + -- This is the documentation | -- This is the documentation + -- for module foo. | -- for module foo. + module('foo', package.seeall) | module('foo')]] + | + --- | --- + -- Documentation for bar. | -- Documentation for bar. + -- ... | -- ... + -- | -- @name bar + function bar() | function M.bar() + ... | ... + end | end + | + function baz() | function M.baz() + bar() | M.bar() + end | end + | + | return M + + -- File *~/.textadept/init.lua* + -- Lua 5.1 | -- Lua 5.2 + | + require 'textadept' | _M.textadept = require 'textadept' + require 'foo' | foo = require 'foo' + +Notes: + +1. Even though Lua 5.2 deprecates Lua 5.1's `module()`, Textadept 5 removes it. +2. Prefix all intern module tables and function calls with `M`. +3. Also, replace all instances (if any) of `_M` (a references created by + `module()` that holds the current module table) with `M`. +4. You can use your existing LuaDoc comments by keeping the `module()` call + commented out and adding `@name` tags. + +#### Theme Changes + +You can use the following as a reference for converting your Lua 5.1 themes to +Lua 5.2: + + -- File *~/.textadept/themes/theme/lexer.lua* + -- Lua 5.1 | -- Lua 5.2 + | + | local l = lexer + module('lexer', package.seeall) | local color = l.color + | local style = l.style + | + colors = { | l.colors = { + ... | ... + } | } + | + style_nothing = style{} | l.style_nothing = style{...} + style_class = style{ | l.style_class = style{ + fore = colors.light_yellow | fore = l.colors.light_yellow + } | } + ... | ... + style_identifier = style_nothing | l.style_identifier = l.style_nothing + | + ... | ... + | + style_default = style{ | l.style_default = style{ + ... | ... + } | } + style_line_number = { | l.style_line_number = { + fore = colors.dark_grey, | fore = l.colors.dark_grey, + back = colors.black | back = l.colors.black + } | } + ... | ... + +Note the `l.` prefix before most identifiers. + +### Textadept 3 to 4 + +#### Key and Menu Changes + +Textadept 4 features a brand new set of key bindings and menu structure. It also +shows simple key bindings (not keychains) in menus. In order for key bindings to +appear in menus, `_m.textadept.menu` must know which commands map to which keys. +Therefore, the menu module needs to be `require`d *after* `_m.textadept.keys`. +If your *~/.textadept/init.lua* calls `require 'textadept'`, you do not have to +make any changes. If you load individual modules from `_m.textadept`, ensure +`_m.textadept.menu` loads after `_m.textadept.keys`. + +Mac OSX has different modifier key definitions. A new `m` indicates ⌘ (command) +and `a` changed from ⌘ to ⌥ (alt/option). `c` remains ^ (control). Keep in mind +that ⌥ functions as a compose key for locale-dependent characters. + +#### API Changes + +Old API |Change | New API +-------------------------|:-----:|-------- +**\_m.textadept.editing**| | +select\_scope() |Renamed|select\_style() +SAVE\_STRIPS\_WS |Renamed|STRIP\_WHITESPACE\_ON\_SAVE + +### Textadept 2 to 3 + +#### Module Changes + +##### Core Extensions + +The core extention modules moved from *core/ext/* to *modules/textadept/*. +Putting + + require 'textadept' + +in your *~/.textadept/init.lua* loads all the modules you would expect. The +[loading modules](#Loading.Modules) section has instructions on how to load +specific modules. + +##### Autoloading Keys and Snippets + +Key bindings in *~/.textadept/key_commands.lua* and snippets in +*~/.textadept/snippets.lua* no longer auto-load. Move them to your +*~/.textadept/init.lua* or a file loaded by *~/.textadept/init.lua*. + +#### API Changes + +Textadept has a brand new Lua [API][]. Old scripts and themes are likely not +compatible and need to be upgraded. + +Old API |Change | New API +--------------------------|:-----:|-------- +**_G** | | +N/A |New |[\_SCINTILLA][] +N/A |New |[events][] +N/A |New |[gui][] +**_m.textadept.lsnippets**|Renamed|**[_m.textadept.snippets][]** +**textadept** |Removed|N/A +\_print() |Renamed|\_G.[gui.\_print()][] +buffer\_functions |Renamed|\_G.[\_SCINTILLA.functions][] +buffer\_properties |Renamed|\_G.[\_SCINTILLA.properties][] +buffers |Renamed|\_G.[\_BUFFERS][] +check\_focused\_buffer() |Renamed|\_G.gui.check\_focused\_buffer() +clipboard\_text |Renamed|\_G.[gui.clipboard\_text][] +command\_entry |Renamed|\_G.[gui.command\_entry][] +constants |Renamed|\_G.[\_SCINTILLA.constants][] +context\_menu |Renamed|\_G.[gui.context\_menu][] +dialog |Renamed|\_G.[gui.dialog()][] +docstatusbar\_text |Renamed|\_G.[gui.docstatusbar\_text][] +events |Renamed|\_G.[events][] +events.add\_handler() |Renamed|\_G.[events.connect()][] +events.handle() |Renamed|\_G.[events.emit()][] +find |Renamed|\_G.[gui.find][] +focused\_doc\_pointer |Renamed|\_G.gui.focused\_doc\_pointer +get\_split\_table() |Renamed|\_G.[gui.get\_split\_table()][] +goto\_view() |Renamed|\_G.[gui.goto\_view()][] +gtkmenu() |Renamed|\_G.[gui.gtkmenu()][] +iconv() |Renamed|\_G.[string.iconv()][] +menubar |Renamed|\_G.[gui.menubar][] +new\_buffer() |Renamed|\_G.[new\_buffer()][] +print() |Renamed|\_G.[gui.print()][] +quit() |Renamed|\_G.[quit()][] +reset() |Renamed|\_G.[reset()][] +session\_file |Renamed|\_G.\_SESSIONFILE +size |Renamed|\_G.[gui.size][] +statusbar\_text |Renamed|\_G.[gui.statusbar\_text][] +switch\_buffer() |Renamed|\_G.[gui.switch\_buffer()][] +title |Renamed|\_G.[gui.title][] +user\_dofile() |Renamed|\_G.user\_dofile() +views |Renamed|\_G.[\_VIEWS][] + +[API]: api +[\_SCINTILLA]: api.html#_SCINTILLA +[events]: api.html#events +[gui]: api.html#ui +[_m.textadept.snippets]: api.html#textadept.snippets +[gui.\_print()]: api.html#ui._print +[\_SCINTILLA.functions]: api.html#_SCINTILLA.functions +[\_SCINTILLA.properties]: api.html#_SCINTILLA.properties +[\_BUFFERS]: api.html#_BUFFERS +[gui.clipboard\_text]: api.html#ui.clipboard_text +[gui.command\_entry]: api.html#ui.command_entry +[\_SCINTILLA.constants]: api.html#_SCINTILLA.constants +[gui.context\_menu]: api.html#ui.context_menu +[gui.dialog()]: api.html#ui.dialog +[gui.docstatusbar\_text]: api.html#ui.docstatusbar_text +[events.connect()]: api.html#events.connect +[events.emit()]: api.html#events.emit +[gui.find]: api.html#ui.find +[gui.get\_split\_table()]: api.html#ui.get_split_table +[gui.goto\_view()]: api.html#ui.goto_view +[gui.gtkmenu()]: api.html#ui.menu +[string.iconv()]: api.html#string.iconv +[gui.menubar]: api.html#ui.menubar +[new\_buffer()]: api.html#buffer.new +[gui.print()]: api.html#ui.print +[quit()]: api.html#quit +[reset()]: api.html#reset +[gui.size]: api.html#ui.size +[gui.statusbar\_text]: api.html#ui.statusbar_text +[gui.switch\_buffer()]: api.html#ui.switch_buffer +[gui.title]: api.html#ui.title +[\_VIEWS]: api.html#_VIEWS diff --git a/doc/markdowndoc.lua b/doc/markdowndoc.lua index dbc15864..1a8d5c5d 100644 --- a/doc/markdowndoc.lua +++ b/doc/markdowndoc.lua @@ -10,27 +10,26 @@ local table_concat = table.concat -- @usage luadoc -d [output_path] -doclet path/to/markdowndoc [file(s)] local M = {} -local NAVFILE = '%s* [%s](%s)\n' +local NAVFILE = '1. [%s](%s)\n' +local MODULE = '\n# The `%s` Module\n\n' local FIELD = '\n### `%s` %s\n\n' local FUNCTION = '\n### `%s`(*%s*)\n\n' local FUNCTION_NO_PARAMS = '\n### `%s`()\n\n' ---local FUNCTION = '### `%s` (%s)\n\n' local DESCRIPTION = '%s\n\n' local LIST_TITLE = '%s:\n\n' local PARAM = '* *`%s`*: %s\n' local USAGE = '* `%s`\n' local RETURN = '* %s\n' -local SEE = '* [`%s`](%s)\n' +local SEE = '* [`%s`](#%s)\n' local TABLE = '\n### `%s`\n\n' ---local TABLE = '### `%s`\n\n' -local TFIELD = '* `%s`: %s\n ' +local TFIELD = '* `%s`: %s\n' local HTML = [[ %(title) - - + + @@ -38,15 +37,11 @@ local HTML = [[ - -
-

Contents

- %(toc) -
+

Textadept API Documentation

+

Modules

+ %(toc) +
%(main)