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