diff options
35 files changed, 2554 insertions, 826 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..91da4a4b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,1003 @@ +# Changelog + +## 5.1 (01 Mar 2012) + +Bugfixes: + +* Fixed crash caused by [`gui.filteredlist()`][] dialogs. +* Support multiple `@return` tags in Lua Adeptsense. +* Fixed display of `buffer._type` when it has slashes in its name. + +Changes: + +* Better Lua Adeptsense formatting. +* Use new Cocoa-based [GtkOSXApplication][] library for better OSX support. +* Lexers with no tokens can be styled manually. +* Added more OSX default key shortcuts. + +[`gui.filteredlist()`]: api/gui.html#filteredlist +[GtkOSXApplication]: https://live.gnome.org/GTK%2B/OSX/Integration#Gtk-mac-integration.2BAC8-GtkOSXApplication + +## 5.0 (01 Feb 2012) + +Please see the [4 to 5 migration guide][] for upgrading from Textadept 4 to +Textadept 5. + +Bugfixes: + +* Fixed bug with recent files in sessions. + +Changes: + +* Added default extension and folder filters in + `modules/textadept/snapopen.lua`. +* Added ChucK lexer. +* Updated to [Scintilla][] 3.0.3. +* Also include [LuaJIT][] executables in releases. + +[4 to 5 migration guide]: manual/14_Appendix.html#Textadept.4.to.5 +[Scintilla]: http://scintilla.org +[LuaJIT]: http://luajit.org + +## 5.0 beta (11 Jan 2012) + +Bugfixes: + +* Fixed bug in [`reset()`][] from update to Lua 5.2. + +Changes: + +* Changed `locale.localize()` to global [`_L`][] table and removed `locale` + module. +* Renamed `_m` to [`_M`][]. +* Do not clear registered images when autocompleting with Adeptsense. +* Renamed editing module's `current_word()` to [`select_word()`][]. +* Updated [manual][]. + +[`reset()`]: api/_G.html#reset +[`_L`]: api/_L.html +[`_M`]: api/_M.html +[manual]: manual +[`select_word()`]: api/_M.textadept.editing.html#select_word + +## 5.0 alpha (21 Dec 2012) + +Bugfixes: + +* None. + +Changes: + +* Updated to [Lua 5.2][]. +* Updated sections in the [manual][] to reflect Lua 5.2 changes. +* Textadept can be compiled with [LuaJIT][]. + +[Lua 5.2]: http://www.lua.org/manual/5.2/ +[manual]: manual +[LuaJIT]: http://luajit.org + +## 4.3 (01 Dec 2011) + +Bugfixes: + +* Fixed bug with opening files in the current directory from the command line. +* Fixed erroneous charset conversion. + +Changes: + +* Added on-the-fly [theme switching][]. +* All new `light` and `dark` themes. +* Removed `_m.textadept.editing.select_style()`. +* Simplify theming via [gtkrc][] by naming `GtkWindow` only. +* Updated to [Scintilla][] 3.0.1. + +[theme switching]: api/gui.html#set_theme +[gtkrc]: manual/8_Themes.html#Theming.the.GUI +[Scintilla]: http://scintilla.org + +## 4.2 (01 Nov 2011) + +Bugfixes: + +* Fixed bug with `%n` in Replace introduced in 4.1. +* Fixed Adeptsense autocomplete for single item. + +Changes: + +* Updated to [Scintilla][] 3.0.0. + +[Scintilla]: http://scintilla.org + +## 4.1 (01 Oct 2011) + +Bugfixes: + +* Only fold when clicking on fold margin, not any sensitive one. +* Fixed bug with `CALL_TIP_CLICK` event disconnect in Adeptsense. +* Fixed bug with autocomplete and capitalization. + +Changes: + +* Handle mouse [dwell events][] `DWELL_START` and `DWELL_END`. +* Rearranged `Tools` menu slightly. +* Slight API 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()`][]. + + [`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. +* Added language-specific [context menu][] support. +* Use [LuaCoco][] patch for Lua 5.1.4. +* Use lexer at the caret for key commands and snippets. +* Updated to [Scintilla][] 2.29. + +[dwell events]: api/events.html +[`_BUFFERS`]: api/_G.html#_BUFFERS +[`_VIEWS`]: api/_G.html#_VIEWS +[`buffer:check_global()`]: api/buffer.html#buffer.check_global +[`view:goto_buffer()`]: api/view.html#view:goto_buffer +[`gui.goto_view()`]: api/gui.html#goto_view +[context menu]: api/_M.html#Context.Menu +[LuaCoco]: http://coco.luajit.org/ +[Scintilla]: http://scintilla.org + +## 4.0 (01 Sep 2011) + +Please see the [3 to 4 migration guide][] for upgrading from Textadept 3 to +Textadept 4. + +Bugfixes: + +* Makefile should only link to `libdl.so` on Linux/BSD. +* Fixed memory access bug in [`gui.dialog()`][]. +* Autocompletion list sort order respects `buffer.auto_c_ignore_case` now. +* Fixed split view focus bug with the same buffer in two views. +* Set new buffer EOL mode properly on Mac OSX. + +Changes: + +* Added Russian translation. +* 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]: manual/14_Appendix.html#Textadept.3.to.4 +[`gui.dialog()`]: api/gui.html#dialog + +## 4.0 beta 2 (11 Aug 2011) + +Bugfixes: + +* Fixed transpose characters bug at end of buffer. +* Do not autosave over explicitly loaded session. +* Fixed startup crash on Mac OSX. +* Fixed resize crash on Mac OSX Lion. + +Changes: + +* Added Scala lexer. +* Add [recent file list][] to session files. +* Autocomplete supports multiple selections. +* Swapped OSX `c` and `m` key command definition modifiers. +* Changed some key bindings from 4.0 beta. + +[recent file list]: api/io.html#recent_files + +## 4.0 beta (01 Aug 2011) + +Bugfixes: + +* None. + +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.line_down()` is allowed). +* Complete overhaul of menus and added accelerators to [menu][] items. +* Renamed `_m.textadept.editing.SAVE_STRIPS_WS` to + `_m.textadept.editing.STRIP_WHITESPACE_ON_SAVE`. +* Renamed `_m.textadept.editing.select_scope()` to + `_m.textadept.editing.select_style()`. +* *Completely new set of key commands.* +* Updated to [Scintilla][] 2.28. + +[`io.open_recent_file()`]: api/io.html#open_recent_file +[`buffer` functions]: api/buffer.html#Functions +[menu]: api/gui.html#gtkmenu +[Scintilla]: http://scintilla.org + +## 3.9 (01 Jul 2011) + +Bugfixes: + +* Fixed bug for when [`gui.dialog`][] steals focus. + +Changes: + +* Added support for [GTK][] 3.0. +* Use ID generator [functions][] for marker, indicator, and user list IDs. +* Updated to [Scintilla][] 2.27. +* Use string constants for event names. +* Compile and run commands [emit events][]. +* Enhanced Luadoc and Lua Adeptsense. +* Added `fold.line.comments` property for folding multiple single-line comments. +* Use [GTK][] 2.22 on Windows. +* Can localize the labels and buttons in the GUI [find][] frame. +* Added ConTeXt lexer. + +[GTK]: http://gtk.org +[`gui.dialog`]: api/gui.html#dialog +[functions]: api/_SCINTILLA.html#Functions +[Scintilla]: http://scintilla.org +[emit events]: api/_M.textadept.run.html#Run.Events +[find]: api/gui.find.html + +## 3.8 (11 Jun 2011) + +Bugfixes: + +* Removed non-existant key chain. +* Fixed bug in snippets. + +Changes: + +* Updated Adeptsense and documentation. +* [`events.handlers`][] is accessible. +* Added menu mnemonics for indentation size. +* Added support for indicator and hotspot [events][]. +* Updated [documentation][] for installing [official modules][]. +* Updated to [Scintilla][] 2.26. +* Writing custom folding for lexers is much [easier][] now. +* Added native folding for more than 60% of existing lexers. The rest still use + folding by indentation by default. + +[`events.handlers`]: api/events.html#handlers +[events]: api/events.html +[documentation]: manual/7_Modules.html#Getting.Modules +[official modules]: http://foicica.com/hg +[Scintilla]: http://scintilla.org +[easier]: api/lexer.html#Simple.Code.Folding + +## 3.7 (01 May 2011) + +Bugfixes: + +* Fixed bug in [`buffer:get_lexer()`][]. + +Changes: + +* Changed Mac OSX Adeptsense complete key command from `~` to `Ctrl+Escape`. +* Added [PHP module][]. + +[`buffer:get_lexer()`]: api/buffer.html#buffer.get_lexer +[PHP module]: api/_M.php.html + +## 3.7 beta 3 (01 Apr 2011) + +Bugfixes: + +* Small Adeptsense bugfixes. +* Snapopen respects filesystem encoding. +* Standard input dialogs have "Cancel" button by default. + +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][]. +* Updated mime-types and prioritize by shebang, pattern, and then file + extension. +* [`buffer:get_lexer(true)`] returns the lexer at the caret position. +* Adeptsense can be triggered in embedded lexers now. +* Added C standard library and Lua C API to C/C++ Adeptsense. +* Lua module fields are now in Lua Adeptsense. +* Updated to [Scintilla][] 2.25. +* Rewrote [`_m.textadept.snippets`][] with syntax changes. +* `Alt+I` (`Ctrl+I` on Mac OSX) is now "Select Snippet" instead of "Show Style". + "Show Style" is now `Ctrl+Alt+Shift+I` (`Ctrl+Apple+Shift+I`). +* Adeptsense can exclude types matched by `sense.syntax.type_declarations` + patterns. +* `Ctrl+T, V` (`Apple+T, V` on Mac OSX) keychain for toggling whitespace, wrap, + etc. is now `Ctrl+Shift+B` (`Apple+Shift+B`). +* Key commands and menu definition syntax changed. +* Snapopen allows for multiple-selection. +* [`gui.print()`] handles `nil` and non-string arguments properly. +* Officially supported modules have their own [repositories][] and are available + as a separate download. + +[`post_init.lua`]: manual/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 +[Scintilla]: http://scintilla.org +[`_m.textadept.snippets`]: api/_M.textadept.snippets.html +[`gui.print()`]: api/gui.html#print +[repositories]: http://foicica.com/hg + +## 3.7 beta 2 (01 Mar 2011) + +Bugfixes: + +* Fixed bug with Win32 paths in Adeptsense [`goto_ctag()`][]. +* Adeptsense could not recognize some symbols. +* Handle `\n` sequences correctly in Adeptsense apidoc. +* Fixed bug with Adeptsense C/C++ type declarations. +* Adeptsense can now recognize more than 1 level of inheritence. +* Keychain is cleared on key command error. +* Fixed infinite loop bug in `_m.textadept.editing.select_scope()`. + +Changes: + +* Updated to [Scintilla][] 2.24. +* Updated mime-types. +* Line margin width is now `4`. +* Adeptsense completion list images are accessible via scripts. +* Added class context completion to Adeptsense. +* Added class type-inference through variable assignment to Adeptsense. +* Added Adeptsense [tutorial][]. +* Added `_m.textadept.adeptsense.always_show_globals` setting for showing + globals in completion lists. +* `Ctrl+H` (highlight word) is now `Ctrl+Shift+H`. +* `Ctrl+H` now shows Adeptsense documentation. +* Added Adeptsense [`complete()`][] and [`show_documentation()`][] functions to + the menu. +* 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. + +[`goto_ctag()`]: api/_M.textadept.adeptsense.html#goto_ctag +[Scintilla]: http://scintilla.org +[tutorial]: api/_M.textadept.adeptsense.html +[`complete()`]: api/_M.textadept.adeptsense.html#complete +[`show_documentation()`]: api/_M.textadept.adeptsense.html#show_documentation +[CSS]: api/_M.css.html +[HTML]: api/_M.hypertext.html +[Java]: api/_M.java.html +[Ruby]: api/_M.ruby.html + +## 3.7 beta (01 Feb 2011) + +Bugfixes: + +* `update_ui` is called properly for `buffer_new` and `view_new` events. +* Use proper pointer type for Scintilla calls. +* Fixed bug with loading lexers from `_USERHOME` on Win32. + +Changes: + +* More informative error message for unfocused buffer. +* Added [Adeptsense][], a smarter form of autocompletion for programming + languages. +* Emit a [`language_module_loaded`][] as appropriate. +* Added indentation settings to "Buffer" menu (finally). +* Added [`gui.filteredlist()`][] shortcut for `gui.dialog('filteredlist', ...)`. +* Can navigate between bookmarks with a filteredlist. +* Language-specific [`char_matches`][] and [`braces`][] can be defined. +* `command_entry_keypress` event accepts modifier keys. + +[Adeptsense]: manual/6_AdeptEditing.html#Adeptsense +[`language_module_loaded`]: api/_M.textadept.mime_types.html#Mime-type.Events +[`gui.filteredlist()`]: api/gui.html#filteredlist +[`char_matches`]: api/_M.textadept.editing.html#char_matches +[`braces`]: api/_M.textadept.editing.html#braces + +## 3.6 (01 Jan 2011) + +Bugfixes: + +* Fixed infinite recursion errors caused in events. +* Fix statusbar update bug with key chains. +* Do not emit `buffer_new` event when splitting the view. + +Changes: + +* `buffer.rectangular_selection_modifier` on Linux is the Super/Windows key. +* Improved Hypertext lexer. +* Added Markdown, BibTeX, CMake, CUDA, Desktop Entry, F#, GLSL, and Nemerle + lexers. +* Added [`_m.textadept.filter_through`][] module for [shell commands][]. +* Moved GUI events from `core/events.lua` to `core/gui.lua`. +* Separated key command manager from key command definitions. + +[`_m.textadept.filter_through`]: api/_M.textadept.filter_through.html +[shell commands]: manual/10_Advanced.html#Shell.Commands.and.Filtering.Text + +## 3.5 (01 Dec 2010) + +Bugfixes: + +* Fixed bug introduced when exposing Find in Files API. + +Changes: + +* Lua files are syntax-checked for errors on save. +* [Menus][] are easier to create. +* Changed [`_m.textadept.editing.enclose()`][] behavior. +* Win32 and Mac OSX packages are all-in-one bundles; GTK is no longer an + external dependency. +* New [manual][]. +* Added `file_after_save` [event][]. + +[Menus]: api/_M.textadept.menu.html +[`_m.textadept.editing.enclose()`]: api/_M.textadept.editing.html#enclose +[manual]: manual +[event]: api/io.html#File.Events + +## 3.4 (01 Nov 2010) + +Bugfixes: + +* Fixed menu item conflicts. +* Pressing `Cancel` in the [Switch Buffers][] dialog does not jump to the + selected buffer anymore. +* Autocomplete lists sort properly for machines with a different locale. +* Statusbar is not cleared when set from a key command. +* Unreadable files are handled appropriately. + +Changes: + +* Multi-language lexers (HTML, PHP, RHTML, etc.) are processed as fast as single + language ones, resulting in a huge speed improvement. +* 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. +* Removed `_m.textadept.editing.smart_cutcopy()` and + `_m.textadept.editing.squeeze()` functions. +* Added `_m.textadept.editing.SAVE_STRIPS_WS` option to disable strip whitespace + on save. +* Changed locale implementation. Locale files are much easier to create now. +* `gui.statusbar_text` is now readable instead of being write-only. +* Can [highlight][] all occurances of a word. +* Added jsp lexer. +* More consistant handling of `\` directory separator for Win32. +* Consolidated `textadept.h` and `lua_interface.c` into single `textadept.c` + file. +* Added [`_G.timeout()`][] function for calling functions and/or events after a + period of time. +* Find in files is accessible through [find API][]. +* Updated to [Scintilla][] 2.22. +* Renamed `_G.MAC` to `_G.OSX`. + +[Switch Buffers]: manual/4_WorkingWithFiles.html#Buffer.Browser +[`gui.dialog()`]: api/gui.html#dialog +[`_m.textadept.snapopen.open()`]: api/_M.textadept.snapopen.html#open +[highlight]: manual/6_AdeptEditing.html#Word.Highlight +[`_G.timeout()`]: api/_G.html#timeout +[find API]: api/gui.find.html#find_in_files +[Scintilla]: http://scintilla.org + +## 3.3 (01 Oct 2010) + +Bugfixes: + +* Fixed buggy snippet menu. + +Changes: + +* Added [`_m.textadept.snapopen`][] module with menu options for rapidly opening + files. + +[`_m.textadept.snapopen`]: api/_M.textadept.snapopen.html + +## 3.2 (01 Sep 2010) + +Bugfixes: + +* Fixed "Replace All" infinite loop bug. + +Changes: + +* Updated to the new [Scintillua][] that does not required patched Scintilla. +* Updated to [Scintilla][] 2.21. + +[Scintillua]: http://foicica.com/scintillua +[Scintilla]: http://scintilla.org + +## 3.1 (21 Aug 2010) + +Bugfixes: + +* Fixed memory leak in Mac OSX. + +Changes: + +* Refactored key commands to support [propagation][]. +* Updated to [Scintilla][] 2.20. +* Added Lua autocompletion. + +[propagation]: api/keys.html#Propagation +[Scintilla]: http://scintilla.org + +## 3.0 (01 Jul 2010) + +Please see the [2 to 3 migration guide][] for upgrading from Textadept 2 to +Textadept 3. + +Bugfixes: + +* None + +Changes: + +* More accurate CSS and Diff lexers. + +[2 to 3 migration guide]: manual/14_Appendix.html#Textadept.2.to.3 + +## 3.0 beta (21 Jun 2010) + +Bugfixes: + +* Fixed Mac OSX paste issue. +* Fixed [`buffer:text_range()`][] argcheck problem. + +Changes: + +* Remove initial "Untitled" buffer when necessary. +* Moved core extension modules into [`textadept`][] module. +* New [API][]. +* `~/.textadept/init.lua` is created for you if one does not exist. +* No more autoload of `~/.textadept/key_commands.lua` and + `~/.textadept/snippets.lua` +* Updated to [Scintilla][] 2.12. +* [Abbreviated][] Lua commands in the command entry. +* Dynamic command line [arguments][]. +* Added statusbar notification on [`reset()`][]. +* Added Gtkrc, Prolog, and Go lexers. + +[`buffer:text_range()`]: api/buffer.html#buffer.text_range +[`textadept`]: api/_M.textadept.html +[API]: api +[Scintilla]: http://scintilla.org +[Abbreviated]: manual/10_Advanced.html#Command.Entry +[arguments]: api/args.html +[`reset()`]: api/_G.html#reset + +## 2.2 (11 May 2010) + +Bugfixes: + +* Save buffer before compiling or running. +* Fixed error in the manual for `~/.textadept/init.lua` example. +* Ignore `file://` prefix for filenames. + +Changes: + +* `_USERHOME` comes before `_HOME` in `package.path` so `require` searches + `~/.textadept/` first. + +## 2.2 beta 2 (01 May 2010) + +Bugfixes: + +* Fixed crash with [`buffer:text_range()`][]. +* Fixed snippets bug with `%n` sequences. +* Respect tab settings for snippets. +* Fixed help hanging bug in Win32. +* Fixed Lua module commands bug. + +Changes: + +* Added BSD support. +* Removed kill-ring from editing module. +* [Run][] and [compile][] commands are in language-specific modules. +* [Block comment][] strings are in language-specific modules now. +* Remove "Untitled" buffer when necessary. +* Moved "Search" menu into "Tools" menu to prevent `Alt+S` key conflict. +* Rewrote lexers implementation. +* Added Inform, Lilypond, and NSIS lexers. +* `_m.textadept.editing.enclosure` is now an accessible table. + +[`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 + +## 2.2 beta (01 Apr 2010) + +Bugfixes: + +* Fixed transform bug in snippets. +* Fixed bug with Io lexer mime-type. +* Fixed embedded css/javascript bug in hypertext (HTML) lexer. + +Changes: + +* Removed `_m.textadept.mlines` module since Scintilla's multiple selections + supercedes it. +* Removed side pane. +* New [`gui.dialog('filteredlist', ...)] from [gcocoadialog][]. +* Can select buffer from filteredlist dialog (replacing side pane buffer list). +* Can select lexer from filteredlist dialog. +* Can have user `key_commands.lua`, `snippets.lua`, `mime_types.conf`, + `locale.conf` that are loaded by their respective modules. +* Added Matlab/Octave lexer. +* Backspace deletes auto-inserted character pairs. +* Added notification for session files not found. +* Snippets use multiple carets. +* Removed api file support. + +[gcocoadialog]: http://foicica.com/gcocoadialog +[`gui.dialog('filteredist', ...)]: api/gui.html#dialog + +## 2.1 (01 Mar 2010) + +Bugfixes: + +* Do not close files opened from command line when loading PM session. +* Fixed bug for running a file with no path. +* Fixed error message for session file not being found. +* Fixed key command for word autocomplete on Win32. +* Changed conflicting menu shortcut for Lexers menu. +* Fixed typos in templates generated by modules PM browser. + +Changes: + +* Added Dot and JSON lexers. +* Search `_USERHOME` in addition to `_HOME` for themes. +* Added command line switch for not loading/saving session. +* Modified key commands to be more key-layout agnostic. +* Added `reset_before` and `reset_after` events while `textadept.reset()` is + being run. +* Reload current lexer module after `textadept.reset()`. +* Added `~/.textadept/modules/` to `package.path`. +* Updated to [Scintilla][] 2.03. +* Modified quit and close dialogs to be more readable. + +[Scintilla]: http://scintilla.org + +## 2.0 (01 Oct 2009) + +Bugfixes: + +* Fixed bug with reloading PM width from session file. +* Only show a non-nil PM context menu. +* Fixed bug in `modules/textadept/lsnippets.lua`. +* Fixed bug in `core/ext/mime_types.lua` caused during `textadept.reset()`. +* Close all buffers before loading a session. +* Identify `shellscript` files correctly. +* D lexer no longer has key-command conflicts. + +Changes: + +* Refactored `modules/textadept/lsnippets.lua`. +* Updated key commands. +* Allow PM modules in the `~/.textadept` user directory. +* Added `style_whitespace` to [lexers][] for custom styles. +* Added standard `F3` key command for "Find Next" for Windows/Linux. + +[lexers]: api/lexer.html + +## 2.0 beta (31 Jul 2009) + +Bugfixes: + +* Alphabetize lexer list. +* Fixed some locale issues. +* Fixed some small memory leaks. +* Try a [list of encodings][] rather than just UTF-8 so "conversion failed" does + not happen so often. +* Restore a manually set lexer. + +Changes: + +* Removed `_m.textadept.macros` module and respective PM browser (use Lua + instead). +* Linux version can be installed and run from anywhere; no need to recompile + anymore. +* Added many more [events][] to hook into lots of core functionality. +* Updated to [Scintilla][] 1.79. +* Run module allows more flexible [compile commands][] and [run commands][]. +* Save project manager cursor over sessions. +* Allow mime-types and compile and run commands to be user-redefinable in user + scripts. +* Use `~/.textadept/` for holding user lexers, themes, sessions, etc. +* Added "Help" menu linking to Manual and LuaDoc. +* Textadept compiles as C99 code. (Drops Microsoft Visual Studio support.) +* Sessions functionality moved to `modules/textadept/session.lua` from + `core/file_io.lua`. +* The `char_added` event now passes an int, not a string, to handler functions. +* Replaced [cocoaDialog][] and [lua_dialog][] with my C-based [gcocoadialog][]. +* [Incremental find][] via the Lua command entry. +* *NO* dependencies other than [GTK][] on _all_ platforms. + + + Win32 no longer requires the MSVC++ 2008 Runtime. + + Linux no longer requires `libffi`. + + Mac OSX no longer requires [cocoaDialog][]. + +* Can cross compile to Win32 from Linux. +* Removed confusing `local function` and `local table` LuaDoc. +* Rewrote the manual and most of the documentation. + +[list of encodings]: api/io.html#try_encodings +[events]: api/events.html +[Scintilla]: http://scintilla.org +[compile commands]: api/_M.textadept.run.html#compile_command +[run commands]: api/_M.textadept.run.html#run_command +[gcocoadialog]: http://foicica.com/gcocoadialog +[lua_dialog]: http://luaforge.net/projects/lua-dialog +[cocoaDialog]: http://cocoadialog.sf.net +[Incremental find]: manual/6_AdeptEditing.html#Find.Incremental +[GTK]: http://gtk.org + +## 1.6 (01 Apr 2009) + +Bugfixes: + +* Fixed `NULL` byte bug associated with Lua interface due to multi-encoding + support. +* Find marker is colored consistently. +* Fixed issue with buffer browser cursor saving. +* Fixed block character insertion issue on GTK-OSX. + +Updates: + +* Trimmed theme files. +* Added `file_before_save` [event][]. + +[event]: api/io.html#File.Events + +## 1.6 beta (01 Mar 2009) + +Bugfixes: + +* Fixed bookmarks bugs. +* PM browsers are not re-added to the list again on `textadept.reset()`. +* Fixed ctags PM browser bug with filenames. +* Marker colors are set for all views now. +* Fixed never-ending "reload modified file?" dialog bug. +* Fixed key command for `m_snippets.list`. +* Fixed issues with [`_m.textadept.run`][] module. +* Fixed document modification status bug for unfocused split views. +* Fixed filename encoding issues for Windows. + +Updates: + +* Added key commands and menu items to navigate "Find in Files" list. +* The `recent_files` popup list behaves better. +* Attempt to preserve existing EOL mode for opened files. +* Add drag-and-dropped directories to the PM browser list. +* Removed `project` PM browser. +* Multiple character encoding support for opening and saving files. + +[`_m.textadept.run`]: api/_M.textadept.run.html + +## 1.5 (20 Feb 2009) + +Bugfixes: + +* Fixed some corner cases in Find in Files user interface. +* Fixed some OSX key command issues for consistency. +* Fixed some key command modifiers for "enclose in" series. + +Updates: + +* Consolidated `core/ext/key_commands_{std,mac}.lua` into single + `core/ext/key_commands.lua`. +* Can use the `Tab` and `Shift+Tab` keys for snippets now. +* Removed support for Textmate-style snippets in favor of Lua-style snippets. +* Load drag-and-dropped directories into file browser. +* Can toggle showing "dot" files in file browser. +* Prompt for file reload when files are modified outside Textadept. +* Added `textadept.context_menu` field for right-click inside Scintilla. +* Project Manager cursors are saved and restored. +* Only use escape sequences in Lua pattern searches. +* Rewrote `modules/textadept/run.lua` to be easier to use and configure. +* Find in Files marks the selected line for easier reference. +* Save special buffers in session file (e.g. error buffer, message buffer, etc.) +* Moved mime-types into `core/ext/mime_types.conf` configuration file. +* Moved localization into `core/locale.conf` configuration file. + +## 1.4 (10 Feb 2009) + +Bugfixes: + +* Handle empty clipboard properly. +* Fixed some widget focus issues. +* Fixed a couple Find in Files bugs. +* Workaround for GTK-OSX pasting issue. + +Updates: + +* Added menu options for changing line endings. +* The Project Manager Entry responds better. +* Improved Lua State integrity for critical data. +* Keep only 10 items in Find/Replace history. +* Special buffers are not "Untitled" anymore. +* Moved `textadept.locale` table to `_G`. + +## 1.3 (30 Jan 2009) + +Bugfixes: + +* Binary files are opened and handled properly. +* Drag-and-dropped files are now opened in the correct split view they were + dropped in. +* Fixed some various GTK-OSX UI issues. +* Fixed a special case of "Replace All". +* Clicking "Ok" closes any error dialogs on init. +* Fixed statusbar glitch when creating new buffers. +* Windows' CR+LF line endings are handled properly. +* Do not go to non-existent buffer index when loading session. +* Do not attempt to open non-existent files when double-clicking error messages. + +Updates: + +* Look for `~/.ta_theme` for setting Textadept `_THEME`. +* `_THEME` can now be a directory path. +* Themes now contain their own `lexer.lua` for defining lexer colors. +* Added "Find in Files" support. +* Can set the Project Manager cursor through Lua. +* Look for `~/.ta_modules` to load instead of default modules in `init.lua`. +* Added "Replace All" for just selected text. +* Removed menu label text in favor of using menu id numbers for menu actions. +* Added Find/Replace history. +* Use a combo entry for the Project Manager browser entry. +* Print messages to a split view instead of switching buffers. + +## 1.2 (21 Jan 2009) + +Bugfixes: + +* None. + +Updates: + +* Windows command line support ("Open With Textadept" works too). +* New [`_m.textadept.run`][] module for compiling and running programs. Output + is displayed in a message buffer and you can double-click errors and warnings + to go to them in the source file. + +[`_m.textadept.run`]: api/_M.textadept.run.html + +## 1.1 (11 Jan 2009) + +Bugfixes: + +* Fixed `core/ext/key_commands_std.lua` key conflict (`Ctrl+V`). + +Updates: + +* Dramatic speed increase in lexing for large, single-language files. +* Added [localization][] support. +* Added [bookmarks][] support. +* All `require` statements have been moved to `init.lua` for easy module + configuration. +* Various improvements to efficiency, speed, and readability of source code. +* Manually parse `~/.gtkrc-2.0` on Mac since GTK-OSX does not do it. + +[localization]: api/_L.html +[bookmarks]: api/_M.textadept.bookmarks.html + +## 1.0 (01 Jan 2009) + +Bugfixes: + +* Fixed bug with placeholders in Lua-style snippets. +* Fixed view grow/shrink error thrown when the view is not split. +* Various fixes to recognize windows directory separators. +* Fixed some Find bugs. +* Fixed macro recording and playback bugs. + +Updates: + +* Added actions for all menu items. +* Added Lua interface functions and fields for the [find][] box. +* Nearly full Mac OSX support with [GTK-OSX][]. +* Compile [LPeg][] and [LuaFileSystem][] libraries into Textadept by default. +* Use UTF-8 encoding by default. +* Added `light` color theme used by default. +* New Textadept icons. +* Added a true project manager. + +[find]: api/gui.find.html +[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/ + +## 0.6 (03 Oct 2008) + +Bugfixes: + +* Gracefully exit when `core/init.lua` fails to load. + +Updates: + +* Windows support! (finally) +* [Theming][] support (SciTE theme used by default). +* Added `textadept.size` field and save it in session files. +* Some C++ API-simplifying changes. +* Drag-and-drop files into Textadept works as expected. +* Revised [manual][]. +* Buffer and View properties are no longer set in C++, but in Lua through + "buffer_new" and "view_new" event handlers respectively. +* File types can be recognized by [pattern matching][] the first line. + +[Theming]: manual/8_Themes.html +[manual]: manual +[pattern matching]: manual/9_Preferences.html#Detect.by.Pattern + +## 0.5 (23 Jul 2008) + +Bugfixes: + +* Fixed bug in Lua module when there is no matching file to go to. + +Updates: + +* Added user-friendly key commands and menus. +* Added 43 more lexers. +* Moved block-comment commands from language modules to `textadept.editing` + module. +* Updated some Luadoc. + +## 0.4 (25 Jun 2008) + +Bugfixes: + +* Fixed bug with "%" being contained in text to replace. +* Fixed compile warnings. +* Fixed bug for menu actions on non-focused buffer. + +Updates: + +* Added [bookmark][] support through `modules/textadept/bookmarks.lua` (not + loaded by default). +* Added icons to Textadept. +* Added a modules browser for adding, deleting, and editing modules easily. +* Consolidated source files into `textadept.c`, `textadept.h`, and + `lua_interface.c`. +* Always load project manager settings from session file if available. +* Include `liblua5.1.a` for compiling Lua into Textadept. +* Added true [tab-completion][] to Lua command entry. +* Added Doxygen documentation for C source files. +* Updated Luadoc, and added Textadept manual. + +[bookmark]: api/_M.textadept.bookmarks.html +[tab-completion]: manual/10_Advanced.html#Tab.Completion + +## 0.3 (04 Mar 2008) + +Bugfixes: + +* Fixed bug in editing module's [`select_indented_block()`][]. +* Fixed empty `buffer.filename` bug in `textadept.io.save_as()`. +* Fixed setting of Ruby lexer after detecting filetype. + +Updates: + +* Makefile builds Textadept to optimize for small size. +* Lua is no longer an external dependency and built into Textadept. +* [Zenity][] is no longer a dependency on Linux. [lua_dialog][] is used instead. +* Resources from `io.popen()` are handled more appropriately. +* Added `textadept.reset()` function for for reloading Lua scripts. +* Added new find in files project manager browser. +* Fixed some code redundancy and typos in documentation. + +[`select_indented_block()`]: api/_M.textadept.editing.html#select_indented_block +[Zenity]: http://live.gnome.org/Zenity +[lua_dialog]: http://luaforge.net/projects/lua-dialog + +## 0.2 (20 Dec 2007) + +Bugfixes: + +* Fixed command line parameters bug. +* Fixed `package.path` precedence bug. +* Use 8 style bits by default. + +Updates: + +* Scintilla-st. +* Lexers. +* Improved support for embedded language-specific snippets. + +## 0.1 (01 Dec 2007) + +Initial Release diff --git a/README.md b/README.md new file mode 100644 index 00000000..6bc94601 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# Textadept + +## Overview + +Textadept is a fast, minimalist, and ridiculously 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 options without +sacrificing speed or succumbing to code bloat and featuritis. + +[Lua]: http://lua.org + +## Features + +* Self-contained executable -- no installation necessary. +* Entirely keyboard driven. +* Unlimited split views. +* Support for over 80 programming languages. +* Powerful snippets and key commands. +* Code autocompletion and API lookup. +* Unparalleled extensibility. + +## Requirements + +In its bid for minimalism, Textadept has no dependencies on Windows and Mac OSX +operating systems and depends only on [GTK+ 2.0][] version 2.16 or greater on +Linux. Lua is pre-compiled into Textadept on all platforms and a GTK runtime is +included on Windows and Mac OSX. + +[GTK+ 2.0]: http://gtk.org + +## Download + +Download Textadept from the [project page][]. + +[project page]: http://foicica.com/textadept + +## Installation and Usage + +Textadept comes with a comprehensive manual and API documentation in the `doc/` +directory. They are also available [online][]. + +[online]: http://foicica.com/textadept + +## Contact + +Contact me by email: mitchell.at.foicica.com. + +There is also a [mailing list][]. + +[mailing list]: http://foicica.com/lists diff --git a/THANKS.md b/THANKS.md new file mode 100644 index 00000000..28a971ac --- /dev/null +++ b/THANKS.md @@ -0,0 +1,30 @@ +# Thanks
+
+Thank you everyone for your contributions and feedback. They have helped make
+Textadept the amazing editor that it is today.
+
+## Code and Documentation Contributors
+
+* Alex Bepple
+* Anton Verbitski
+* Brian Schott
+* Callum Wilson
+* Jay Gould
+* Jeff Stone
+* M Rawash
+* Martin Morawetz
+* Neil Hodgson
+* Nils Nordman
+* Patrick McMorris
+* Robert Gieseke
+* Russell Dickinson
+* Ryan Pusztai
+* Scott Weisman
+* Steve Donovan
+* Tymur Gubayev
+* Vais Salikhov
+* Vladimir Lomov
+
+If I have left off your name, please [contact me][]. I am very sorry about that.
+
+[contact me]: README.html#Contact
diff --git a/core/._M.luadoc b/core/._M.luadoc index 04d2e938..bf9ed787 100644 --- a/core/._M.luadoc +++ b/core/._M.luadoc @@ -13,52 +13,64 @@ module('_M')]] -- Note that while language-specific modules can only be used by files of that -- language, they persist in Textadept's Lua state. Because of this, it is not -- recommended to set global functions or variables and depend on them, as they --- may be inadvertantly overwritten. Keep these inside the module. +-- may be inadvertantly overwritten. Keep them inside the module. -- -- ## Structure -- -- Each module should have an `init.lua` that `require`s all submodules it -- needs. For an example, see `modules/textadept/init.lua`. -- --- ## Recommended Features for Language-Specific Modules +-- ## Language-Specific Modules -- --- #### Snippets +-- The following is a list of recommended features for Language-Specific +-- modules. They are all entirely optional. -- --- [Snippets](../modules/_M.textadept.snippets.html) for common code constructs. +-- ### Snippets -- --- #### Commands +-- [Snippets][] for common code constructs. -- --- ##### Run +-- [Snippets]: _M.textadept.snippets.html +-- +-- ### Commands +-- +-- #### Run -- -- If the code can be run by an interpreter or other executable, create a [run --- command](../modules/_M.textadept.run.html#run_command) for it as well as an --- [error format](../modules/_M.textadept.run.html#error_detail) for the ability --- to jump to the position in a file where the error occured. +-- command][] for it as well as an [error format][] for the ability to jump to +-- the position in a file where the error occured. -- -- For example: -- -- _M.textadept.run.run_command.lua = 'lua %(filename)' -- --- ##### Compile +-- [run command]: _M.textadept.run.html#run_command +-- [error format]: _M.textadept.run.html#error_detail +-- +-- #### Compile -- --- If the code can be compiled by an executable, create a [compile --- command](../modules/_M.textadept.run.html#compile_command) for it. +-- If the code can be compiled by an executable, create a [compile command][] +-- for it. -- -- For example: -- -- _M.textadept.run.compile_command.lua = 'luac %(filename)' -- --- ##### Block Comment +-- [compile command]: _M.textadept.run.html#compile_command +-- +-- #### Block Comment +-- +-- Create a [comment prefix][] for it so code can be easily commented and +-- uncommented. -- --- Create a [comment --- prefix](../modules/_M.textadept.editing.html#comment_string) for it so code --- can be easily commented and uncommented. +-- [comment prefix]: _M.textadept.editing.html#comment_string -- -- For example: -- -- _M.textadept.editing.comment_string.lua = '--' -- --- #### Buffer Properties +-- [comment prefix]: _M.textadept.editing.html#comment_string +-- +-- ### Buffer Properties -- -- Add a `set_buffer_properties` function with default buffer properties for -- code like tab and indentation settings. @@ -72,7 +84,7 @@ module('_M')]] -- buffer.indent = 2 -- end -- --- #### Context Menu (Optional) +-- ### Context Menu -- -- Language-specific context menus, accessible by right-clicking inside the -- view, can be defined as: @@ -84,16 +96,3 @@ module('_M')]] -- } -- -- See `modules/textadept/menu.lua` for examples on how to define menus. --- --- ## Modules and Key Commands --- --- When assigning [key commands](../modules/_M.textadept.keys.html) to module --- functions, do not forget to do so AFTER the function has been defined. --- Typically key commands are placed at the end of files, like `init.lua` in --- the `textadept` module. - ---- --- This module contains no functions. --- @class function --- @name no_functions -local no_functions diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc index e2acea09..52be35cf 100644 --- a/core/.buffer.luadoc +++ b/core/.buffer.luadoc @@ -45,13 +45,12 @@ module('buffer') -- looking up the style. -- * `annotation_visible` [number] -- The visibility of annotations. --- * `_SCINTILLA.constants.ANNOTATION_HIDDEN` (0) --- Annotations are not displayed. --- * `_SCINTILLA.constants.ANNOTATION_STANDARD` (1) --- Annotations are drawn left justified with no adornment. --- * `_SCINTILLA.constants.ANNOTATION_BOXED` (2) --- Annotations are indented to match the text and are surrounded by a --- box. +-- * `_SCINTILLA.constants.ANNOTATION_HIDDEN` (0) +-- Annotations are not displayed. +-- * `_SCINTILLA.constants.ANNOTATION_STANDARD` (1) +-- Annotations are drawn left justified with no adornment. +-- * `_SCINTILLA.constants.ANNOTATION_BOXED` (2) +-- Annotations are indented to match the text and are surrounded by a box. -- * `auto_c_auto_hide` [bool] -- Whether or not autocompletion is hidden automatically when nothing matches. -- By default, the list is cancelled if there are no viable matches (the user @@ -131,26 +130,26 @@ module('buffer') -- 500 milliseconds. -- * `caret_sticky` [number] -- The caret preferred x position changing when the user types. --- * `_SCINTILLA.constants.SC_CARETSTICKY_OFF` (0) --- All text changes (and all caret position changes) will remember the --- caret's new horizontal position when moving to different lines. --- This is the default. --- * `_SCINTILLA.constants.SC_CARETSTICKY_ON` (1) --- The only thing which will cause the editor to remember the horizontal --- caret position is moving the caret with mouse or keyboard (left/right --- arrow keys, home/end keys, etc). --- * `_SCINTILLA.constants.SC_CARETSTICKY_WHITESPACE` (2) --- The caret acts like sticky off except under one special case; when --- space or tab characters are inserted. (Including pasting --- *only space/tabs* -- undo, redo, etc. do not exhibit this behavior.) +-- * `_SCINTILLA.constants.SC_CARETSTICKY_OFF` (0) +-- All text changes (and all caret position changes) will remember the +-- caret's new horizontal position when moving to different lines. +-- This is the default. +-- * `_SCINTILLA.constants.SC_CARETSTICKY_ON` (1) +-- The only thing which will cause the editor to remember the horizontal +-- caret position is moving the caret with mouse or keyboard (left/right +-- arrow keys, home/end keys, etc). +-- * `_SCINTILLA.constants.SC_CARETSTICKY_WHITESPACE` (2) +-- The caret acts like sticky off except under one special case; when +-- space or tab characters are inserted. (Including pasting +-- *only space/tabs* -- undo, redo, etc. do not exhibit this behavior.) -- * `caret_style` [number] -- The style of the caret to be drawn. --- * `_SCINTILLA.constants.CARETSTYLE_INVISIBLE` (0) --- Not draw the caret at all. --- * `_SCINTILLA.constants.CARETSTYLE_LINE` (1) --- A line caret. This is the default value. --- * `_SCINTILLA.constants.CARETSTYLE_BLOCK` (2) --- A block caret. +-- * `_SCINTILLA.constants.CARETSTYLE_INVISIBLE` (0) +-- Not draw the caret at all. +-- * `_SCINTILLA.constants.CARETSTYLE_LINE` (1) +-- A line caret. This is the default value. +-- * `_SCINTILLA.constants.CARETSTYLE_BLOCK` (2) +-- A block caret. -- * `caret_width` [number] -- The width of the insert mode caret in pixels. -- Can be `0`, `1`, `2` or `3` pixels. The default width is 1 pixel. This @@ -174,10 +173,10 @@ module('buffer') -- When setting, the caret is not scrolled into view. -- * `cursor` [number] -- The cursor type. --- * `_SCINTILLA.constants.SC_CURSORNORMAL` (-1) --- The normal cursor is displayed. --- * `_SCINTILLA.constants.SC_CURSORWAIT` (4) --- The wait cursor is displayed when the mouse is over the view. +-- * `_SCINTILLA.constants.SC_CURSORNORMAL` (-1) +-- The normal cursor is displayed. +-- * `_SCINTILLA.constants.SC_CURSORWAIT` (4) +-- The wait cursor is displayed when the mouse is over the view. -- * `direct_function` [number] (Read-only) -- A pointer to a function that processes messages for this view. -- * `direct_pointer` [number] (Read-only) @@ -188,26 +187,26 @@ module('buffer') -- last saved. -- * `eol_mode` [number] -- The current end of line mode. --- * `_SCINTILLA.constants.SC_EOL_CRLF` (0) --- `CRLF`. --- * `_SCINTILLA.constants.SC_EOL_CR` (1) --- `CR`. --- * `_SCINTILLA.constants.SC_EOL_LF` (2) --- `LF`. +-- * `_SCINTILLA.constants.SC_EOL_CRLF` (0) +-- `CRLF`. +-- * `_SCINTILLA.constants.SC_EOL_CR` (1) +-- `CR`. +-- * `_SCINTILLA.constants.SC_EOL_LF` (2) +-- `LF`. -- * `edge_colour` [number] -- The color used in edge indication in `0xBBGGRR` format. -- * `edge_column` [number] -- The column number which text should be kept within. -- * `edge_mode` [number] -- The edge highlight mode. --- * `_SCINTILLA.constants.EDGE_NONE` (0) --- Long lines are not marked. This is the default state. --- * `_SCINTILLA.constants.EDGE_LINE` (1) --- A vertical line is drawn at the column number set by --- `buffer.edge_column`. --- * `_SCINTILLA.constants.EDGE_BACKGROUND` (2) --- The background color of characters after the column limit is changed --- to the color set by `buffer.edge_colour`. +-- * `_SCINTILLA.constants.EDGE_NONE` (0) +-- Long lines are not marked. This is the default state. +-- * `_SCINTILLA.constants.EDGE_LINE` (1) +-- A vertical line is drawn at the column number set by +-- `buffer.edge_column`. +-- * `_SCINTILLA.constants.EDGE_BACKGROUND` (2) +-- The background color of characters after the column limit is changed to +-- the color set by `buffer.edge_colour`. -- * `encoding` [string or nil] -- The encoding of the file on the hard disk. -- It will be `nil` if the file is a binary file. @@ -228,8 +227,7 @@ module('buffer') -- added to each line. -- * `filename` [string] -- The absolute path to the file associated with this buffer. --- It is encoded in UTF-8. Use [`string.iconv()`][string_iconv] for charset --- conversions. +-- It is encoded in UTF-8. Use [`string.iconv()`][] for charset conversions. -- * `first_visible_line` [number] -- The display line at the top of the display. -- * `focus` [bool] @@ -240,21 +238,21 @@ module('buffer') -- Table of fold levels for lines starting from zero. -- Fold levels encodes an integer level along with flags indicating whether -- the line is a header and whether it is effectively white space. --- * `_SCINTILLA.constants.SC_FOLDLEVELBASE` (0x400) --- Initial fold level. --- * `_SCINTILLA.constants.SC_FOLDLEVELWHITEFLAG` (0x1000) --- Indicates that the line is blank. --- * `_SCINTILLA.constants.SC_FOLDLEVELHEADERFLAG` (0x2000) --- Indicates that the line is a header (fold point). +-- * `_SCINTILLA.constants.SC_FOLDLEVELBASE` (0x400) +-- Initial fold level. +-- * `_SCINTILLA.constants.SC_FOLDLEVELWHITEFLAG` (0x1000) +-- Indicates that the line is blank. +-- * `_SCINTILLA.constants.SC_FOLDLEVELHEADERFLAG` (0x2000) +-- Indicates that the line is a header (fold point). -- * `fold_parent` [table] (Read-only) -- Table of parent line numbers for child lines starting from zero. -- `-1` means no line was found. -- * `font_quality` [number] (Windows only) -- The quality level for text. --- * `_SCINTILLA.constants.SC_EFF_QUALITY_DEFAULt` (0). --- * `_SCINTILLA.constants.SC_EFF_QUALITY_NON_ANTIALIASED` (1). --- * `_SCINTILLA.constants.SC_EFF_QUALITY_ANTIALIASED` (2). --- * `_SCINTILLA.constants.SC_EFF_QUALITY_LCD_OPTIMIZED` (3). +-- * `_SCINTILLA.constants.SC_EFF_QUALITY_DEFAULt` (0). +-- * `_SCINTILLA.constants.SC_EFF_QUALITY_NON_ANTIALIASED` (1). +-- * `_SCINTILLA.constants.SC_EFF_QUALITY_ANTIALIASED` (2). +-- * `_SCINTILLA.constants.SC_EFF_QUALITY_LCD_OPTIMIZED` (3). -- * `h_scroll_bar` [bool] -- Whether the horizontal scroll bar is visible. -- Set to `false` to never see it and `true` to enable it again. The default @@ -274,21 +272,21 @@ module('buffer') -- Indentation guides appearance. -- Indentation guides are dotted vertical lines that appear within indentation -- white space every indent size columns. --- * `_SCINTILLA.constants.SC_IV_NONE` (0) --- No indentation guides are shown. --- * `_SCINTILLA.constants.SC_IV_REAL` (1) --- Indentation guides are shown inside real indentation white space. --- * `_SCINTILLA.constants.SC_IV_LOOKFORWARD` (2) --- Indentation guides are shown beyond the actual indentation up to the --- level of the next non-empty line. --- If the previous non-empty line was a fold header then indentation --- guides are shown for one more level of indent than that line. This --- setting is good for Python. --- * `_SCINTILLA.constants.SC_IV_LOOKBOTH` (3) --- Indentation guides are shown beyond the actual indentation up to the --- level of the next non-empty line or previous non-empty line whichever --- is the greater. --- This setting is good for most languages. +-- * `_SCINTILLA.constants.SC_IV_NONE` (0) +-- No indentation guides are shown. +-- * `_SCINTILLA.constants.SC_IV_REAL` (1) +-- Indentation guides are shown inside real indentation white space. +-- * `_SCINTILLA.constants.SC_IV_LOOKFORWARD` (2) +-- Indentation guides are shown beyond the actual indentation up to the +-- level of the next non-empty line. +-- If the previous non-empty line was a fold header then indentation +-- guides are shown for one more level of indent than that line. This +-- setting is good for Python. +-- * `_SCINTILLA.constants.SC_IV_LOOKBOTH` (3) +-- Indentation guides are shown beyond the actual indentation up to the +-- level of the next non-empty line or previous non-empty line whichever +-- is the greater. +-- This setting is good for most languages. -- * `indic_alpha` [table] -- Table of alpha transparency values ranging from `0` (transparent) to `255` -- (opaque) or `256` (no alpha) for indicators from `0` to `31`. @@ -304,48 +302,48 @@ module('buffer') -- `INDIC_STRAIGHTBOX` rectangle. -- * `indic_style` [table] -- Table of styles for indicators from `0` to `31`. --- * `_SCINTILLA.constants.INDIC_PLAIN` (0) --- Underlined with a single, straight line. --- * `_SCINTILLA.constants.INDIC_SQUIGGLE` (1) --- A squiggly underline. Requires 3 pixels of descender space. --- * `_SCINTILLA.constants.INDIC_TT` (2) --- A line of small T shapes. --- * `_SCINTILLA.constants.INDIC_DIAGONAL` (3) --- Diagonal hatching. --- * `_SCINTILLA.constants.INDIC_STRIKE` (4) --- Strike out. --- * `_SCINTILLA.constants.INDIC_HIDDEN` (5) --- An indicator with no visual effect. --- * `_SCINTILLA.constants.INDIC_BOX` (6) --- A rectangle around the text. --- * `_SCINTILLA.constants.INDIC_ROUNDBOX` (7) --- A rectangle with rounded corners around the text using translucent --- drawing with the interior usually more transparent than the border. --- Use `buffer.indic_alpha` and `buffer.indic_outline_alpha` to control --- the alpha transparency values. The default alpha values are `30` for --- fill color and `50` for outline color. --- * `_SCINTILLA.constants.INDIC_STRAIGHTBOX` (8) --- A rectangle around the text using translucent drawing with the --- interior usually more transparent than the border. --- You can use `buffer.indic_alpha` and `buffer.indic_outline_alpha` to --- control the alpha transparency values. The default alpha values are --- `30` for fill color and `50` for outline color. --- * `_SCINTILLA.constants.INDIC_DASH` (9) --- A dashed underline. --- * `_SCINTILLA.constants.INDIC_DOTS` (10) --- A dotted underline. --- * `_SCINTILLA.constants.INDIC_SQUIGGLELOW` (11) --- Similar to `INDIC_SQUIGGLE` but only using 2 vertical pixels so will --- fit under small fonts. --- * `_SCINTILLA.constants.INDIC_DOTBOX` (12) --- A dotted rectangle around the text using translucent drawing. --- Translucency alternates between the alpha and outline alpha settings --- with the top-left pixel using the alpha setting. `buffer.indic_alpha` --- and `buffer.indic_outline_alpha` control the alpha transparency --- values. The default values are `30` for alpha and `50` for outline --- alpha. To avoid excessive memory allocation the maximum width of a --- dotted box is 4000 pixels. --- * Use `_SCINTILLA.next_indic_number()` for custom indicators. +-- * `_SCINTILLA.constants.INDIC_PLAIN` (0) +-- Underlined with a single, straight line. +-- * `_SCINTILLA.constants.INDIC_SQUIGGLE` (1) +-- A squiggly underline. Requires 3 pixels of descender space. +-- * `_SCINTILLA.constants.INDIC_TT` (2) +-- A line of small T shapes. +-- * `_SCINTILLA.constants.INDIC_DIAGONAL` (3) +-- Diagonal hatching. +-- * `_SCINTILLA.constants.INDIC_STRIKE` (4) +-- Strike out. +-- * `_SCINTILLA.constants.INDIC_HIDDEN` (5) +-- An indicator with no visual effect. +-- * `_SCINTILLA.constants.INDIC_BOX` (6) +-- A rectangle around the text. +-- * `_SCINTILLA.constants.INDIC_ROUNDBOX` (7) +-- A rectangle with rounded corners around the text using translucent +-- drawing with the interior usually more transparent than the border. Use +-- `buffer.indic_alpha` and `buffer.indic_outline_alpha` to control the +-- alpha transparency values. The default alpha values are `30` for fill +-- color and `50` for outline color. +-- * `_SCINTILLA.constants.INDIC_STRAIGHTBOX` (8) +-- A rectangle around the text using translucent drawing with the interior +-- usually more transparent than the border. +-- You can use `buffer.indic_alpha` and `buffer.indic_outline_alpha` to +-- control the alpha transparency values. The default alpha values are +-- `30` for fill color and `50` for outline color. +-- * `_SCINTILLA.constants.INDIC_DASH` (9) +-- A dashed underline. +-- * `_SCINTILLA.constants.INDIC_DOTS` (10) +-- A dotted underline. +-- * `_SCINTILLA.constants.INDIC_SQUIGGLELOW` (11) +-- Similar to `INDIC_SQUIGGLE` but only using 2 vertical pixels so will +-- fit under small fonts. +-- * `_SCINTILLA.constants.INDIC_DOTBOX` (12) +-- A dotted rectangle around the text using translucent drawing. +-- Translucency alternates between the alpha and outline alpha settings +-- with the top-left pixel using the alpha setting. `buffer.indic_alpha` +-- and `buffer.indic_outline_alpha` control the alpha transparency values. +-- The default values are `30` for alpha and `50` for outline alpha. To +-- avoid excessive memory allocation the maximum width of a dotted box is +-- 4000 pixels. +-- * Use `_SCINTILLA.next_indic_number()` for custom indicators. -- * `indic_under` [table] -- Table of booleans for drawing under text or over (default) for indicators -- from `0` to `31`. @@ -359,15 +357,15 @@ module('buffer') -- Interpret keyboard input as Unicode. -- * `layout_cache` [number] -- The degree of caching of layout information. --- * `_SCINTILLA.constants.SC_CACHE_NONE` (0) --- No lines are cached. --- * `_SCINTILLA.constants.SC_CACHE_CARET` (1) --- The line containing the text caret. --- This is the default. --- * `_SCINTILLA.constants.SC_CACHE_PAGE` (2) --- Visible lines plus the line containing the caret. --- * `_SCINTILLA.constants.SC_CACHE_DOCUMENT` (3) --- All lines in the document. +-- * `_SCINTILLA.constants.SC_CACHE_NONE` (0) +-- No lines are cached. +-- * `_SCINTILLA.constants.SC_CACHE_CARET` (1) +-- The line containing the text caret. +-- This is the default. +-- * `_SCINTILLA.constants.SC_CACHE_PAGE` (2) +-- Visible lines plus the line containing the caret. +-- * `_SCINTILLA.constants.SC_CACHE_DOCUMENT` (3) +-- All lines in the document. -- * `length` [number] (Read-only) -- The number of bytes in the document. -- * `lexer` [number] @@ -404,10 +402,10 @@ module('buffer') -- * `margin_cursor_n` [table] -- Table of cursors shown for margins from zero to four. -- A reversed arrow cursor is normally shown over all margins. --- * `_SCINTILLA.constants.SC_CURSORARROW` --- Normal arrow. --- * `_SCINTILLA.constants.SC_CURSORREVERSEARROW` --- Reversed arrow. +-- * `_SCINTILLA.constants.SC_CURSORARROW` +-- Normal arrow. +-- * `_SCINTILLA.constants.SC_CURSORREVERSEARROW` +-- Reversed arrow. -- * `margin_left` [number] -- The size in pixels of the left margin. -- The default is to one pixel. @@ -416,13 +414,13 @@ module('buffer') -- A mask determines which markers are displayed in a margin. -- * `margin_options` [number] -- A bit mask of margin options. --- * `_SCINTILLA.constants.SC_MARGINOPTION_NONE` (0) --- None (default). --- * `_SCINTILLA.constants.SC_MARGINOPTION_SUBLINESELECT` (1) --- Controls how wrapped lines are selected when clicking on margin in --- front of them. --- If set, only sub line of wrapped line is selected, otherwise whole --- wrapped line is selected. +-- * `_SCINTILLA.constants.SC_MARGINOPTION_NONE` (0) +-- None (default). +-- * `_SCINTILLA.constants.SC_MARGINOPTION_SUBLINESELECT` (1) +-- Controls how wrapped lines are selected when clicking on margin in +-- front of them. +-- If set, only sub line of wrapped line is selected, otherwise whole +-- wrapped line is selected. -- * `margin_right` [number] -- The size in pixels of the right margin. -- The default is to one pixel. @@ -441,20 +439,20 @@ module('buffer') -- the offset added before looking up the style. -- * `margin_type_n` [table] -- Table of margin types for margins from zero to four. --- * `_SCINTILLA.constants.SC_MARGIN_SYMBOL` (0) --- A symbol margin. --- * `_SCINTILLA.constants.SC_MARGIN_NUMBER` (1) --- A line number margin. --- * `_SCINTILLA.constants.SC_MARGIN_BACK` (2) --- A symbol margin that sets its background color to match the default --- text background color. --- * `_SCINTILLA.constants.SC_MARGIN_FORE` (3) --- A symbol margin that sets its background color to match the default --- text foreground color. --- * `_SCINTILLA.constants.SC_MARGIN_TEXT` (4) --- A text margin. --- * `_SCINTILLA.constants.SC_MARGIN_RTEXT` (5) --- A right justified text margin. +-- * `_SCINTILLA.constants.SC_MARGIN_SYMBOL` (0) +-- A symbol margin. +-- * `_SCINTILLA.constants.SC_MARGIN_NUMBER` (1) +-- A line number margin. +-- * `_SCINTILLA.constants.SC_MARGIN_BACK` (2) +-- A symbol margin that sets its background color to match the default +-- text background color. +-- * `_SCINTILLA.constants.SC_MARGIN_FORE` (3) +-- A symbol margin that sets its background color to match the default +-- text foreground color. +-- * `_SCINTILLA.constants.SC_MARGIN_TEXT` (4) +-- A text margin. +-- * `_SCINTILLA.constants.SC_MARGIN_RTEXT` (5) +-- A right justified text margin. -- * `margin_width_n` [table] -- Table of margin widths expressed in pixes for margins from zero to four. -- * `max_line_state` [number] (Read-only) @@ -469,10 +467,10 @@ module('buffer') -- events are generated. -- * `multi_paste` [bool] -- The effect of pasting when there are multiple selections. --- * `_SCINTILLA.constants.SC_MULTIPASTE_ONCE` (0) --- Pasted text can go into just the main selection (default). --- * `_SCINTILLA.constants.SC_MULTIPASTE_EACH` (1) --- Pasted text can go into each selection. +-- * `_SCINTILLA.constants.SC_MULTIPASTE_ONCE` (0) +-- Pasted text can go into just the main selection (default). +-- * `_SCINTILLA.constants.SC_MULTIPASTE_EACH` (1) +-- Pasted text can go into each selection. -- * `multiple_selection` [bool] -- Whether multiple selections can be made. -- When multiple selection is disabled, it is not possible to select multiple @@ -485,33 +483,33 @@ module('buffer') -- that their layout can be determined more quickly if the run recurs. -- * `print_colour_mode` [number] -- The print color mode. --- * `_SCINTILLA.constants.SC_PRINT_NORMAL` (0) --- Print using the current screen colors. --- This is the default. --- * `_SCINTILLA.constants.SC_PRINT_INVERTLIGHT` (1) --- If you use a dark screen background this saves ink by inverting the --- light value of all colors and printing on a white background. --- * `_SCINTILLA.constants.SC_PRINT_BLACKONWHITE` (2) --- Print all text as black on a white background. --- * `_SCINTILLA.constants.SC_PRINT_COLOURONWHITE` (3) --- Everything prints in its own color on a white background. --- * `_SCINTILLA.constants.SC_PRINT_COLOURONWHITEDEFAULTBG` (4) --- Everything prints in its own color on a white background except that --- line numbers use their own background color. +-- * `_SCINTILLA.constants.SC_PRINT_NORMAL` (0) +-- Print using the current screen colors. +-- This is the default. +-- * `_SCINTILLA.constants.SC_PRINT_INVERTLIGHT` (1) +-- If you use a dark screen background this saves ink by inverting the +-- light value of all colors and printing on a white background. +-- * `_SCINTILLA.constants.SC_PRINT_BLACKONWHITE` (2) +-- Print all text as black on a white background. +-- * `_SCINTILLA.constants.SC_PRINT_COLOURONWHITE` (3) +-- Everything prints in its own color on a white background. +-- * `_SCINTILLA.constants.SC_PRINT_COLOURONWHITEDEFAULTBG` (4) +-- Everything prints in its own color on a white background except that +-- line numbers use their own background color. -- * `print_magnification` [number] -- The print magnification added to the point size of each style for printing. -- * `print_wrap_mode` [number] -- Printing line wrap mode. --- * `_SCINTILLA.constants.SC_WRAP_NONE` (0) --- Each line of text generates one line of output and the line is --- truncated if it is too long to fit into the print area. --- * `_SCINTILLA.constants.SC_WRAP_WORD` (1) --- Wraps printed output so that all characters fit into the print --- rectangle. --- Tries to wrap only between words as indicated by white space or style --- changes although if a word is longer than a line, it will be wrapped --- before the line end. This is the default. --- * `_SCINTILLA.constants.SC_WRAP_CHAR` (2). +-- * `_SCINTILLA.constants.SC_WRAP_NONE` (0) +-- Each line of text generates one line of output and the line is +-- truncated if it is too long to fit into the print area. +-- * `_SCINTILLA.constants.SC_WRAP_WORD` (1) +-- Wraps printed output so that all characters fit into the print +-- rectangle. +-- Tries to wrap only between words as indicated by white space or style +-- changes although if a word is longer than a line, it will be wrapped +-- before the line end. This is the default. +-- * `_SCINTILLA.constants.SC_WRAP_CHAR` (2). -- * `property` [table] (Write-only) -- Table of keyword:value string pairs used by a lexer for some optional -- features. @@ -531,12 +529,12 @@ module('buffer') -- * `rectangular_selection_modifier` [number] -- The modifier key used to indicate that a rectangular selection should be -- created when combined with a mouse drag. --- * `_SCINTILLA.constants.SCMOD_CTRL` (2) --- Control key (default). --- * `_SCINTILLA.constants.SCMOD_ALT` (4) --- Alt key. --- * `_SCINTILLA.constants.SCMOD_SUPER` (8) --- Left Windows key on a Windows keyboard or the Command key on a Mac. +-- * `_SCINTILLA.constants.SCMOD_CTRL` (2) +-- Control key (default). +-- * `_SCINTILLA.constants.SCMOD_ALT` (4) +-- Alt key. +-- * `_SCINTILLA.constants.SCMOD_SUPER` (8) +-- Left Windows key on a Windows keyboard or the Command key on a Mac. -- * `rgba_image_height` [number] -- The height for future RGBA image data. -- * `rgba_image_width` [number] @@ -552,20 +550,20 @@ module('buffer') -- Whether the maximum width line displayed is used to set scroll width. -- * `search_flags` [number] -- The search flags used by `buffer:search_in_target()`. --- * `_SCINTILLA.constants.SCFIND_WHOLEWORD` (2) --- A match only occurs with text that matches the case of the search --- string. --- * `_SCINTILLA.constants.SCFIND_MATCHCASE` (4) --- A match only occurs if the characters before and after are not word --- characters. --- * `_SCINTILLA.constants.SCFIND_WORDSTART` (0x00100000) --- A match only occurs if the character before is not a word character. --- * `_SCINTILLA.constants.SCFIND_REGEXP` (0x00200000) --- The search string should be interpreted as a regular expression. --- * `_SCINTILLA.constants.SCFIND_POSIX` (0x00400000) --- Treat regular expression in a more POSIX compatible manner by --- interpreting bare `(` and `)` for tagged sections rather than `\(` --- and `\)`. +-- * `_SCINTILLA.constants.SCFIND_WHOLEWORD` (2) +-- A match only occurs with text that matches the case of the search +-- string. +-- * `_SCINTILLA.constants.SCFIND_MATCHCASE` (4) +-- A match only occurs if the characters before and after are not word +-- characters. +-- * `_SCINTILLA.constants.SCFIND_WORDSTART` (0x00100000) +-- A match only occurs if the character before is not a word character. +-- * `_SCINTILLA.constants.SCFIND_REGEXP` (0x00200000) +-- The search string should be interpreted as a regular expression. +-- * `_SCINTILLA.constants.SCFIND_POSIX` (0x00400000) +-- Treat regular expression in a more POSIX compatible manner by +-- interpreting bare `(` and `)` for tagged sections rather than `\(` and +-- `\)`. -- * `sel_alpha` [number] -- The alpha of the selection, between `0` (transparent) and `255` (opaque), -- or `256` for no alpha. @@ -581,14 +579,14 @@ module('buffer') -- The alternative is the more common stream selection. -- * `selection_mode` [number] -- The mode of the current selection. --- * `_SCINTILLA.constants.SC_SEL_STREAM` (0) --- Stream. --- * `_SCINTILLA.constants.SC_SEL_RECTANGLE` (1) --- Rectangle. --- * `_SCINTILLA.constants.SC_SEL_LINES` (2) --- Lines. --- * `_SCINTILLA.constants.SC_SEL_THIN` (3) --- Thin rectangular. +-- * `_SCINTILLA.constants.SC_SEL_STREAM` (0) +-- Stream. +-- * `_SCINTILLA.constants.SC_SEL_RECTANGLE` (1) +-- Rectangle. +-- * `_SCINTILLA.constants.SC_SEL_LINES` (2) +-- Lines. +-- * `_SCINTILLA.constants.SC_SEL_THIN` (3) +-- Thin rectangular. -- * `selection_n_anchor` [table] -- Table of anchor positions for existing selections starting from zero, the -- main selection. @@ -614,12 +612,12 @@ module('buffer') -- The number of selections currently active. -- * `status` [number] -- The error status. --- * `_SCINTILLA.constants.SC_STATUS_OK` (0) --- No failures. --- * `_SCINTILLA.constants.SC_STATUS_FAILURE` (1) --- Generic failure. --- * `_SCINTILLA.constants.SC_STATUS_BADALLOC` (2) --- Memory is exhausted. +-- * `_SCINTILLA.constants.SC_STATUS_OK` (0) +-- No failures. +-- * `_SCINTILLA.constants.SC_STATUS_FAILURE` (1) +-- Generic failure. +-- * `_SCINTILLA.constants.SC_STATUS_BADALLOC` (2) +-- Memory is exhausted. -- * `style_at` [table] (Read-only) -- Table of style bytes at positions in the document starting at zero. -- * `style_back` [table] @@ -633,12 +631,12 @@ module('buffer') -- Table of booleans for bold styles from `0` to `255`. -- * `style_case` [table] -- Table of cases for styles from `0` to `255`. --- * `_SCINTILLA.constants.SC_CASE_MIXED` (0) --- Normal, mixed case. --- * `_SCINTILLA.constants.SC_CASE_UPPER` (1) --- Upper case. --- * `_SCINTILLA.constants.SC_CASE_LOWER` (2) --- Lower case. +-- * `_SCINTILLA.constants.SC_CASE_MIXED` (0) +-- Normal, mixed case. +-- * `_SCINTILLA.constants.SC_CASE_UPPER` (1) +-- Upper case. +-- * `_SCINTILLA.constants.SC_CASE_LOWER` (2) +-- Lower case. -- * `style_changeable` [table] -- Table of booleans for changeable styles from `0` to `255`. -- The default setting is `true`. @@ -672,12 +670,12 @@ module('buffer') -- with 1 being very light and 999 very heavy. While any value can be used, -- fonts often only support between 2 and 4 weights with three weights being -- common enough to use symbolic names: --- * `_SCINTILLA.constants.SC_WEIGHT_NORMAL` (400) --- Normal. --- * `_SCINTILLA.constants.SC_WEIGHT_SEMIBOLD` (600) --- Semi-bold. --- * `_SCINTILLA.constants.SC_WEIGHT_BOLD` (700) --- Bold. +-- * `_SCINTILLA.constants.SC_WEIGHT_NORMAL` (400) +-- Normal. +-- * `_SCINTILLA.constants.SC_WEIGHT_SEMIBOLD` (600) +-- Semi-bold. +-- * `_SCINTILLA.constants.SC_WEIGHT_BOLD` (700) +-- Bold. -- * `tab_indents` [bool] -- Whether a tab pressed when caret is within indentation indents. -- * `tab_width` [number] @@ -714,22 +712,22 @@ module('buffer') -- Normally, the end of line characters are hidden. -- * `view_ws` [number] -- The visibility of white space characters. --- * `_SCINTILLA.constants.SCWS_INVISIBLE` (0) --- The normal display mode with white space displayed as an empty --- background color. --- * `_SCINTILLA.constants.SCWS_VISIBLEALWAYS` (1) --- White space characters are drawn as dots and arrows. --- * `_SCINTILLA.constants.SCWS_VISIBLEAFTERINDENT` (2) --- White space used for indentation is displayed normally but after the --- first visible character, it is shown as dots and arrows. +-- * `_SCINTILLA.constants.SCWS_INVISIBLE` (0) +-- The normal display mode with white space displayed as an empty +-- background color. +-- * `_SCINTILLA.constants.SCWS_VISIBLEALWAYS` (1) +-- White space characters are drawn as dots and arrows. +-- * `_SCINTILLA.constants.SCWS_VISIBLEAFTERINDENT` (2) +-- White space used for indentation is displayed normally but after the +-- first visible character, it is shown as dots and arrows. -- * `virtual_space_options` [number] -- Virtual space options. --- * `_SCINTILLA.constants.SCVS_NONE` (0) --- Disables all use of virtual space (default). --- * `_SCINTILLA.constants.SCVS_RECTANGULARSELECTION` (1) --- Enabled only for rectangular selections. --- * `_SCINTILLA.constants.SCVS_USERACCESSIBLE` (2) --- Enabled. +-- * `_SCINTILLA.constants.SCVS_NONE` (0) +-- Disables all use of virtual space (default). +-- * `_SCINTILLA.constants.SCVS_RECTANGULARSELECTION` (1) +-- Enabled only for rectangular selections. +-- * `_SCINTILLA.constants.SCVS_USERACCESSIBLE` (2) +-- Enabled. -- * `whitespace_chars` [string] (Write-only) -- The set of characters making up whitespace for when moving or selecting by -- word. @@ -737,45 +735,45 @@ module('buffer') -- * `wrap_indent_mode` [number] -- How wrapped sublines are placed. -- Default is fixed. --- * `_SCINTILLA.constants.SC_WRAP_INDENT_FIXED` (0) --- Wrapped sublines aligned to left of window plus amount set by --- `buffer.wrap_start_indent`. --- * `_SCINTILLA.constants.SC_WRAP_INDENT_SAME` (1) --- Wrapped sublines are aligned to first subline indent. --- * `_SCINTILLA.constants.SC_WRAP_INDENT_INDENT` (2) --- Wrapped sublines are aligned to first subline indent plus one more --- level of indentation. +-- * `_SCINTILLA.constants.SC_WRAP_INDENT_FIXED` (0) +-- Wrapped sublines aligned to left of window plus amount set by +-- `buffer.wrap_start_indent`. +-- * `_SCINTILLA.constants.SC_WRAP_INDENT_SAME` (1) +-- Wrapped sublines are aligned to first subline indent. +-- * `_SCINTILLA.constants.SC_WRAP_INDENT_INDENT` (2) +-- Wrapped sublines are aligned to first subline indent plus one more +-- level of indentation. -- * `whitespace_size` [number] -- The size of the dots used to mark space characters. -- * `word_chars` [string] -- The set of characters making up words when moving or selecting by word. -- * `wrap_mode` [number] -- Text word wrap mode. --- * `_SCINTILLA.constants.SC_WRAP_NONE` (0) --- Disable line wrapping. --- * `_SCINTILLA.constants.SC_WRAP_WORD` (1) --- Enable wrapping on word boundaries. --- * `_SCINTILLA.constants.SC_WRAP_CHAR` (2) --- Enable wrapping between any characters. +-- * `_SCINTILLA.constants.SC_WRAP_NONE` (0) +-- Disable line wrapping. +-- * `_SCINTILLA.constants.SC_WRAP_WORD` (1) +-- Enable wrapping on word boundaries. +-- * `_SCINTILLA.constants.SC_WRAP_CHAR` (2) +-- Enable wrapping between any characters. -- * `wrap_start_indent` [number] -- The start indent for wrapped lines. -- * `wrap_visual_flags` [number] -- The display mode of visual flags for wrapped lines. --- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_NONE` (0) --- No visual flags. --- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_END` (1) --- Visual flag at end of subline of a wrapped line. --- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_START` (2) --- Visual flag at begin of subline of a wrapped line. --- Subline is indented by at least 1 to make room for the flag. +-- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_NONE` (0) +-- No visual flags. +-- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_END` (1) +-- Visual flag at end of subline of a wrapped line. +-- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_START` (2) +-- Visual flag at begin of subline of a wrapped line. +-- Subline is indented by at least 1 to make room for the flag. -- * `wrap_visual_flags_location` [number] -- The location of visual flags for wrapped lines. --- * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_DEFAULT` (0) --- Visual flags drawn near border. --- * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_END_BY_TEXT` (1) --- Visual flag at end of subline drawn near text. --- * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_START_BY_TEXT` (2) --- Visual flag at beginning of subline drawn near text. +-- * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_DEFAULT` (0) +-- Visual flags drawn near border. +-- * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_END_BY_TEXT` (1) +-- Visual flag at end of subline drawn near text. +-- * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_START_BY_TEXT` (2) +-- Visual flag at beginning of subline drawn near text. -- * `x_offset` [number] -- The horizontal scroll position. -- A value of `0` is the normal position with the first text column visible at @@ -784,7 +782,7 @@ module('buffer') -- The number of points added to the size of all fonts. -- It may be positive to magnify or negative to reduce. -- --- [string_iconv]: ../modules/string.html#iconv +-- [`string.iconv()`]: string.html#iconv --- -- Add a selection from anchor to caret as the main selection. diff --git a/core/args.lua b/core/args.lua index 0f383544..f0b0fcf2 100644 --- a/core/args.lua +++ b/core/args.lua @@ -10,8 +10,8 @@ module('args')]] -- Markdown: -- ## Arg Events -- --- + `'arg_none'`: Called when no command line arguments are passed to Textadept --- on init. +-- + `'arg_none'` +-- Called when no command line arguments are passed to Textadept on init. local arg = arg diff --git a/core/events.lua b/core/events.lua index c939e0db..02a1dcc5 100644 --- a/core/events.lua +++ b/core/events.lua @@ -36,7 +36,7 @@ module('events')]] -- -- * `APPLEEVENT_ODOC` -- Called when Mac OSX tells Textadept to open a document. --- * `uri`: The URI to open encoded in UTF-8. +-- * `uri`: The URI to open encoded in UTF-8. -- * `AUTO_C_CHAR_DELETED` -- Called when the user deleted a character while the autocompletion list was -- active. @@ -45,10 +45,11 @@ module('events')]] -- * `AUTO_C_SELECTION` -- Called when the user has selected an item in an autocompletion list and -- before the selection is inserted. --- Automatic insertion can be cancelled by calling `buffer:auto_c_cancel()` --- before returning from the event handler. Arguments: --- * `text`: The text of the selection. --- * `position`: The start position of the word being completed. +-- Automatic insertion can be cancelled by calling +-- [`buffer:auto_c_cancel()`][] before returning from the event handler. +-- Arguments: +-- * `text`: The text of the selection. +-- * `position`: The start position of the word being completed. -- * `BUFFER_AFTER_SWITCH` -- Called right after a buffer is switched to. -- * `BUFFER_BEFORE_SWITCH` @@ -60,134 +61,134 @@ module('events')]] -- * `CALL_TIP_CLICK` -- Called when the user clicks on a calltip. -- Arguments: --- * `position`: Set to 1 if the click is in an up arrow, 2 if in a down --- arrow, and 0 if elsewhere. +-- * `position`: Set to 1 if the click is in an up arrow, 2 if in a down +-- arrow, and 0 if elsewhere. -- * `CHAR_ADDED` -- Called when an ordinary text character is added to the buffer. -- Arguments: --- * `ch`: The text character byte. +-- * `ch`: The text character byte. -- * `COMMAND_ENTRY_COMMAND` -- Called when a command is entered into the Command Entry. -- Arguments: --- * `command`: The command text. +-- * `command`: The command text. -- * `COMMAND_ENTRY_KEYPRESS` -- Called when a key is pressed in the Command Entry. -- Arguments: --- * `code`: The key code. --- * `shift`: The Shift key is held down. --- * `ctrl`: The Control/Command key is held down. --- * `alt`: The Alt/option key is held down. --- * `meta`: The Control key on Mac OSX is held down. +-- * `code`: The key code. +-- * `shift`: The Shift key is held down. +-- * `ctrl`: The Control/Command key is held down. +-- * `alt`: The Alt/option key is held down. +-- * `meta`: The Control key on Mac OSX is held down. -- * `DOUBLE_CLICK` -- Called when the mouse button is double-clicked. -- Arguments: --- * `position`: The text position of the double click. --- * `line`: The line of the double click. --- * `modifiers`: The key modifiers held down. It is a combination of zero --- or more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, --- `_SCINTILLA.constants.SCMOD_SHIFT`, and --- `_SCINTILLA.constants.SCMOD_META`. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. +-- * `position`: The text position of the double click. +-- * `line`: The line of the double click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero +-- or more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK. -- * `DWELL_END` -- Called after a `DWELL_START` and the mouse is moved or other activity such -- as key press indicates the dwell is over. -- Arguments: --- * `position`: The nearest position in the document to the position --- where the mouse pointer was lingering. --- * `x`: Where the pointer lingered. --- * `y`: Where the pointer lingered. +-- * `position`: The nearest position in the document to the position where +-- the mouse pointer was lingering. +-- * `x`: Where the pointer lingered. +-- * `y`: Where the pointer lingered. -- * `DWELL_START` -- Called when the user keeps the mouse in one position for the dwell period -- (see `_SCINTILLA.constants.SCI_SETMOUSEDWELLTIME`). -- Arguments: --- * `position`: The nearest position in the document to the position --- where the mouse pointer was lingering. --- * `x`: Where the pointer lingered. --- * `y`: Where the pointer lingered. +-- * `position`: The nearest position in the document to the position where +-- the mouse pointer was lingering. +-- * `x`: Where the pointer lingered. +-- * `y`: Where the pointer lingered. -- * `ERROR` -- Called when an error occurs. -- Arguments: --- * `text`: The error text. +-- * `text`: The error text. -- * `FIND` -- Called when finding text via the Find dialog box. -- Arguments: --- * `text`: The text to search for. --- * `next`: Search forward. +-- * `text`: The text to search for. +-- * `next`: Search forward. -- * `HOTSPOT_CLICK` -- Called when the user clicks on text that is in a style with the hotspot -- attribute set. -- Arguments: --- * `position`: The text position of the click. --- * `modifiers`: The key modifiers held down. It is a combination of zero --- or more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, --- `_SCINTILLA.constants.SCMOD_SHIFT`, and --- `_SCINTILLA.constants.SCMOD_META`. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. +-- * `position`: The text position of the click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero +-- or more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK. -- * `HOTSPOT_DOUBLE_CLICK` -- Called when the user double clicks on text that is in a style with the -- hotspot attribute set. -- Arguments: --- * `position`: The text position of the double click. --- * `modifiers`: The key modifiers held down. It is a combination of zero --- or more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, --- `_SCINTILLA.constants.SCMOD_SHIFT`, and --- `_SCINTILLA.constants.SCMOD_META`. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. +-- * `position`: The text position of the double click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero +-- or more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK. -- * `HOTSPOT_RELEASE_CLICK` -- Called when the user releases the mouse on text that is in a style with the -- hotspot attribute set. -- Arguments: --- * `position`: The text position of the release. +-- * `position`: The text position of the release. -- * `INDICATOR_CLICK` -- Called when the user clicks the mouse on text that has an indicator. -- Arguments: --- * `position`: The text position of the click. --- * `modifiers`: The key modifiers held down. It is a combination of zero --- or more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, --- `_SCINTILLA.constants.SCMOD_SHIFT`, and --- `_SCINTILLA.constants.SCMOD_META`. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. +-- * `position`: The text position of the click. +-- * `modifiers`: The key modifiers held down. It is a combination of zero +-- or more of `_SCINTILLA.constants.SCMOD_ALT`, +-- `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK. -- * `INDICATOR_RELEASE` -- Called when the user releases the mouse on text that has an indicator. -- Arguments: --- * `position`: The text position of the release. +-- * `position`: The text position of the release. -- * `KEYPRESS` -- Called when a key is pressed. -- Arguments: --- * `code`: The key code. --- * `shift`: The Shift key is held down. --- * `ctrl`: The Control/Command key is held down. --- * `alt`: The Alt/option key is held down. --- * `meta`: The Control key on Mac OSX is held down. +-- * `code`: The key code. +-- * `shift`: The Shift key is held down. +-- * `ctrl`: The Control/Command key is held down. +-- * `alt`: The Alt/option key is held down. +-- * `meta`: The Control key on Mac OSX is held down. -- * `MARGIN_CLICK` -- Called when the mouse is clicked inside a margin. -- Arguments: --- * `margin`: The margin number that was clicked. --- * `position`: The position of the start of the line in the buffer that --- corresponds to the margin click. --- * `modifiers`: The appropriate combination of --- `_SCINTILLA.constants.SCI_SHIFT`, `_SCINTILLA.constants.SCI_CTRL`, --- and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were --- held down at the time of the margin click. --- Note: If you set `buffer.rectangular_selection_modifier` to --- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* --- Ctrl and Alt due to a Scintilla limitation with GTK. +-- * `margin`: The margin number that was clicked. +-- * `position`: The position of the start of the line in the buffer that +-- corresponds to the margin click. +-- * `modifiers`: The appropriate combination of +-- `_SCINTILLA.constants.SCI_SHIFT`, `_SCINTILLA.constants.SCI_CTRL`, +-- and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were +-- held down at the time of the margin click. +-- Note: If you set `buffer.rectangular_selection_modifier` to +-- `_SCINTILLA.constants.SCMOD_CTRL`, the Ctrl key is reported as *both* +-- Ctrl and Alt due to a Scintilla limitation with GTK. -- * `MENU_CLICKED` -- Called when a menu item is selected. -- Arguments: --- * `menu_id`: The numeric ID of the menu item set in `gui.gtkmenu()`. +-- * `menu_id`: The numeric ID of the menu item set in [`gui.gtkmenu()`][]. -- * `QUIT` -- Called when quitting Textadept. -- When connecting to this event, connect with an index of 1 or the handler @@ -195,18 +196,18 @@ module('events')]] -- * `REPLACE` -- Called to replace selected (found) text. -- Arguments: --- * `text`: The text to replace selected text with. +-- * `text`: The text to replace selected text with. -- * `REPLACE_ALL` -- Called to replace all occurances of found text. -- Arguments: --- * `find_text`: The text to search for. --- * `repl_text`: The text to replace found text with. +-- * `find_text`: The text to search for. +-- * `repl_text`: The text to replace found text with. -- * `RESET_AFTER` -- Called after resetting the Lua state. --- This is triggered by `reset()`. +-- This is triggered by [`reset()`][]. -- * `RESET_BEFORE` -- Called before resetting the Lua state. --- This is triggered by `reset()`. +-- This is triggered by [`reset()`][]. -- * `SAVE_POINT_LEFT` -- Called when a save point is left. -- * `SAVE_POINT_REACHED` @@ -217,14 +218,14 @@ module('events')]] -- * `URI_DROPPED` -- Called when the user has dragged a URI such as a file name onto the view. -- Arguments: --- * `text`: The URI text encoded in UTF-8. +-- * `text`: The URI text encoded in UTF-8. -- * `USER_LIST_SELECTION` -- Called when the user has selected an item in a user list. -- Arguments: --- * `list_type`: This is set to the list_type parameter from the --- `buffer:user_list_show()` call that initiated the list. --- * `text`: The text of the selection. --- * `position`: The position the list was displayed at. +-- * `list_type`: This is set to the list_type parameter from the +-- [`buffer:user_list_show()`][] call that initiated the list. +-- * `text`: The text of the selection. +-- * `position`: The position the list was displayed at. -- * `VIEW_NEW` -- Called when a new view is created. -- * `VIEW_BEFORE_SWITCH` @@ -232,6 +233,11 @@ module('events')]] -- * `VIEW_AFTER_SWITCH` -- Called right after another view is switched to. -- +-- [`buffer:auto_c_cancel()`]: buffer.html#buffer.auto_c_cancel +-- [`gui.gtkmenu()`]: gui.html#gtkmenu +-- [`reset()`]: _G.html#reset +-- [`buffer:user_list_show()`]: buffer.html#buffer.user_list_show +-- -- ## Example -- -- The following Lua code generates and handles a custom `my_event` event: diff --git a/core/file_io.lua b/core/file_io.lua index 8ff6d5be..1d31f1e6 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -6,13 +6,14 @@ module('io')]] -- Markdown: --- ## Converting Filenames to and from UTF-8 +-- ## Working with UTF-8 -- -- If your filesystem does not use UTF-8 encoded filenames, conversions to and --- from that encoding will be necessary. When opening and saving files through --- dialogs, Textadept takes care of these conversions for you, but if you need --- to do them manually, use [`string.iconv()`][string_iconv] along with --- `_CHARSET`, your filesystem's detected encoding. +-- from that encoding are necessary since all of Textadept's internal strings +-- are UTF-8 encoded. When opening and saving files through dialogs, these +-- conversions are performed autmatically, but if you need to do them manually, +-- use [`string.iconv()`][] along with `_CHARSET`, your filesystem's detected +-- encoding. -- -- Example: -- @@ -23,26 +24,26 @@ module('io')]] -- f:close() -- end) -- --- [string_iconv]: ../modules/string.html#iconv +-- [`string.iconv()`]: string.html#iconv -- -- ## File Events -- -- * `_G.events.FILE_OPENED` -- Called when a file is opened in a new buffer. -- Arguments: --- * `filename`: The filename encoded in UTF-8. +-- * `filename`: The filename encoded in UTF-8. -- * `_G.events.FILE_BEFORE_SAVE` -- Called right before a file is saved to disk. -- Arguments: --- * `filename`: The filename encoded in UTF-8. +-- * `filename`: The filename encoded in UTF-8. -- * `_G.events.FILE_AFTER_SAVE` -- Called right after a file is saved to disk. -- Arguments: --- * `filename`: The filename encoded in UTF-8. +-- * `filename`: The filename encoded in UTF-8. -- * `_G.events.FILE_SAVED_AS` -- Called when a file is saved under a different filename. -- Arguments: --- * `filename`: The filename encoded in UTF-8. +-- * `filename`: The filename encoded in UTF-8. -- Events. local events, events_connect = events, events.connect diff --git a/core/init.lua b/core/init.lua index 056a212b..8f7fd360 100644 --- a/core/init.lua +++ b/core/init.lua @@ -30,23 +30,24 @@ module('_G')]] -- * `_HOME` [string] -- Path to the directory containing Textadept. -- * `_LEXERPATH` [string] --- Paths to lexers, formatted like [`package.path`][package_path]. +-- Paths to lexers, formatted like [`package.path`][]. -- * `_RELEASE` [string] -- The Textadept release version. -- * `_USERHOME` [string] -- Path to the user's `~/.textadept/`. -- * `_CHARSET` [string] -- The character set encoding of the filesystem. --- This is used in [File I/O](../modules/io.html). +-- This is used in [File I/O][]. -- * `RESETTING` [bool] --- If [`reset()`](../modules/_G.html#reset) has been called, this flag is --- `true` while the Lua state is being re-initialized. +-- If [`reset()`](#reset) has been called, this flag is `true` while the Lua +-- state is being re-initialized. -- * `WIN32` [bool] -- If Textadept is running on Windows, this flag is `true`. -- * `OSX` [bool] -- If Textadept is running on Mac OSX, this flag is `true`. -- --- [package_path]: http://www.lua.org/manual/5.1/manual.html#pdf-package.path +-- [`package.path`]: http://www.lua.org/manual/5.2/manual.html#pdf-package.path +-- [File I/O]: io.html --- -- Calls `dofile()` on the given filename in the user's Textadept directory. diff --git a/core/keys.lua b/core/keys.lua index 90d677ab..6418b612 100644 --- a/core/keys.lua +++ b/core/keys.lua @@ -34,17 +34,20 @@ module('keys')]] -- ADD = '+' -- -- pressing control, alt, shift, and 'a' yields: 'Ctrl+Alt+Shift+A' -- --- For key values less than 255, Lua's [`string.char()`][string_char] is used to --- determine the key's string representation. Otherwise, the --- [`KEYSYMS`](../modules/_M.textadept.keys.html#KEYSYMS) lookup table is used. +-- For key values less than 255, Lua's [`string.char()`][] is used to determine +-- the key's string representation. Otherwise, the [`KEYSYMS`](#KEYSYMS) lookup +-- table is used. -- --- [string_char]: http://www.lua.org/manual/5.1/manual.html#pdf-string.char +-- [`string.char()`]: http://www.lua.org/manual/5.2/manual.html#pdf-string.char -- -- Normally, Lua functions are assigned to key commands, but those functions are -- called without any arguments. In order to pass arguments to a function, -- assign a table to the key command. This table contains the function followed --- by its arguments in order. Any [buffer](../modules/buffer.html) or --- [view](../modules/view.html) references are handled correctly at runtime. +-- by its arguments in order. Any [buffer][] or [view][] references are handled +-- correctly at runtime. +-- +-- [buffer]: buffer.html +-- [view]: view.html -- -- Key commands can be chained like in Emacs using keychain sequences. By -- default, the `Esc` key (`Apple+Esc` on Mac OSX) cancels the current keychain, @@ -77,12 +80,12 @@ module('keys')]] -- modules. -- The default value is Ctrl/Cmd+L. -- --- ## Key Command Precedence +-- ## Precedence -- -- When searching for a key command to execute in the `keys` table, key commands -- in the current lexer have priority, followed by the ones in the global table. -- --- #### Propagation +-- ### Propagation -- -- Normally when the same key command is assigned to two separate functions of -- different precedence, the higher priority key command is run and the lower diff --git a/core/locale.lua b/core/locale.lua index 5448cdc4..a89685ed 100644 --- a/core/locale.lua +++ b/core/locale.lua @@ -8,7 +8,7 @@ local M = {} module('_L')]] -- Markdown: --- # Settings +-- ## Settings -- -- * `_NIL` [string] -- String returned when no localization for a given message exists. @@ -26,10 +26,4 @@ for line in f:lines() do end f:close() ---- --- This table contains no functions. --- @class function --- @name no_functions -local no_functions - return setmetatable(M, { __index = function() return M._NIL end }) diff --git a/doc/manual/10_Advanced.md b/doc/manual/10_Advanced.md index db5cc5a3..d81687aa 100644 --- a/doc/manual/10_Advanced.md +++ b/doc/manual/10_Advanced.md @@ -6,16 +6,18 @@ Access to the Lua state is available through the command entry. Press `Ctrl+E` (`⌘E` on Mac OSX) to access it. It is useful for debugging, inspecting, and entering buffer or view commands. If you try to cause instability in Textadept's Lua state, you might very well succeed so be careful. For more information, see -the [scripting](11_Scripting.html) page. +the [scripting][] page. Abbreviated commands for the `buffer`, `view` and `gui` are available. So `buffer:append_text('foo')` can be shortened to `append_text('foo')`. `print()` -redirects to [`gui.print()`](../modules/gui.html#print). Use `_G.print()` for -Lua's `print()`. +redirects to [`gui.print()`][]. Use `_G.print()` for Lua's `print()`.  -#### Tab Completion +[scripting]: 11_Scripting.html +[`gui.print()`]: ../api/gui.html#print + +### Tab Completion Tab-completion for functions, variables, tables, etc. is available. Press the `Tab` (`⇥`) key to display a list of available completions. Use the arrow keys @@ -23,21 +25,24 @@ to make a selection and press `Enter` (`↩`) to insert it.  -#### Extending +### Extending You can extend the command entry to do more than enter Lua commands. An -example of this is [incremental -search](../modules/gui.find.html#find_incremental). See -`modules/textadept/find.lua` for the implementation. +example of this is [incremental search][]. See `modules/textadept/find.lua` for +the implementation. + +[incremental search]: ../api/gui.find.html#find_incremental ## Command Selection -If you did not disable the menu in your [preferences](9_Preferences.html), then -pressing `Ctrl+Shift+E` (`⌘⇧E` on Mac OSX) 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 commands. It is also useful for looking up particular -key commands quickly. +If you did not disable the menu in your [preferences][], then pressing +`Ctrl+Shift+E` (`⌘⇧E` on Mac OSX) 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 commands. It is also useful for looking up particular key +commands quickly. + +[preferences]: 9_Preferences.html#User.Init ## Shell Commands and Filtering Text @@ -69,10 +74,11 @@ not notice any difference for working with files containing ASCII text since UTF-8 is compatible with it. Textadept can also detect ISO-8859-1 and MacRoman, the primary encodings used on Windows and Mac OSX respectively. Files with more exotic encodings may not be detected properly, if at all. You can change the -list of encodings Textadept tries to detect via -[`io.try_encodings`](../modules/io.html#try_encodings). +list of encodings Textadept tries to detect via [`io.try_encodings`][]. It is recommended to use UTF-8 encoded files because UTF-8 is very well supported by other text editors and operating systems. You can change the file's encoding via the `Buffer -> Encoding` menu. Textadept saves new files as UTF-8 by default. + +[`io.try_encodings`]: ../api/io.html#try_encodings diff --git a/doc/manual/11_Scripting.md b/doc/manual/11_Scripting.md index 6fbf2cba..463d01bc 100644 --- a/doc/manual/11_Scripting.md +++ b/doc/manual/11_Scripting.md @@ -2,23 +2,26 @@ Textadept has superb support for editing Lua code. Syntax autocomplete and LuaDoc is available for many Textadept objects as well as Lua's standard -libraries. See the [lua module documentation](../modules/_M.lua.commands.html) -for more information. +libraries. See the [`lua` module documentation][] for more information.   +[`lua` module documentation]: ../api/_M.lua.html + ## LuaDoc and Examples -Textadept's API is heavily documented. The [LuaDoc](../index.html) is the -ultimate resource on scripting Textadept. There are of course abundant scripting -examples since Textadept is mostly written in Lua. +Textadept's API is heavily documented. The [LuaDoc][] is the ultimate resource +on scripting Textadept. There are of course abundant scripting examples since +Textadept is mostly written in Lua. + +[LuaDoc]: ../api/index.html ## Lua Configuration -[Lua 5.2](http://www.lua.org/manual/5.2/) is built into Textadept. It has the -same configuration (`luaconf.h`) as vanilla Lua with the following exceptions: +[Lua 5.2][] is built into Textadept. It has the same configuration (`luaconf.h`) +as vanilla Lua with the following exceptions: * `TA_LUA_PATH` and `TA_LUA_CPATH` are the environment variable used in place of the usual `LUA_PATH` and `LUA_CPATH`. @@ -27,47 +30,52 @@ same configuration (`luaconf.h`) as vanilla Lua with the following exceptions: `LUA_COMPAT_LOADERS`, `LUA_COMPAT_LOG10`, `LUA_COMPAT_LOADSTRING`, `LUA_COMPAT_MAXN`, and `LUA_COMPAT_MODULE`.) +[Lua 5.2]: http://www.lua.org/manual/5.2/ + ## Scintilla -The editing component used by Textadept is [Scintilla](http://scintilla.org). -The [buffer](../modules/buffer.html) part of Textadept's API is derived from the -[Scintilla API](http://scintilla.org/ScintillaDoc.html) so any C/C++ code using +The editing component used by Textadept is [Scintilla][]. The [buffer][] part of +Textadept's API is derived from the [Scintilla API][] so any C/C++ code using Scintilla calls can be ported to Lua without too much trouble. -## Textadept Folder Structure +[Scintilla]: http://scintilla.org +[buffer]: ../api/buffer.html +[Scintilla API]: http://scintilla.org/ScintillaDoc.html + +## Textadept Structure Because Textadept is mostly written in Lua, its Lua scripts have to be stored in an organized folder structure. -#### Core +### Core Textadept's core Lua modules are contained in `core/`. These are absolutely necessary in order for the application to run. They are responsible for Textadept's Lua to C interface, event structure, file input/output, and localization. -#### Lexers +### Lexers Lexer Lua modules are responsible for the syntax highlighting of source code. They are located in `lexers/`. -#### Modules +### Modules Editor Lua modules are contained in `modules/`. These provide advanced text editing capabilities and can be available for all programming languages or targeted at specific ones. -#### Themes +### Themes Built-in themes to customize the look and behavior of Textadept are located in `themes/`. -#### User +### User User Lua modules are contained in the `~/.textadept/` folder. This folder may contain `lexers/`, `modules/`, and `themes/` subdirectories. -#### GTK +### GTK The `etc/`, `lib/`, and `share/` directories are used by GTK and only appear in the Win32 and Mac OSX packages. diff --git a/doc/manual/12_Compiling.md b/doc/manual/12_Compiling.md index f52c3b0f..aa7b2303 100644 --- a/doc/manual/12_Compiling.md +++ b/doc/manual/12_Compiling.md @@ -5,43 +5,49 @@ Unfortunately, the requirements for building Textadept are not quite as minimal as running it. -#### Linux and BSD +### Linux and BSD Linux systems need the GTK+ development libraries. Your package manager should allow you to install them. For Debian-based distributions like Ubuntu, the package is typically called `libgtk2.0-dev`. Otherwise, compile and install GTK -from the [GTK+ website](http://www.gtk.org/download/linux.html). Additionally -you will need the [GNU C compiler](http://gcc.gnu.org) (`gcc`) and -[GNU Make](http://www.gnu.org/software/make/) (`make`). Both should be available -for your Linux distribution through its package manager. For example, Ubuntu -includes these tools in the `build-essential` package. +from the [GTK+ website][]. Additionally you will need the [GNU C compiler][] +(`gcc`) and [GNU Make][] (`make`). Both should be available for your Linux +distribution through its package manager. For example, Ubuntu includes these +tools in the `build-essential` package. -#### Windows +[GTK+ website]: http://www.gtk.org/download/linux.html +[GNU C compiler]: http://gcc.gnu.org +[GNU Make]: http://www.gnu.org/software/make/ + +### Windows Compiling Textadept on Windows is no longer supported. If you wish to do so however, you need a C compiler that supports the C99 standard (Microsoft's does -not) and the [GTK+ for Windows bundle](http://www.gtk.org/download/win32.html) -(2.22 is recommended). +not) and the [GTK+ for Windows bundle][] (2.22 is recommended). The preferred way to compile for Windows is cross-compiling from Linux. To do -so, in addition to the GTK bundle mentioned above, you need -[MinGW](http://mingw.org) with the Windows header files. They should be -available from your package manager. +so, in addition to the GTK bundle mentioned above, you need [MinGW][] with the +Windows header files. They should be available from your package manager. + +[GTK+ for Windows bundle]: http://www.gtk.org/download/win32.html +[MinGW]: http://mingw.org -#### Mac OSX +### Mac OSX -[XCode](http://developer.apple.com/TOOLS/xcode/) is needed for Mac OSX as well -as [jhbuild](http://sourceforge.net/apps/trac/gtk-osx/wiki/Build). After -building `meta-gtk-osx-bootstrap` and `meta-gtk-osx-core`, you need to build +[XCode][] is needed for Mac OSX as well as [jhbuild][]. After building +`meta-gtk-osx-bootstrap` and `meta-gtk-osx-core`, you need to 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. +[XCode]: http://developer.apple.com/TOOLS/xcode/ +[jhbuild]: http://sourceforge.net/apps/trac/gtk-osx/wiki/Build + ## Compiling Make sure you downloaded the `textadept_x.x.src.zip` (regardless of what platform you are on) and not a platform-specific binary package. -#### Linux and BSD +### Linux and BSD For Linux systems, simply run `make` in the `src/` directory. The `textadept` executable is created in the root directory. Make a symlink from it to @@ -49,14 +55,14 @@ executable is created in the root directory. Make a symlink from it to BSD users please run `make BSD=1`. -#### Cross Compiling for Windows from Linux +### Cross Compiling for Windows When cross-compiling from within Linux, first unzip the GTK+ for Windows bundle into a new `src/win32gtk` directory. Then modify the `CC`, `CPP`, and `WINDRES` variables in the `WIN32` block of `src/Makefile` to match your MinGW installation and run `make WIN32=1` to build `../textadept.exe`. -#### Mac OSX +### Mac OSX After using `jhbuild`, GTK is in `~/gtk` so make a symlink from `~/gtk/inst` to `src/gtkosx` in Textadept. Then run `make OSX=1` to build `../textadept.osx`. At @@ -67,7 +73,7 @@ all `.dylib` files in `Contents/Resources/lib`, and all `.so` files in own versions in `src/gtkosx/lib`. If you wish, you may also replace the files in `Contents/Resources/{etc,share}`, but these rarely change. -##### Problems +#### Problems If the build fails because of a @@ -80,16 +86,16 @@ lines (put `//` at the start of the line): #define TextRange Sci_TextRange #define TextToFind Sci_TextToFind -#### Compiling with LuaJIT +### Compiling with LuaJIT -[LuaJIT](http://luajit.org) 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](http://luajit.org/ext_ffi.html), however, appears to be -useful for interfacing with external, non-Lua, libraries. +[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. You can compile Textadept with LuaJIT by running `make LUAJIT=1` for Linux systems, `make OSX=1 LUAJIT=1` for Mac OSX, and `make WIN32=1 LUAJIT=1` for @@ -98,3 +104,6 @@ Windows systems. Please note that a `lua51.dll` is produced for Windows platforms because limitations on external Lua library loading do not allow statically linking LuaJIT to Textadept. Static linking occurs on all other platforms. + +[LuaJIT]: http://luajit.org +[ffi library]: http://luajit.org/ext_ffi.html diff --git a/doc/manual/13_Help.md b/doc/manual/13_Help.md index 8116b125..800a18cb 100644 --- a/doc/manual/13_Help.md +++ b/doc/manual/13_Help.md @@ -7,9 +7,9 @@ parameters. ## Online Help -Textadept has a [mailing list](http://groups.google.com/group/textadept) and a -[wiki](http://caladbolg.net/textadeptwiki). You can also join us on IRC via -[freenode.net](http://freenode.net) in `#textadept`. +Textadept has a [mailing list][] and a [wiki][]. You can also join us on IRC via +[freenode.net][] in `#textadept`. -<br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/> -<br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/> +[mailing list]: http://foicica.com/lists +[wiki]: http://caladbolg.net/textadeptwiki +[freenode.net]: http://freenode.net diff --git a/doc/manual/14_Appendix.md b/doc/manual/14_Appendix.md index cdff8db7..426ab35f 100644 --- a/doc/manual/14_Appendix.md +++ b/doc/manual/14_Appendix.md @@ -16,7 +16,6 @@ Ctrl+Shift+W|⌘⇧W |Close all files None |None|Load session... None |None|Load session... Alt+Q |⌘Q |Quit - **Edit** ||| Ctrl+Z<br/>Alt+Backspace|⌘Z |Undo Ctrl+Y<br/>Ctrl+Shift+Z |⌘⇧Z |Redo @@ -58,7 +57,6 @@ Ctrl++ |⌘+ |Grow selection by 1 on either side Ctrl+\_ |⌘\_ |Shrink selection by 1 on either side Ctrl+Shift+Up |^⇧⇡ |Move selected lines up Ctrl+Shift+Down |^⇧⇣ |Move selected lines down - **Search** ||| Ctrl+F |⌘F |Find Ctrl+G<br/>F3 |⌘G |Find next @@ -70,7 +68,6 @@ Ctrl+Shift+F |⌘⇧F |Find in files Ctrl+Alt+G |^⌘G |Goto next file found Ctrl+Alt+Shift+G |^⌘⇧G|Goto previous file found Ctrl+J |⌘J |Jump to line - **Tools** ||| Ctrl+E |⌘E |Command entry Ctrl+Shift+E |⌘⇧E |Select command @@ -92,7 +89,6 @@ Ctrl+U |⌘U |Snapopen `_USERHOME` None |None |Snapopen `_HOME` Ctrl+Alt+Shift+O|^⌘⇧O |Snapopen current directory Ctrl+I |⌘I |Show style - **Buffer** ||| Ctrl+Tab |^⇥ |Next buffer Ctrl+Shift+Tab |^⇧⇥ |Previous buffer @@ -112,7 +108,6 @@ None |None |`ISO-8859-1` encoding None |None |`UTF-16` encoding Ctrl+Shift+L |⌘⇧L |Select lexer... F5 |F5 |Refresh syntax highlighting - **View** ||| Ctrl+Alt+N |^⌥⇥ |Next view Ctrl+Alt+P |^⌥⇧⇥ |Previous view @@ -132,12 +127,10 @@ Ctrl+= |⌘= |Zoom in Ctrl+- |⌘- |Zoom out Ctrl+0 |⌘0 |Reset zoom Ctrl+Shift+T |⌘⇧T |Select theme... - **Help** ||| F1 |F1 |Open manual Shift+F1|⇧F1 |Open LuaDoc None |None|About - **Movement** ||| Down |⇣<br/>^N |Line down Shift+Down |⇧⇣<br/>^⇧N |Line down extend selection @@ -183,15 +176,12 @@ Tab |⇥ |Insert tab or indent Shift+Tab |⇧⇥ |Dedent None |^K |Cut to line end None |^L |Center line vertically - **Other** ||| Ctrl+Shift+U, xxxx, Enter|None|Input Unicode character U-xxxx. - ## Lua Patterns -The following is taken from the -[Lua 5.2 Reference Manual](http://www.lua.org/manual/5.2/manual.html#6.4.1). +The following is taken from the [Lua 5.2 Reference Manual][]. _Character Class:_ @@ -285,3 +275,412 @@ is captured with number 2, and the part matching "`%s*`" has number 3. As a special case, the empty capture `()` captures the current string position (a number). For instance, if we apply the pattern `"()aa()"` on the string `"flaaap"`, there will be two captures: 3 and 5. + +[Lua 5.2 Reference Manual]: http://www.lua.org/manual/5.2/manual.html#6.4.1 + +## Migration Guides + +### Textadept 4 to 5 + +Lua has been upgraded from [5.1 to 5.2][], so many scripts written for Textadept +4 are not compatible with Textadept 5. Since incompatible scripts may cause +crashes on startup, the following guide will help you migrate your scripts from +Textadept 4 to Textadept 5. While this guide is not exhaustive, it covers the +changes I had to Textadept's internals. + +[5.1 to 5.2]: http://www.lua.org/manual/5.2/manual.html#8 + +#### Module Changes + +##### Syntax Changes + +Although Lua 5.2 only deprecates Lua 5.1's `module` syntax, Textadept 5 removes +it. Therefore, replace + + -- File ~/.textadept/modules/foo.lua + module('_m.foo', package.seeall) + + function bar() + ... + end + + ... + +and + + -- File ~/.textadept/init.lua + require 'textadept' + require 'foo' + +with + + -- File ~/.textadept/modules/foo.lua + local M = {} + + function M.bar() + ... + end + + ... + + return M + +or + + local M = {} + local _ENV = M + if setfenv then setfenv(1, _ENV) end -- LuaJIT support + + function bar() + ... + end + + function baz() + bar() + end + + return M + +and + + -- File ~/.textadept/init.lua + require 'textadept' + _M.foo = require 'foo' + +Please remember that, as stated in the documentation, `require 'textadept'` is a +special case and `_M.textadept = require 'textadept'` is not necessary because +of internal dependencies. All other modules need the +`_M.module = require 'module'` construct. + +Notice that `_M` is the new module table instead of `_m`. More on this +[later](#Global.Module.Table). + +##### Module References + +Replace all instances of `_M` (a reference created by `module()` that holds the +current module table) with `M` (the local module table you created). + +Also, prefix all instances of internal module function calls with `M` if you are +not using `_ENV`. For example, change + + module('foo', package.seeall) + + function bar() + ... + end + + function baz() + bar() + end + +to + + local M = {} + + function M.bar() + ... + end + + function M.baz() + M.bar() + end + + return M + +##### LuaDoc + +If you use LuaDoc for your modules, you can still document them like this: + + local M = {} + + --[[ This comment is for LuaDoc + --- + -- This is the documentation for module foo. + module('foo')]] + + --- + -- Documentation for bar. + -- ... + -- @name bar + function M.bar() + ... + end + + return M + +##### Global Module Table + +Originally, I wanted to use `_M` as the global table that contains modules, but +Lua 5.1's modules used `_M` silently, so I had to settle with `_m`. Now that +modules have been removed, `_M` is available again and is used. Therefore, +replace all instances of `_m` with `_M`. In Textadept, you can easily do a +search and replace with "Match Case" and "Whole Words" checked -- this is what I +did when upgrading Textadept's internals. + +#### Function Changes + +##### `unpack` + +`unpack()` has been renamed to `table.unpack()`. Replace all instances of +`unpack` with `table.unpack`. + +##### `xpcall` + +`xpcall()` accepts error function parameters so you can change code from + + local args = {...} + xpcall(function() return f(unpack(args)) end, error_function) + +to + + xpcall(f, error_function, ...) + +However, this is not required. + +##### `loadstring` + +`loadstring()` has been replaced by `load()` since the latter now recognizes a +string chunk. Replace all instances of `loadstring` with `load`. + +##### `setfenv` + +`setfenv()` has been removed. In some cases, use `load()` with an environment +instead. For example, change + + local f, err = loadstring(command) + if err then error(err) end + setfenv(f, env)() + +to + + local f, err = load(command, nil, 'bt', env) + if err then error(err) end + f() + +(The `'bt'` is necessary for loading both binary and text chunks.) + +If instead you want to set a function's environment, change + + setfenv(f, env) + +to + + debug.setupvalue(f, 1, env) + +##### `getfenv` + +`getfenv()` has been removed. Change + + local env = getfenv(f) + +to + + local debug = require 'debug' + local env = debug.getupvalue(f, 1) + +##### `os.execute` + +`os.execute()`s function parameters have changed. If you are only interested in +the return code, change + + local code = os.execute(cmd) + +to + + local _, _, code = os.execute(cmd) + +##### `localize` + +Localization is done using a global table [`_L`][] instead of calling +`locale.localize()`. Replace all instances of `locale.localize('message')` with +`_L['message']`. This allows messages to be modified via scripts if desirable. + +[`_L`]: ../api/_L.html + +##### `current_word` + +`_M.textadept.editing.current_word()` has been renamed to `select_word()` and +does not take any parameters. There is a `_M.textadept.keys.utils.delete_word()` +function that replaces `current_word('delete')`. You can use it or create a new +function: + + local function delete_word() + _M.textadept.editing.select_word() + buffer:delete_back() + end + +#### Theme Changes + +Any custom themes need to be changed to remove the `module` syntax. Usually this +involves changing + + module('lexer', package.seeall) + + colors = { + ... + } + + style_nothing = style { ... } + style_class = style { fore = colors.light_yellow } + ... + style_identifier = style_nothing + + ... + + style_default = style { + ... + } + style_line_number = { fore = colors.dark_grey, back = colors.black } + ... + +to + + local l, color, style = lexer, lexer.color, lexer.style + + l.colors = { + ... + } + + l.style_nothing = style { ... } + l.style_class = style { fore = l.colors.light_yellow } + ... + l.style_identifier = l.style_nothing + + ... + + l.style_default = style { + ... + } + l.style_line_number = { fore = l.colors.dark_grey, back = l.colors.black } + ... + +Notice the `l.` prefix before most identifiers. + +### Textadept 3 to 4 + +#### Key and Menu Changes + +Textadept 4 allow key shortcuts to appear in menus, but only simple ones, not +keychains. Therefore, Textadept's key commands have changed radically, as has +the menu structure and menu mnemonics. In order for key shortcuts to appear in +menus, `_m.textadept.menu` needs to know which commands are assigned to which +keys. Therefore, the menu module needs to be `require`d *after* +`_m.textadept.keys`. If your `~/.textadept/init.lua` is calling +`require 'textadept'`, you do not have to make any changes. If you are loading +individual modules from `_m.textadept`, ensure `_m.textadept.menu` is loaded +after `_m.textadept.keys`. + +On Mac OSX, key command definition has changed. `m` is now ⌘ (command) and `a` +is now ⌥ (alt/option). `c` remains ^ (control). Previously `a` was ⌘ and ⌥ was +undefined. Please note, however, that not all ⌥ combinations by themselves will +work since that key is typically used to compose locale-dependent characters. + +#### Function Changes + +##### `select_scope` + +`_m.textadept.editing.select_scope()` was renamed to `select_style()`. +Therefore, replace all instances of `_m.textadept.editing.select_scope` with +`_m.textadept.editing.select_style`. + +##### `SAVE_STRIPS_WS` + +`_m.textadept.editing.SAVE_STRIPS_WS` was renamed to `STRIP_WHITESPACE_ON_SAVE`. +Replace all instances of `_m.textadept.editing.SAVE_STRIPS_WS` with +`_m.textadept.editing.STRIP_WHITESPACE_ON_SAVE`. + +### Textadept 2 to 3 + +#### Module Changes + +##### Core Extensions + +There are no more core extention modules (previously in `core/ext/`). They have +been relocated to `modules/textadept/` so putting + + require 'textadept' + +in your `~/.textadept/init.lua` will load all the modules you would expect. +Please see the [preferences][] page for instructions on how to load specific +modules. + +[preferences]: 9_Preferences.html#User.Init + +##### Autoloading + +Key commands in `~/.textadept/key_commands.lua` and snippets in +`~/.textadept/snippets.lua` are no longer auto-loaded. Instead, modify +[`keys`][] and/or [`snippets`][] from within your `~/.textadept/init.lua` or a +file loaded by `~/.textadept/init.lua`. + +[`keys`]: ../api/keys.html +[`snippets`]: ../api/_M.textadept.snippets.html + +#### Function Changes + +Textadept has a brand new Lua [API][]. It is likely that any external scripts, +including themes, need to be rewritten. + +Here is a summary of API changes: + +* `_m.textadept.lsnippets` renamed to [`_m.textadept.snippets`][]. +* `textadept.events` renamed to [`_G.events`][]. + * `events.handle()` renamed to [`events.emit()`][]. + * `events.add_handler()` renamed to [`events.connect()`][]. +* `textadept.constants` renamed to [`_SCINTILLA.constants`][]. +* `textadept.buffer_functions` renamed to [`_SCINTILLA.functions`][]. +* `textadept.buffer_properties` renamed to [`_SCINTILLA.properties`][]. +* `textadept.buffers` renamed to [`_BUFFERS`][]. +* `textadept.views` renamed to [`_VIEWS`][]. +* New [`gui`][] module. + * Renamed `textadept._print()` to [`gui._print()`][]. + * Renamed `textadept.check_focused_buffer()` to `gui.check_focused_buffer()`. + * Renamed `textadept.clipboard_text` to `gui.clipboard_text`. + * Renamed `textadept.context_menu` to `gui.context_menu`. + * Renamed `textadept.command_entry` to [`gui.command_entry`][]. + * Renamed `textadept.dialog` to [`gui.dialog()`][]. + * Renamed `textadept.docstatusbar_text` to `gui.docstatusbar_text`. + * Renamed `textadept.find` to [`gui.find`][]. + * Renamed `textadept.focused_doc_pointer` to `gui.focused_doc_pointer`. + * Renamed `textadept.get_split_table()` to [`gui.get_split_table()`][]. + * Renamed `textadept.gtkmenu()` to [`gui.gtkmenu()`][]. + * Renamed `textadept.goto_view()` to [`gui.goto_view()`][]. + * Renamed `textadept.menubar` to `gui.menubar`. + * Renamed `textadept.print()` to [`gui.print()`][]. + * Renamed `textadept.size` to `gui.size`. + * Renamed `textadept.statusbar_text` to `gui.statusbar_text`. + * Renamed `textadept.switch_buffer()` to [`gui.switch_buffer()`][]. + * Renamed `textadept.title` to `gui.title`. + * Renamed `textadept.new_buffer()` to [`new_buffer()`][]. + * Renamed `textadept.quit()` to [`quit()`][]. + * Renamed `textadept.reset()` to [`reset()`][]. + * Renamed `textadept.user_dofile()` to [`user_dofile()`][]. + * Renamed `textadept.iconv()` to [`string.iconv()`][]. + * Renamed `textadept.session_file` to `_SESSIONFILE`. +* Removed global `textadept` module. + +[API]: ../api +[`_m.textadept.snippets`]: ../api/_M.textadept.snippets.html +[`_G.events`]: ../api/events.html +[`events.emit()`]: ../api/events.html#emit +[`events.connect()`]: ../api/events.html#connect +[`_SCINTILLA.constants`]: ../api/_SCINTILLA.html#constants +[`_SCINTILLA.functions`]: ../api/_SCINTILLA.html#functions +[`_SCINTILLA.properties`]: ../api/_SCINTILLA.html#properties +[`_BUFFERS`]: ../api/_G.html#_BUFFERS +[`_VIEWS`]: ../api/_G.html#_VIEWS +[`gui`]: ../api/gui.html +[`gui._print()`]: ../api/gui.html#_print +[`gui.command_entry`]: ../api/gui.command_entry.html +[`gui.dialog()`]: ../api/gui.html#dialog +[`gui.find`]: ../api/gui.find.html +[`gui.get_split_table()`]: ../api/gui.html#get_split_table +[`gui.gtkmenu()`]: ../api/gui.html#gtkmenu +[`gui.goto_view()`]: ../api/gui.html#goto_view +[`gui.print()`]: ../api/gui.html#print +[`gui.switch_buffer()`]: ../api/gui.html#switch_buffer +[`new_buffer()`]: ../api/_G.html#new_buffer +[`quit()`]: ../api/_G.html#quit +[`reset()`]:../api/_G.html#reset +[`user_dofile()`]: ../api/_G.html#user_dofile +[`string.iconv()`]: ../api/string.html#iconv diff --git a/doc/manual/1_Introduction.md b/doc/manual/1_Introduction.md index 4653d5db..0bdf97e2 100644 --- a/doc/manual/1_Introduction.md +++ b/doc/manual/1_Introduction.md @@ -2,24 +2,26 @@ ## Overview -<div style="float: right; margin: 0 0 1em 1em;"> - <img src="images/textadept.png" alt="Textadept" /> -</div> + Textadept is a fast, minimalist, and ridiculously extensible cross-platform text -editor for programmers. Written in a combination of C and [Lua](http://lua.org) -and relentlessly optimized for speed and minimalism over the years, Textadept is -an ideal editor for programmers who want endless extensibility options without +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 options without sacrificing speed or succumbing to code bloat and featuritis. -#### Fast +[Lua]: http://lua.org + +### Fast Textadept is _fast_. It starts up instantly and has a very responsive user interface (UI). Even though the editor is mostly written in Lua, Lua is one of -the fastest scripting languages available. With [LuaJIT](http://luajit.org), -Textadept is faster than ever before, though using LuaJIT is overkill. +the fastest scripting languages available. With [LuaJIT][], Textadept is faster +than ever before, though using LuaJIT is overkill. + +[LuaJIT]: http://luajit.org -#### Minimalist +### Minimalist Textadept is minimalist. Not only is this apparent in the UI, but the editor's C core was designed to never exceed 2000 lines of code and its Lua extension code @@ -27,7 +29,7 @@ is not supposed to go beyond 4000 lines. After 4 1/2 years of development, Textadept has fewer lines of code (~5000) than it did in its first release (~5600) and is vastly superior in every respect. -#### Ridiculously Extensible +### Ridiculously Extensible Textadept is ridiculously extensible. It was designed to be that way from the very beginning. The features came later. Most of Textadept is written in Lua, @@ -36,9 +38,7 @@ and more. Textadept gives you complete control over the entire application using Lua. You can do everything from moving the caret to changing menus and key commands on-the-fly to handling UI events. The possibilities are limitless. -<div style="float: left; margin: 0 3em 1em 0;"> - <img src="images/splitviews.png" alt="Split Views" /> -</div> + ## Manual Notation @@ -61,13 +61,3 @@ commands on-the-fly to handling UI events. The possibilities are limitless. Mac OSX's (e.g `Ctrl` to `⌘`), but this is not always the case. Please do not view the key equivalents as translations of one another, but rather as separate entities. This will minimize confusion. - -## Features at a Glance - -* Self-contained executable - no installation necessary. -* Entirely keyboard driven. -* Unlimited split views. -* Support for over 80 programming languages. -* Powerful snippets and key commands. -* Code autocompletion and API lookup. -* Unparalleled extensibility. diff --git a/doc/manual/2_Installation.md b/doc/manual/2_Installation.md index 251638eb..ffc8b938 100644 --- a/doc/manual/2_Installation.md +++ b/doc/manual/2_Installation.md @@ -3,51 +3,51 @@ ## Requirements In its bid for minimalism, Textadept also needs very little to run. In fact, the -only thing it needs is [GTK+ 2.0](http://gtk.org) >= 2.16 on Linux systems. GTK -is already included in Windows and Mac OSX packages. Textadept also has its own -version of Lua. +only thing it needs is [GTK+ 2.0][] >= 2.16 on Linux systems. GTK is already +included in Windows and Mac OSX packages. Textadept also has its own version of +Lua. Note: for Win32 and Mac OSX, more than 3/4 of the download and unpackaged application sizes are due to GTK, the cross-platform GUI toolkit Textadept uses. Textadept itself is much smaller. -#### Linux +[GTK+ 2.0]: http://gtk.org + +### Linux Most Linux systems already have GTK+ installed. If not, it is probably available through your package manager. Otherwise, compile and install it from the -[GTK+ website](http://www.gtk.org/download-linux.html). - -#### Mac OSX +[GTK+ website][]. -Prior to 3.5, the GTK+ [Mac OSX Framework][GTK-OSX] was required. Newer versions -are all-inclusive and do not require anything. +[GTK+ website]: http://www.gtk.org/download-linux.html -[GTK-OSX]: http://code.google.com/p/textadept/downloads/detail?name=Gtk-Framework-2.14.3-2-test1.dmg +### Mac OSX -Note that Textadept is designed for Intel Leopard+ Macs. +No requirements other than Mac OSX 10.5 (Leopard) or higher with an Intel CPU. -#### Windows +### Windows -Prior to 3.5, the [GTK+ 2.0 Runtime](http://sourceforge.net/projects/gtk-win/) -was required. Newer versions are all-inclusive and do not require anything. +No requirements. ## Download -Download Textadept from the [project page](http://textadept.googlecode.com/). -Select the appropriate package for your platform. +Download Textadept from the [project page][]. Select the appropriate package for +your platform. + +You can also download an official set of [language-specific modules][], but this +is optional. The list of language modules in the package is contained [here][]. +Textadept includes C/C++ and Lua language modules by default. -You can also download an official set of -[language-specific modules](7_Modules.html#language_specific), but this is -optional. The list of language modules in the package is contained -[here](https://bitbucket.org/mitchell). Textadept includes C/C++ and Lua -language modules by default. +[project page]: http://foicica.com/textadept +[language-specific modules]: 7_Modules.html#Language.Specific +[here]: http://foicica.com/hg ## Installation Textadept is designed to be as easy as possible to install by any user. You do not need to have administrator privileges. -#### Linux +### Linux Unpack the archive anywhere. Run Textadept by running `/path/to/textadept_VERSION/textadept` from the terminal. You can also create a @@ -58,7 +58,7 @@ If you downloaded the set of language-specific modules, unpack it where you unpacked the Textadept archive. The modules will be contained in `/path/to/textadept_VERSION/modules/`. -##### Problems +#### Problems It is difficult to provide a single binary that runs on all Linux platforms since the versions of software installed vary widely from distribution to @@ -75,9 +75,11 @@ former has been compiled to use `libpng12`. If the above situation did not apply to you, do not be alarmed. The solution is actually quite painless even though it requires recompiling Textadept. See the -[compiling](12_Compiling.html) page for more information. +[compiling][] page for more information. -#### Mac OSX +[compiling]: 12_Compiling.html + +### Mac OSX Unpack the archive and move `textadept.app` to your user or system `Applications` directory like any other Mac OSX application. Run Textadept by @@ -87,17 +89,20 @@ If you downloaded the set of language-specific modules, unpack it, right-click `textadept.app`, select `Show Package Contents`, navigate to `Contents/Resources/modules`, and copy the unpacked modules there. -##### Environment Variables +#### Environment Variables By default, GUI apps like Textadept do not utilize environment variables such as -`PATH` from your shell profile. Therefore, any [modules](7_Modules.md) that use -programs contained in `PATH` (e.g. the progams in `/usr/local/bin/`) for run and -compile commands will not be found. The solution is to follow the instructions -[here](http://developer.apple.com/library/mac/#qa/qa1067/_index.html) to export -whichever environment variables you need. At the very least, set `PATH` to be -`$PATH`. You will have to logout and log back in for the changes to take effect. - -#### Windows +`PATH` from your shell profile. Therefore, any [modules][] that use programs +contained in `PATH` (e.g. the progams in `/usr/local/bin/`) for run and compile +commands will not be found. The solution is to follow these [instructions][] to +export whichever environment variables you need. At the very least, set `PATH` +to be `$PATH`. You will have to logout and log back in for the changes to take +effect. + +[modules]: 7_Modules.html +[instructions]: http://developer.apple.com/library/mac/#qa/qa1067/_index.html + +### Windows Unpack the archive anywhere. Run Textadept by double-clicking `textadept.exe`. You can also create shortcuts to the executable in your Start Menu, Quick Launch diff --git a/doc/manual/3_UserInterface.md b/doc/manual/3_UserInterface.md index f610d423..bda4d1fe 100644 --- a/doc/manual/3_UserInterface.md +++ b/doc/manual/3_UserInterface.md @@ -1,8 +1,6 @@ # User Interface -<div style="float: right; margin: 0 0 1em 1em;"> - <img src="images/ui.png" alt="UI" /> -</div> + Textadept's user interface was designed to be simple. It consists of a menubar, editor view, initially hidden find/replace dialog, initially hidden command @@ -37,5 +35,3 @@ pops in and out as you wish. The left side of the statusbar displays any status messages. The right side shows the current buffer's status. - -<br/><br/><br/><br /> diff --git a/doc/manual/4_WorkingWithFiles.md b/doc/manual/4_WorkingWithFiles.md index 0b7820ea..201e46cf 100644 --- a/doc/manual/4_WorkingWithFiles.md +++ b/doc/manual/4_WorkingWithFiles.md @@ -61,8 +61,9 @@ A quicker, though slightly more limited alternative to the standard displays a list of files to open, including files in subdirectories. You can snapopen the current file's directory with `Ctrl+Alt+Shift+O` (`^⌘⇧O` on Mac OSX) or from the `Tools -> Snapopen -> Current Directory` menu. Snapopen is -pretty limited from the menu, but more versatile in scripts. See its -[LuaDoc](../modules/_M.textadept.snapopen.html). `Ctrl+U` (`⌘U`) snaps open -`~/.textadept/`. +pretty limited from the menu, but more versatile in scripts. See its [LuaDoc][]. +`Ctrl+U` (`⌘U`) snaps open `~/.textadept/`. + +[LuaDoc]: ../api/_M.textadept.snapopen.html  diff --git a/doc/manual/5_FileNavigation.md b/doc/manual/5_FileNavigation.md index ed0e5539..953464a7 100644 --- a/doc/manual/5_FileNavigation.md +++ b/doc/manual/5_FileNavigation.md @@ -23,5 +23,3 @@ extends the selection. Textadept supports the keybindings you are accustomed to for navigating text fields in Mac OSX. - -<br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/> diff --git a/doc/manual/6_AdeptEditing.md b/doc/manual/6_AdeptEditing.md index 61faf93e..9dee1183 100644 --- a/doc/manual/6_AdeptEditing.md +++ b/doc/manual/6_AdeptEditing.md @@ -3,17 +3,21 @@ ## Key Commands Textadept is entirely keyboard-driven. See the comprehensive list of key -commands in the [appendix](14_Appendix.html#key_bindings). Key commands can be -modified in your [preferences](9_Preferences.html#key_commands). +commands in the [appendix][]. Key commands can be modified in your +[key preferences][]. + +[appendix]: 14_Appendix.html#Key.Bindings +[key preferences]: 9_Preferences.html#Key.Commands ## Character Autopairing Usually, quote (`'`, `"`) and brace (`(`, `[`, `{`) characters go together in pairs. By default, Textadept automatically inserts the complement character when the first is typed. Similarly, the complement is deleted when you press -`Backspace` (`⌫`) over the first. See the -[preferences](9_Preferences.html#module_settings) page if you would like to -disable this. +`Backspace` (`⌫`) over the first. See the [preferences][] page if you would like +to disable this. + +[preferences]: 9_Preferences.html#Module.Settings ## Word Completion @@ -28,10 +32,9 @@ suggestion. Press `Return` (`↩`) to complete the selected word. Textadept has the capability to autocomplete symbols for programming languages and display API documentation. Lua is of course supported extremely well and -other languages have basic support with the help of -[ctags](http://ctags.sf.net). Symbol completion is available by pressing -`Ctrl+Space` (`⌥⎋` on Mac OSX). Documentation for symbols is available with -`Ctrl+H` (`^H`). +other languages have basic support with the help of [ctags][]. Symbol completion +is available by pressing `Ctrl+Space` (`⌥⎋` on Mac OSX). Documentation for +symbols is available with `Ctrl+H` (`^H`).  @@ -40,16 +43,19 @@ other languages have basic support with the help of  For more information on adding adeptsense support for another language, see -the [LuaDoc](../modules/_M.textadept.adeptsense.html). +the [LuaDoc][]. + +[ctags]: http://ctags.sf.net +[LuaDoc]: ../api/_M.textadept.adeptsense.html ## Find and Replace `Ctrl+F` (`⌘F` on Mac OSX) brings up the Find/Replace dialog. In addition to offering the usual find and replace, Textadept allows you to find with [Lua -patterns](14_Appendix.html#lua_patterns) and replace with Lua captures and even -Lua code! For example: replacing all `(%w+)` with `%(string.upper('%1'))` -capitalizes all words in the buffer. Lua captures (`%n`) are only available from -a Lua pattern search, but embedded Lua code enclosed in `%()` is always allowed. +patterns][] and replace with Lua captures and even Lua code! For example: +replacing all `(%w+)` with `%(string.upper('%1'))` capitalizes all words in the +buffer. Lua captures (`%n`) are only available from a Lua pattern search, but +embedded Lua code enclosed in `%()` is always allowed. Note the `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, `Ctrl+Alt+Shift+R` key commands for find next, find previous, replace, and replace all (`⌘G`, `⌘⇧G`, `^R`, `^⇧R` @@ -57,7 +63,9 @@ respectively on Mac OSX) only work when the Find/Replace dialog is hidden. When it is visible, use the button mnemonics: `Alt+N`, `Alt+P`, `Alt+R`, and `Alt+A` (`⌘N`, `⌘P`, `⌘R`, `⌘A`) for English locale. -#### Find in Files +[Lua patterns]: 14_Appendix.html#Lua.Patterns + +### Find in Files `Ctrl+Shift+F` brings up Find in Files (`⌘⇧F` on Mac OSX) and will prompt for a directory to search. The results are displayed in a new buffer. Double-clicking @@ -69,13 +77,13 @@ for each file a result is found in. The `Match Case`, `Whole Word`, and  -#### Find Incremental +### Find Incremental You can start an incremental search by pressing `Ctrl+Alt+F` (`^⌘F` on Mac OSX). Incremental search searches the buffer as you type. Only the `Match Case` option -is recognized. +is recognized. Pressing `Esc` (`⎋`) stops it. -#### Replace in Selection +### Replace in Selection By default, `Replace All` replaces all text in the buffer. If you want to replace all text in just a portion of the buffer, select a block of text and @@ -83,31 +91,36 @@ then `Replace All`. ## Indentation -#### Increase or Decrease Indent Level +### Change Indent Level The amount of indentation for a selected set of lines is increased by pressing `Tab` (`⇥`) and decreased by pressing `Shift+Tab` (`⇧⇥`). Using these key sequences when no selection is present does not have the same effect. -#### Change Indent Size +### Change Indent Size -The indent size is usually set by a [language-specific -module](7_Modules.html#buffer_properties) or the [theme](8_Themes.html#buffer). -You can set it manually using the `Buffer -> Indentation` menu. Textadept shows -what it is using for indentation in the document statusbar. +The indent size is usually set by a [language-specific module][] or the +[theme][]. You can set it manually using the `Buffer -> Indentation` menu. +Textadept shows what it is using for indentation in the document statusbar.  -#### Using Tabs Instead of Spaces +[language-specific module]: 7_Modules.html#Buffer.Properties +[theme]: 8_Themes.html#Buffer + +### Using Tabs You can use tabs instead of the default spaces by pressing `Ctrl+Alt+Shift+T` (`^⇧T` on Mac OSX) or using the `Buffer -> Toggle Use Tabs` menu. Textadept shows what it is using for indentation in the document statusbar. -The default option is usually set by a [language-specific -module](7_Modules.html#buffer_properties) or the [theme](8_Themes.html#buffer). +The default option is usually set by a [language-specific module][] or the +[theme][]. + +[language-specific module]: 7_Modules.html#Buffer.Properties +[theme]: 8_Themes.html#Buffer -#### Converting Between Tabs and Spaces +### Converting Indentation Use the `Edit -> Convert Indentation` menu to convert indentation. If the buffer is using tabs, all spaces are converted to tabs. If the buffer is using spaces, @@ -115,7 +128,7 @@ all tabs are converted to spaces. ## Selecting Text -#### Rectangular Selection +### Rectangular Selection Holding `Alt+Shift` (`⌥⇧` on Mac OSX) and pressing the arrow keys enables rectangular selections to be made. Start typing to type on each line. @@ -124,7 +137,7 @@ rectangular selections to be made. Start typing to type on each line.  -#### Multiple Selection +### Multiple Selection Clicking the mouse at a point in the buffer while holding `Control` places an additional caret at that point. Clicking and dragging while holding `Control` @@ -132,7 +145,7 @@ creates multiple selections. Start typing to enter text at each selection. This is currently unavailable on Mac OSX. -#### Selecting Entities +### Selecting Entities Textadept allows you to select many different entities from the caret. For example, `Ctrl+"` (`^"` on Mac OSX) selects all characters in a `""` sequence. @@ -157,13 +170,13 @@ occurrences of a variable name in source code. ## Editing Modes -#### Virtual Space +### Virtual Space Virtual space (freehand) mode is enabled and disabled with `Ctrl+Alt+Shift+V` (`^⇧V` in Mac OSX). When enabled, caret movement is not restricted by line endings. -#### Overwrite +### Overwrite Overwrite mode is enabled and disabled with the `Insert` key. When enabled, characters in the buffer will be overwritten instead of inserted as you type. diff --git a/doc/manual/7_Modules.md b/doc/manual/7_Modules.md index 50461062..1b915c85 100644 --- a/doc/manual/7_Modules.md +++ b/doc/manual/7_Modules.md @@ -8,94 +8,105 @@ module: generic and language-specific. ## Generic This class of modules is usually available globally for programming in all -languages or writing plain-text. An example is the -[textadept](../modules/_M.textadept.html) module which implements most of -Textadept's functionality (find/replace, key commands, menus, snippets, etc.). -These kinds of modules are generally loaded on startup. See the -[preferences](9_Preferences.html#user_init) page for instructions on how to load -generic modules when Textadept starts. +languages or writing plain-text. An example is the [textadept module][] which +implements most of Textadept's functionality (find/replace, key commands, menus, +snippets, etc.). These kinds of modules are generally loaded on startup. See the +[preferences][] page for instructions on how to load generic modules when +Textadept starts. + +[textadept module]: ../api/_M.textadept.html +[preferences]: 9_Preferences.html#User.Init ## Language Specific Each module of this class of modules is named after a language lexer in the `lexers/` directory and is only available only for editing code in that particular programming language unless you specify otherwise. Examples are the -[cpp](../modules/_M.cpp.html) and [lua](../modules/_M.lua.html) modules which -provide special editing features for the C/C++ and Lua languages respectively. +[cpp][] and [lua][] modules which provide special editing features for the C/C++ +and Lua languages respectively. + +[cpp]: ../api/_M.cpp.html +[lua]: ../api/_M.lua.html -#### Lexer +### Lexer -All languages have a [lexer](../modules/lexer.html) that performs syntax -highlighting on the source code. While the lexer itself is not part of the -module, its existence in `lexers/` is required. +All languages have a [lexer][] that performs syntax highlighting on the source +code. While the lexer itself is not part of the module, its existence in +`lexers/` is required. -#### Activation +[lexer]: ../api/lexer.html + +### Activation Language-specific modules are automatically loaded when a file of that language is loaded or a buffer's lexer is set to that language. -#### Snippets +### Snippets -Most language-specific modules have a set of -[snippets](../modules/_M.textadept.snippets.html). Press `Ctrl+K` (`⌥⇥` on Mac -OSX) for a list of available snippets or see the module's Lua code. To insert a -snippet, type its trigger followed by the `Tab` (`⇥`) key. Subsequent presses of -`Tab` (`⇥`) causes the caret to enter tab stops in sequential order, `Shift+Tab` -(`⇧⇥`) goes back to the previous tab stop, and `Ctrl+Shift+K` (`⌥⇧⇥` on Mac OSX) -cancels the current snippet. Snippets can be nested (inserted from within -another snippet). +Most language-specific modules have a set of [snippets][]. Press `Ctrl+K` (`⌥⇥` +on Mac OSX) for a list of available snippets or see the module's Lua code. To +insert a snippet, type its trigger followed by the `Tab` (`⇥`) key. Subsequent +presses of `Tab` (`⇥`) causes the caret to enter tab stops in sequential order, +`Shift+Tab` (`⇧⇥`) goes back to the previous tab stop, and `Ctrl+Shift+K` (`⌥⇧⇥` +on Mac OSX) cancels the current snippet. Snippets can be nested (inserted from +within another snippet).   -#### Commands +[snippets]: ../api/_M.textadept.snippets.html + +### Commands -Most language-specific modules have a set of [key -commands](../modules/_M.textadept.keys.html). See the module's Lua code for -which key commands are available. They are typically stored in the `Ctrl+L` -(`⌘L` on Mac OSX) key prefix. +Most language-specific modules have a set of [key commands][]. See the module's +Lua code for which key commands are available. They are typically stored in the +`Ctrl+L` (`⌘L` on Mac OSX) key prefix. -##### Run +[key commands]: ../api/_M.textadept.keys.html + +#### Run Most language-specific modules have a command that runs the code in the current file. Pressing `Ctrl+R` (`⌘R` on Mac OSX) runs that command. -##### Compile +#### Compile Most language-specific modules have a command that compiles the code in the current file. Pressing `Ctrl+Shift+R` (`⌘⇧R` on Mac OSX) runs that command. -##### Block Comments +#### Block Comments Pressing `Ctrl+/` (`⌘/` on Mac OSX) comments or uncomments the code on the selected lines. -#### Buffer Properties +### Buffer Properties Sometimes language-specific modules set default buffer properties like tabs and indentation size. See the module's Lua code for these settings. If you wish to change them or use different settings, see the -[Customizing Modules](#customizing_modules) section below. +[Customizing Modules](#Customizing.Modules) section below. -#### Context Menu +### Context Menu Some language-specific modules add extra actions to the context menu. Right-click inside the view to bring up this menu. ## Getting Modules -The officially supported language modules are hosted on -[Bitbucket](https://bitbucket.org/mitchell) and are available as a separate -download. To upgrade to the most recent version of a module, you can either use -[Mercurial](http://mercurial.selenic.com) (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. If you do not have access to -`_HOME`, place the updated module in your `_USERHOME` and replace all instances -of `_HOME` with `_USERHOME` in the module's `init.lua`. +The officially supported language modules are hosted [here][] and are available +as a separate download. To upgrade to the most recent version of a module, you +can 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. If you do not have access to `_HOME`, +place the updated module in your `_USERHOME` and replace all instances of +`_HOME` with `_USERHOME` in the module's `init.lua`. + +For now, user-created modules are obtained from the [wiki][]. -For now, user-created modules are obtained from the -[wiki](http://caladbolg.net/textadeptwiki). +[here]: http://foicica.com/hg +[Mercurial]: http://mercurial.selenic.com +[wiki]: http://caladbolg.net/textadeptwiki ## Installing Modules @@ -107,7 +118,9 @@ module, it will be loaded instead of the one that comes with Textadept. ## Developing Modules -See the [LuaDoc](../modules/_M.html) for modules. +See the [LuaDoc][] for modules. + +[LuaDoc]: ../api/_M.html ## Customizing Modules @@ -140,5 +153,6 @@ from `post_init.lua`: end Similarly, you can use `post_init.lua` to change the compile/run commands, load -more [Adeptsense tags](../modules/_M.textadept.adeptsense.html#load_ctags), and -add additional key commands and snippets. +more [Adeptsense tags][], and add additional key commands and snippets. + +[Adeptsense tags]: ../api/_M.textadept.adeptsense.html#load_ctags diff --git a/doc/manual/8_Themes.md b/doc/manual/8_Themes.md index 81ee285d..b40135e2 100644 --- a/doc/manual/8_Themes.md +++ b/doc/manual/8_Themes.md @@ -11,10 +11,11 @@ the name of the theme you would like to use. Themes apply to all buffers. You cannot assign a theme to a particular file or filetype. You can change things like tab and indent settings per filetype -however by creating a [language-specific -module](7_Modules.html#buffer_properties). +however by creating a [language-specific module]. -## Creating or Modifying a Theme +[language-specific module]: 7_Modules.html#Buffer.Properties + +## Creating or Modifying Themes Each theme is a single folder on the filesystem composed of three files: `lexer.lua`, `buffer.lua`, and `view.lua`. It is recommended to put themes in @@ -27,15 +28,16 @@ To use a theme not located in `~/.textadept/themes/` or Textadept's `themes/` directory, you need to specify an absolute path to the theme's folder in your `~/.textadept/theme` file. -#### Lexer +### Lexer Textadept uses lexers to assign names to buffer elements like comments, strings, and keywords. These elements are assigned styles composed of font and color information in the theme's `lexer.lua`. See the `Styling Tokens` section of the -[lexer](../modules/lexer.html) page for more information on how to create styles -and colors. +[lexer][] page for more information on how to create styles and colors. + +[lexer]: ../api/lexer.html -#### Buffer +### Buffer `buffer.lua` contains buffer-specific properties like indentation size and whether or not to use tabs. For example, to set the default tab size to 4 and @@ -45,12 +47,16 @@ use tabs: buffer.use_tabs = true buffer.indent = 4 -See the [LuaDoc](../modules/buffer.html) for documentation on the properties. +See the [LuaDoc][] for documentation on the properties. + +[LuaDoc]: ../api/buffer.html -#### View +### View `view.lua` contains view-specific properties like caret and selection colors. -See the [LuaDoc](../modules/buffer.html) for documentation on the properties. +See the [LuaDoc][] for documentation on the properties. + +[LuaDoc]: ../api/buffer.html ## Testing Themes @@ -66,16 +72,17 @@ Any errors that occur in the theme are printed to `io.stderr`. ## Theming the GUI There is no way to theme GUI controls like text fields and buttons from within -Textadept. Instead, use [GTK Resource files][gtkrc]. The `GtkWindow` name is +Textadept. Instead, use [GTK Resource files][]. The `GtkWindow` name is `textadept`. For example, styling all text fields with a `"textadept-entry-style"` would be done like this: widget "textadept*GtkEntry*" style "textadept-entry-style" -[gtkrc]: http://library.gnome.org/devel/gtk/stable/gtk-Resource-Files.html +[GTK Resource files]: http://library.gnome.org/devel/gtk/stable/gtk-Resource-Files.html ## Getting Themes -For now, user-created themes are obtained from the -[wiki](http://caladbolg.net/textadeptwiki). The classic `dark`, `light`, and -`scite` themes prior to version 4.3 have been moved there. +For now, user-created themes are obtained from the [wiki][]. The classic `dark`, +`light`, and `scite` themes prior to version 4.3 have been moved there. + +[wiki]: http://caladbolg.net/textadeptwiki diff --git a/doc/manual/9_Preferences.md b/doc/manual/9_Preferences.md index bd7fedbd..abceaa97 100644 --- a/doc/manual/9_Preferences.md +++ b/doc/manual/9_Preferences.md @@ -1,8 +1,9 @@ # Preferences At this point it is assumed you are at least familiar with the basics of -[Lua](http://www.lua.org). You do not have to know a lot of the language to -configure Textadept. +[Lua][]. You do not have to know a lot of the language to configure Textadept. + +[Lua]: http://www.lua.org ## User Init @@ -37,11 +38,11 @@ It is important to realize that Textadept will not load anything you do not tell it to. If your `~/.textadept/init.lua` exists and is empty, no modules are loaded (pretty much rendering Textadept useless). -#### Module Settings +### Module Settings Many of Textadept's modules have settings you can change from your `~/.textadept/init.lua`. These settings are viewed from module's -[LuaDoc](../index.html). For example, to disable character autopairing and +[LuaDoc][]. For example, to disable character autopairing and whitespace stripping on save, your `~/.textadept/init.lua` might look like: require 'textadept' @@ -49,13 +50,17 @@ whitespace stripping on save, your `~/.textadept/init.lua` might look like: _M.textadept.editing.AUTOPAIR = false _M.textadept.editing.STRIP_WHITESPACE_ON_SAVE = false -#### Other +[LuaDoc]: ../api/index.html + +### Other Your `~/.textadept/init.lua` is not restricted to just loading modules or setting preferences. It is just Lua code that is run when Textadept loads. For -more information, see the [scripting](11_Scripting.html) page. +more information, see the [scripting][] page. -##### Snippets +[scripting]: 11_Scripting.html + +#### Snippets You can add global snippets to `snippets` such as: @@ -65,7 +70,7 @@ You can add global snippets to `snippets` such as: So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX) will insert the snippet. -##### Key Commands +#### Key Commands It is not recommended to edit Textadept's `modules/textadept/keys.lua` for changing the key bindings since your changes could be overwritten when updating @@ -107,29 +112,32 @@ can override or add to them in your `~/.textadept/mime_types.conf`: It is not recommended to edit Textadept's `modules/textadept/mime_types.conf` because your changes may be overwritten when updating Textadept. -#### Detection by File Extension +### Detect by File Extension file_ext lexer Note: `file_ext` should not start with a `.` (period). -#### Detection by Shebang Keywords +### Detect by Shebang Keywords #shebang_word lexer Examples of `shebang_word`'s are `lua`, `ruby`, `python`. -#### Detection by Pattern +### Detect by Pattern /pattern lexer Only the last space, the one separating the pattern from the lexer, is significant. No spaces in the pattern need to be escaped. -## Default Run and Compile Commands and Block Quotes for Languages +## More Language Preferences Textadept does not come with language-specific modules for all languages so you can add run commands, compile commands, and block quotes manually: -* [Run/Compile commands](http://caladbolg.net/textadeptwiki/index.php?n=Main.RunSupplemental) -* [Block Quotes](http://caladbolg.net/textadeptwiki/index.php?n=Main.CommentSupplemental) +* [Run/Compile commands][] +* [Block Quotes][] + +[Run/Compile commands]: http://caladbolg.net/textadeptwiki/index.php?n=Main.RunSupplemental +[Block Quotes]: http://caladbolg.net/textadeptwiki/index.php?n=Main.CommentSupplemental diff --git a/modules/cpp/init.lua b/modules/cpp/init.lua index d8a573a5..42bc1962 100644 --- a/modules/cpp/init.lua +++ b/modules/cpp/init.lua @@ -6,8 +6,8 @@ local M = {} --- -- The cpp module. -- It provides utilities for editing C/C++ code. --- User tags are loaded from _USERHOME/modules/cpp/tags and user apis are loaded --- from _USERHOME/modules/cpp/api. +-- User tags are loaded from `_USERHOME/modules/cpp/tags` and user apis are +-- loaded from `_USERHOME/modules/cpp/api`. module('_M.cpp')]] -- Markdown: diff --git a/modules/lua/init.lua b/modules/lua/init.lua index 0accbb5c..2a59c666 100644 --- a/modules/lua/init.lua +++ b/modules/lua/init.lua @@ -6,8 +6,8 @@ local M = {} --- -- The lua module. -- It provides utilities for editing Lua code. --- User tags are loaded from _USERHOME/modules/lua/tags and user apis are loaded --- from _USERHOME/modules/lua/api. +-- User tags are loaded from `_USERHOME/modules/lua/tags` and user apis are +-- loaded from `_USERHOME/modules/lua/api`. module('_M.lua')]] -- Markdown: diff --git a/modules/textadept/adeptsense.lua b/modules/textadept/adeptsense.lua index 4e8d1286..f2b022f8 100644 --- a/modules/textadept/adeptsense.lua +++ b/modules/textadept/adeptsense.lua @@ -21,14 +21,16 @@ module('_M.textadept.adeptsense')]] -- ## Creating an Adeptsense -- -- Adeptsenses exist per-language and are typically defined in a --- [language-specific module](../manual/7_Modules.html#language_specific). --- First check to see if the module for your language has an Adeptsense. If not, --- you will need to create one. The language modules included with Textadept --- have Adeptsenses so they can be used for reference. If your language is --- similar to any of those languages, you can copy and modify the existing --- language's Adeptsense, saving some time and effort. +-- [language-specific module][]. First check to see if the module for your +-- language has an Adeptsense. If not, you will need to create one. The language +-- modules included with Textadept have Adeptsenses so they can be used for +-- reference. If your language is similar to any of those languages, you can +-- copy and modify the existing language's Adeptsense, saving some time and +-- effort. -- --- #### Terminology +-- [language-specific module]: _M.html#Language-Specific.Modules +-- +-- ### Terminology -- -- Not all languages have "classes", "functions", and "fields" in the full sense -- of the word. Normally classes are referred to as objects in Object Oriented @@ -41,7 +43,7 @@ module('_M.textadept.adeptsense')]] -- For Lua, consider modules and tables as "classes", functions as "functions", -- and module/table keys as "fields". -- --- #### Introduction +-- ### Introduction -- -- Open the language-specific module for editing and create a new instance of an -- Adeptsense. @@ -54,19 +56,19 @@ module('_M.textadept.adeptsense')]] -- -- Where 'lua' is replaced by your language's name. -- --- #### Syntax Options +-- ### Syntax Options -- -- The syntax of different languages varies so the Adeptsense must be configured -- for your language in order to function properly. See the [`syntax`](#syntax) -- table documentation for all options. -- --- ##### syntax.self +-- #### `self` -- -- The first syntax option is `syntax.self`. While Lua has a `self` identifier, -- it is not used in the usual sense for a class instance so it will just be -- ignored. -- --- ##### syntax.class_definition +-- #### `class_definition` -- -- Next is `syntax.class_definition`. Lua does not really have the "class" -- concept most OOP programmers are used to, but modules do behave somewhat like @@ -76,29 +78,29 @@ module('_M.textadept.adeptsense')]] -- -- The "class"'s name is the identifier in quotes. -- --- ##### syntax.word_chars +-- #### `word_chars` -- -- Lua words already consist of the default `%w_` so no changes are necessary. -- --- ##### syntax.symbol_chars +-- #### `symbol_chars` -- -- In addition to the usual `[%w_%.]` symbol characters, Lua also allows symbols -- to contain a `:`. -- -- sense.syntax.symbol_chars = '[%w_%.:]' -- --- ##### syntax.type_declarations +-- #### `type_declarations` -- -- Since Lua has no type declarations (e.g. `int x` in C), the -- `syntax.type_declarations` table should be empty: -- -- sense.syntax.type_declarations = {} -- --- ##### syntax.type\_declarations\_exclude +-- #### `type_declarations_exclude` -- -- Since Lua has no type declarations, no changes are necessary. -- --- ##### syntax.type_assignments +-- #### `type_assignments` -- -- Sometimes a type can be inferred by the right side of a variable assignment. -- In the Lua code `local foo = 'bar'`, the variable `foo` has type `string`. @@ -114,7 +116,7 @@ module('_M.textadept.adeptsense')]] -- assignment should be matched, otherwise `local foo = bar('baz')` could infer -- an incorrect type. -- --- #### Completion Lists +-- ### Completion Lists -- -- The [`completions`](#completions) table contains the completion lists for -- all classes. Each table entry key is the class's name and the value is a @@ -132,19 +134,18 @@ module('_M.textadept.adeptsense')]] -- Obviously manually creating completion lists would be incredibly -- time-consuming so there is a shortcut method. -- --- ##### Ctags +-- #### Ctags -- --- Adeptsense recognizes the output from [Ctags](http://ctags.sourceforge.net/) --- and can populate the `completions` table from it with a little bit of help. --- Ctags has a list of "kinds" for every language. You can see them by running --- `ctags --list-kinds` in your shell. Since Adeptsense only cares about --- classes, functions, and fields, you need to let it know which kind of tag is --- which. Unfortunately, Lua support in Ctags is not good at all. Instead, --- Textadept has a utility (`scripts/adeptsensedoc.lua`) to generate a fake set --- of tags that is more useful. Functions are tagged `'f'` and should be --- recognized as such; table keys are tagged `'t'` and should be recognized as --- fields; module fields, `'F'`, should be fields; and modules, `'m'`, should be --- classes: +-- Adeptsense recognizes the output from [Ctags][] and can populate the +-- `completions` table from it with a little bit of help. Ctags has a list of +-- "kinds" for every language. You can see them by running `ctags --list-kinds` +-- in your shell. Since Adeptsense only cares about classes, functions, and +-- fields, you need to let it know which kind of tag is which. Unfortunately, +-- Lua support in Ctags is not good at all. Instead, Textadept has a utility +-- (`scripts/adeptsensedoc.lua`) to generate a fake set of tags that is more +-- useful. Functions are tagged `'f'` and should be recognized as such; table +-- keys are tagged `'t'` and should be recognized as fields; module fields, +-- `'F'`, should be fields; and modules, `'m'`, should be classes: -- -- sense.ctags_kinds = { -- f = 'functions', @@ -159,7 +160,9 @@ module('_M.textadept.adeptsense')]] -- -- Textadept comes with a set of Ctags for its Lua API. -- --- #### API Documentation +-- [ctags]: http://ctags.sourceforge.net +-- +-- ### API Documentation -- -- Adeptsense can show API documentation for symbols from files specified in its -- [`api_files`](#api_files) table. See the previous link for documentation on @@ -167,7 +170,7 @@ module('_M.textadept.adeptsense')]] -- -- sense.api_files = { _HOME..'/modules/lua/api' } -- --- #### Triggers +-- ### Triggers -- -- Triggers are characters or character sequences that trigger an autocompletion -- list to be displayed. Lua has two characters that can do so: `.` and `:`. The @@ -178,7 +181,7 @@ module('_M.textadept.adeptsense')]] -- sense:add_trigger('.') -- sense:add_trigger(':', false, true) -- --- #### User-Settings +-- ### User-Settings -- -- Finally, you should allow the users of your Adeptsense to supply their own -- Ctags and API files in addition to any default ones you loaded or specified @@ -192,13 +195,13 @@ module('_M.textadept.adeptsense')]] -- sense.api_files[#sense.api_files + 1] = _USERHOME..'/modules/lua/api' -- end -- --- #### Summary +-- ### Summary -- -- The above method of setting syntax options, ctags kinds, and trigger -- characters for an Adeptsense is sufficient for most static and some dynamic -- languages. The rest of this document is devoted to more complex techniques. -- --- #### Overriding Adeptsense Functions +-- ### Overriding Adeptsense Functions -- -- Sometimes Adeptsense's default behavior is not sufficient. Maybe the -- `type_declarations` and `type_assignments` tables used by the @@ -218,7 +221,7 @@ module('_M.textadept.adeptsense')]] -- The default Adeptsense functions are called by using the `self.super` -- reference. -- --- ##### Examples for Ruby +-- #### Examples for Ruby -- -- In Ruby, everything is an object -- even numbers. Since numbers do not have -- a type declaration, the [`get_class()`](#get_class) function should return @@ -252,7 +255,7 @@ module('_M.textadept.adeptsense')]] -- that handles strings, hashes, symbols, and regexps as well. Please refer to -- it for more information. -- --- ##### Examples for Java +-- #### Examples for Java -- -- Autocomplete of Java `import` statements is something nice to have. Ctags -- produces a tag for packages so it is rather straightforward to build an @@ -312,7 +315,7 @@ module('_M.textadept.adeptsense')]] -- self.imports = {} -- end -- --- #### Other Adeptsense Settings +-- ### Other Adeptsense Settings -- -- * `always_show_globals` [bool] -- Include globals in the list of completions offered. diff --git a/modules/textadept/keys.lua b/modules/textadept/keys.lua index 0bdfbe54..f23445de 100644 --- a/modules/textadept/keys.lua +++ b/modules/textadept/keys.lua @@ -6,7 +6,7 @@ local M = {} --- -- Defines key commands for Textadept. -- This set of key commands is pretty standard among other text editors. --- This module, should be 'require'ed last, but before _M.textadept.menu. +-- This module, should be `require`ed last, but before `_M.textadept.menu`. module('_M.textadept.keys')]] -- Utility functions. diff --git a/modules/textadept/mime_types.lua b/modules/textadept/mime_types.lua index 8364717b..7c3f55c0 100644 --- a/modules/textadept/mime_types.lua +++ b/modules/textadept/mime_types.lua @@ -15,7 +15,7 @@ module('_M.textadept.mime_types')]] -- This is useful for overriding its key commands since they are not available -- when Textadept starts. -- Arguments: --- * `lang`: The language lexer name. +-- * `lang`: The language lexer name. -- Events. local events, events_connect = events, events.connect diff --git a/modules/textadept/run.lua b/modules/textadept/run.lua index 4f1aea0c..56cd91ad 100644 --- a/modules/textadept/run.lua +++ b/modules/textadept/run.lua @@ -5,8 +5,8 @@ local M = {} --[[ This comment is for LuaDoc. --- -- Module for running/executing source files. --- Typically, language-specific modules populate the 'compile_command', --- 'run_command', and 'error_detail' tables for a particular language's file +-- Typically, language-specific modules populate the `compile_command`, +-- `run_command`, and `error_detail` tables for a particular language's file -- extension. module('_M.textadept.run')]] @@ -20,8 +20,8 @@ module('_M.textadept.run')]] -- you want to override the default handler that prints the output to a new -- view. -- Arguments: --- * `lexer`: The lexer language. --- * `output`: The output from the command. +-- * `lexer`: The lexer language. +-- * `output`: The output from the command. -- * `_G.events.RUN_OUTPUT` -- Called after a run command is executed. -- When connecting to this event (typically from a language-specific module), @@ -29,8 +29,8 @@ module('_M.textadept.run')]] -- you want to override the default handler that prints the output to a new -- view. -- Arguments: --- * `lexer`: The lexer language. --- * `output`: The output from the command. +-- * `lexer`: The lexer language. +-- * `output`: The output from the command. -- Events. local events, events_connect, events_emit = events, events.connect, events.emit @@ -45,6 +45,7 @@ events.COMPILE_OUTPUT, events.RUN_OUTPUT = COMPILE_OUTPUT, RUN_OUTPUT -- + `%(filedir)`: The current file's directory path. -- + `%(filename)`: The name of the file including extension. -- + `%(filename_noext)`: The name of the file excluding extension. +-- @param lexer The current lexer. -- @name execute function M.execute(command, lexer) local filepath = buffer.filename:iconv(_CHARSET, 'UTF-8') @@ -71,6 +72,7 @@ end -- Executes a compile or run command. -- @param cmd_table Either `compile_command` or `run_command`. +-- @param lexer The current lexer. local function command(cmd_table, lexer) if not buffer.filename then return end buffer:save() @@ -116,6 +118,7 @@ events_connect(RUN_OUTPUT, function(lexer, output) gui.print(output) end) --- -- A table of error string details. -- Each entry is a table with the following fields: +-- -- + `pattern`: The Lua pattern that matches a specific error string. -- + `filename`: The index of the Lua capture that contains the filename the -- error occured in. @@ -123,6 +126,7 @@ events_connect(RUN_OUTPUT, function(lexer, output) gui.print(output) end) -- error occured on. -- + `message`: [Optional] The index of the Lua capture that contains the -- error's message. A call tip will be displayed if a message was captured. +-- -- When an error message is double-clicked, the user is taken to the point of -- error. -- This table is usually populated by language-specific modules. diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua index a99a51b8..60b9402d 100644 --- a/modules/textadept/snippets.lua +++ b/modules/textadept/snippets.lua @@ -36,7 +36,7 @@ module('_M.textadept.snippets')]] -- -- A snippet to insert may contain any of the following: -- --- #### Plain Text +-- ### Plain Text -- -- Any plain text characters may be used with the exception of `%` followed -- immediately by a digit (`0`-`9`), `(`, `)`, `>`, or `]` character. These are @@ -45,7 +45,7 @@ module('_M.textadept.snippets')]] -- another `%` to the first `%`. For example, `%%>` in the snippet inserts a -- literal `%>` into the document. -- --- #### Placeholders +-- ### Placeholders -- -- Textadept's snippets provide a number of different placeholders. The simplest -- ones are of the form @@ -82,17 +82,17 @@ module('_M.textadept.snippets')]] -- variable (containing the current selection in the buffer). After execution, -- the placeholder contains the return value of the code that was run. -- --- Shell code is executed using Lua's [`io.popen()`][io_popen] which reads from --- the process' standard output (STDOUT). After execution, the placeholder will +-- Shell code is executed using Lua's [`io.popen()`][] which reads from the +-- process' standard output (STDOUT). After execution, the placeholder will -- contain the STDOUT of the process. -- --- [io_popen]: http://www.lua.org/manual/5.1/manual.html#pdf-io.popen +-- [`io.popen()`]: http://www.lua.org/manual/5.2/manual.html#pdf-io.popen -- -- These kinds of placeholders can be used to transform mirrored text. For -- example, `%2<([[%1]]):gsub('^.', function(c) return c:upper() end)>` will -- capitalize a mirrored `%1` placeholder. -- --- ##### Important Note +-- #### Important Note -- -- It is very important that any `%`, `(`, `)`, `>`, or `]` characters -- **within** placeholders be escaped with a `%` as necessary. Otherwise, diff --git a/scripts/adeptsensedoc.lua b/scripts/adeptsensedoc.lua index cfae8898..61f651b4 100644 --- a/scripts/adeptsensedoc.lua +++ b/scripts/adeptsensedoc.lua @@ -184,12 +184,10 @@ function start(doc) end -- Tag the functions and write the apidoc. for _, f in ipairs(m.functions) do - if not f:find('no_functions') then -- ignore placeholders - local func = f:match('[^%.:]+$') - local ext_fields = module == '_G' and '' or 'class:'..module - write_tag(ctags, func, 'f', ext_fields) - write_apidoc(apidoc, m, m.functions[f]) - end + local func = f:match('[^%.:]+$') + local ext_fields = module == '_G' and '' or 'class:'..module + write_tag(ctags, func, 'f', ext_fields) + write_apidoc(apidoc, m, m.functions[f]) end -- Tag the tables and write the apidoc. for _, t in ipairs(m.tables or {}) do diff --git a/scripts/markdowndoc.lua b/scripts/markdowndoc.lua new file mode 100644 index 00000000..4bfb10ed --- /dev/null +++ b/scripts/markdowndoc.lua @@ -0,0 +1,221 @@ +-- Copyright 2007-2012 Mitchell mitchell<att>caladbolg.net. See LICENSE. + +local ipairs, type = ipairs, type +local io_open, io_popen = io.open, io.popen +local string_format, string_rep = string.format, string.rep +local table_concat = table.concat + +--- +-- Markdown doclet for Luadoc. +-- Requires Discount (http://www.pell.portland.or.us/~orc/Code/discount/). +-- @usage luadoc -d [output_path] -doclet path/to/markdowndoc [file(s)] +module('markdowndoc') + +local NAVFILE = '%s* [%s](%s)\n' +local FUNCTION = '<a id="%s" />\n### `%s` (%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 TABLE = '<a id="%s" />\n### `%s`\n\n' +--local TABLE = '### `%s`\n\n' +local FIELD = '> * `%s`: %s\n' +local HTML = [[ + <!doctype html> + <html> + <head> + <title>%(title)</title> + <link rel="stylesheet" href="../style.css" type="text/css" /> + <meta charset="utf-8" /> + </head> + <body> + <div id="content"> + <div id="nav"> + <div class="title">Modules</div> + %(nav) + </div> + <div id="toc"> + <div class="title">Contents</div> + %(toc) + </div> + <div id="main"> + %(main) + </div> + </div> + </body> + </html> +]] + +-- Writes LuaDoc hierarchical module navigation to the given file. +-- @param f The navigation file being written to. +-- @param list The module list. +-- @param parent String parent module with a trailing '.' for sub-modules in +-- order to generate full page links. +local function write_nav(f, list, parent) + if not parent then parent = '' end + local level = 0 + for _ in parent:gmatch('%.') do level = level + 1 end + for _, name in ipairs(list) do + f:write(string_format(NAVFILE, string_rep(' ', level * 4), name, + parent..name..'.html')) + if list[name] then + f:write('\n') + write_nav(f, list[name], parent..name..'.') + end + end +end + +-- Writes a LuaDoc description to the given file. +-- @param f The markdown file being written to. +-- @param description The description. +local function write_description(f, description) + f:write(string_format(DESCRIPTION, description)) +end + +-- Writes a LuaDoc list to the given file. +-- @param f The markdown file being written to. +-- @param title The title of the list. +-- @param fmt The format of a list item. +-- @param list The LuaDoc list. +local function write_list(f, title, fmt, list) + if not list or #list == 0 then return end + if type(list) == 'string' then list = { list } end + f:write(string_format(LIST_TITLE, title)) + for _, value in ipairs(list) do + f:write(string_format(fmt, value, value)) + end + f:write('\n') +end + +-- Writes a LuaDoc hashmap to the given file. +-- @param f The markdown file being written to. +-- @param title The title of the hashmap. +-- @param fmt The format of a hashmap item. +-- @param list The LuaDoc hashmap. +local function write_hashmap(f, title, fmt, hashmap) + if not hashmap or #hashmap == 0 then return end + f:write(string_format(LIST_TITLE, title)) + for _, name in ipairs(hashmap) do + f:write(string_format(fmt, name, hashmap[name] or '')) + end + f:write('\n') +end + +-- Called by LuaDoc to process a doc object. +-- @param doc The LuaDoc doc object. +function start(doc) + local modules, files = doc.modules, doc.files + + -- Create the navigation list. + local hierarchy = {} + for _, name in ipairs(modules) do + local parent, self = name:match('^(.-)%.?([^.]+)$') + local h = hierarchy + for table in parent:gmatch('[^.]+') do + if not h[table] then h[table] = {} end + h = h[table] + end + h[#h + 1] = self + end + local navfile = options.output_dir..'/api/.nav.md' + local f = io_open(navfile, 'wb') + write_nav(f, hierarchy) + f:close() + local p = io_popen('markdown "'..navfile..'"') + local nav = p:read('*all') + p:close() + + -- Create a map of doc objects to file names so their Markdown doc comments + -- can be extracted. + local filedocs = {} + for _, name in ipairs(files) do filedocs[files[name].doc] = name end + + -- Loop over modules, creating Markdown documents. + for _, name in ipairs(modules) do + local module = modules[name] + local filename = filedocs[module.doc] + + local mdfile = options.output_dir..'/api/'..name..'.md' + local f = io_open(mdfile, 'wb') + + -- Write the header and description. + f:write('# ', name, '\n\n') + f:write(module.description, '\n\n') + + -- Extract any Markdown doc comments and insert them. + -- Markdown doc comments must immediately proceed a 'module' declaration + -- (excluding blank lines), start with '-- Markdown:', and end on a blank or + -- uncommented line. + if filename then + local module_declaration, markdown = false, false + local module_file = io_open(filename, 'rb') + for line in module_file:lines() do + if not module_declaration and line:find('^module') then + module_declaration = true + elseif module_declaration and not markdown and line ~= '' then + if line ~= '-- Markdown:' then break end + markdown = true + elseif markdown then + line = line:match('^%-%-%s?(.*)$') + if not line then break end + f:write(line, '\n') + end + end + module_file:close() + end + f:write('\n') + f:write('- - -\n\n') + + -- Write functions. + local funcs = module.functions + if #funcs > 0 then + f:write('## Functions\n\n') + f:write('- - -\n\n') + for _, fname in ipairs(funcs) do + local func = funcs[fname] + f:write(string_format(FUNCTION, func.name, func.name, + table_concat(func.param, ', '):gsub('_', '\\_'))) + write_description(f, func.description) + write_hashmap(f, 'Parameters', PARAM, func.param) + write_list(f, 'Usage', USAGE, func.usage) + write_list(f, 'Return', RETURN, func.ret) + write_list(f, 'See also', SEE, func.see) + f:write('- - -\n\n') + end + f:write('\n') + end + + -- Write tables. + local tables = module.tables + if #tables > 0 then + f:write('## Tables\n\n') + f:write('- - -\n\n') + for _, tname in ipairs(tables) do + local tbl = tables[tname] + f:write(string_format(TABLE, tbl.name, tbl.name)) + write_description(f, tbl.description) + write_hashmap(f, 'Fields', FIELD, tbl.field) + write_list(f, 'Usage', USAGE, tbl.usage) + write_list(f, 'See also', SEE, tbl.see) + f:write('- - -\n\n') + end + end + + f:close() + + -- Write HTML. + local p = io_popen('markdown -f toc -T "'..mdfile..'"') + local toc, main = p:read('*all'):match('^(.-\n</ul>\n)(.+)$') + p:close() + toc = toc:gsub('(<a.-)%b()(</a>)', '%1%2') -- strip function parameters + f = io_open(options.output_dir..'/api/'..name..'.html', 'wb') + local html = HTML:gsub('%%%(([^)]+)%)', { + title = name..' - Textadept API', nav = nav, toc = toc, main = main + }) + f:write(html) + f:close() + end +end diff --git a/scripts/update_doc b/scripts/update_doc index 74d1dd72..ccd42444 100755 --- a/scripts/update_doc +++ b/scripts/update_doc @@ -23,115 +23,77 @@ end -- Generate LuaDoc. if luadoc then - os.execute('rm -rf ../doc/modules/') - os.execute('cd ../; luadoc -d doc/ --nofiles modules/ core/ lexers/lexer.lua') - - -- Insert Markdown in modules into LuaDoc. - local p = io.popen('grep -r "\\-\\- Markdown:" ../*') - for file in p:lines() do - local module - - -- Open the Lua file and extract the Markdown lines. - local f = io.open(file:match('^[^:]+')) - local markdown, flag = {}, false - for line in f:lines() do - if flag and line:match('^%-%-') then - local match = line:match('^%-%- ([^\n]+)') - if match and match:find('^%s*[*+] ') then match = match..'<br />' end - markdown[#markdown + 1] = match or '' - elseif flag then -- markdown ended - break - elseif line:match('^%-%- Markdown:') then - flag = true - elseif line:match('^module') then - module = line:match("^module%('([^']+)") - end - end - f:close() - - -- Convert the Markdown into HTML. - markdown = table.concat(markdown, '\n') - f = io.open('tmp', 'w') - f:write(markdown) - f:close() - f = io.popen('perl ../doc/MultiMarkdown.pl tmp') - markdown = f:read('*all') - f:close() - os.execute('rm tmp') - - -- Insert the Marked down HTML in the LuaDoc HTML file. - local filename = '../doc/modules/'..module..'.html' - f = io.open(filename) - local contents = f:read('*all') - f:close() - local s = contents:find('<h2>Functions</h2>') - if not s then s = contents:find('<h2>Tables</h2>') end - contents = contents:sub(1, s - 1)..markdown..contents:sub(s) - f = io.open(filename, 'w') - f:write(contents) - f:close() - end - p:close() - - -- Modify default CSS. - os.execute("sed -i 's/pre.example/pre, pre.example/;' ../doc/luadoc.css") + os.execute('rm -r ../doc/api/*') + os.execute('luadoc -d ../doc -doclet markdowndoc '.. + '../modules ../core ../lexers/lexer.lua') end -- Generate the Manual. if manual then - p = io.popen('ls -1 ../doc/manual/*.md') - for mdfile in p:lines() do - local htmlfile = mdfile:match('^(.+).md$')..'.html' - html = [[ - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - <html> + local HTML = [[ + <!doctype html> + <html> <head> - <title>Textadept Manual</title> - <meta charset="utf-8" /> - <link rel="stylesheet" href="luadoc.css" type="text/css" /> + <title>%(title)</title> + <link rel="stylesheet" href="../style.css" type="text/css" /> + <meta charset="utf-8" /> </head> - <body> - <div id="container"> - <div id="main"> - <div id="navigation"> - - %sidebar% - - </div> - <div id="content"> - - %content% - - </div> - </div> - <div id="about"> - <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p> - </div> - </div> + <div id="content"> + <div id="nav"> + <div class="title">Manual</div> + %(nav) + </div> + <div id="toc"> + <div class="title">Contents</div> + %(toc) + </div> + <div id="main"> + %(main) + </div> + </div> </body> - </html> - ]] - - local sidebar_md = io.popen('../doc/MultiMarkdown.pl ../doc/sidebar.md') - html = html:gsub('%%sidebar%%', sidebar_md:read('*all')) - sidebar_md:close() - local content_md = io.popen('../doc/MultiMarkdown.pl '..mdfile) - local md = content_md:read('*all'):gsub('%%', '%%%%') - md = md:gsub('(<h%d>)([^<]+)(</h%d>)', - function(s, text, e) - return string.format('%s<a name="%s"></a>%s%s', s, - text:gsub(' ', '_'):lower(), text, e) - end) - html = html:gsub('%%content%%', md) - content_md:close() + </html> + ]] + + -- Get manual pages. + local pages = {} + local lfs = require 'lfs' + for file in lfs.dir('../doc/manual/') do + if file:find('^%d+_.-%.md$') then pages[#pages + 1] = file end + end + table.sort(pages) + pages[#pages + 1] = '../../README.md' + pages[#pages + 1] = '../../CHANGELOG.md' + pages[#pages + 1] = '../../THANKS.md' + + -- Create the navigation list. + local navfile = '../doc/manual/.nav.md' + local f = io.open(navfile, 'wb') + for _, page in ipairs(pages) do + local name = page:match('^%A+(.-)%.md$'):gsub('(%l)(%u)', '%1 %2') + if page:find('^%.%./') then page = page:match('^%A+(.+)$') end + f:write('* [', name, '](', page:gsub('%.md$', '.html'), ')\n') + end + f:close() + local p = io.popen('markdown "'..navfile..'"') + local nav = p:read('*all') + p:close() - local f = io.open(htmlfile, 'w') + -- Write HTML. + for _, page in ipairs(pages) do + local name = page:match('^%A+(.-)%.md$'):gsub('(%l)(%u)', '%1 %2') + local p = io.popen('markdown -f toc -T "../doc/manual/'..page..'"') + local toc, main = p:read('*all'):match('^(.-\n</ul>\n)(.+)$') + p:close() + if page:find('^%.%./') then page = page:match('^%A+(.+)$') end + f = io.open('../doc/manual/'..page:gsub('%.md$', '.html'), 'wb') + local html = HTML:gsub('%%%(([^)]+)%)', { + title = name..' - Textadept Manual', nav = nav, toc = toc, main = main + }) f:write(html) f:close() end - p:close() end -- Generate Doxygen documentation. |