diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/10_Advanced.md | 38 | ||||
| -rw-r--r-- | doc/manual/11_Scripting.md | 42 | ||||
| -rw-r--r-- | doc/manual/12_Compiling.md | 67 | ||||
| -rw-r--r-- | doc/manual/13_Help.md | 10 | ||||
| -rw-r--r-- | doc/manual/14_Appendix.md | 421 | ||||
| -rw-r--r-- | doc/manual/1_Introduction.md | 38 | ||||
| -rw-r--r-- | doc/manual/2_Installation.md | 73 | ||||
| -rw-r--r-- | doc/manual/3_UserInterface.md | 6 | ||||
| -rw-r--r-- | doc/manual/4_WorkingWithFiles.md | 7 | ||||
| -rw-r--r-- | doc/manual/5_FileNavigation.md | 2 | ||||
| -rw-r--r-- | doc/manual/6_AdeptEditing.md | 79 | ||||
| -rw-r--r-- | doc/manual/7_Modules.md | 106 | ||||
| -rw-r--r-- | doc/manual/8_Themes.md | 37 | ||||
| -rw-r--r-- | doc/manual/9_Preferences.md | 36 |
14 files changed, 708 insertions, 254 deletions
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 |