From 1ef52910df3a560d24a1d92e6fe7621a751d6859 Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Thu, 8 Mar 2012 13:44:53 -0500 Subject: Moved Manual into `doc/` root directory. --- doc/01_Introduction.md | 63 +++ doc/02_Installation.md | 119 +++++ doc/03_UserInterface.md | 37 ++ doc/04_WorkingWithFiles.md | 69 +++ doc/05_FileNavigation.md | 25 + doc/06_AdeptEditing.md | 183 +++++++ doc/07_Modules.md | 158 ++++++ doc/08_Themes.md | 88 ++++ doc/09_Preferences.md | 143 ++++++ doc/10_Advanced.md | 84 ++++ doc/11_Scripting.md | 81 ++++ doc/12_Compiling.md | 109 +++++ doc/13_Help.md | 15 + doc/14_Appendix.md | 686 +++++++++++++++++++++++++++ doc/gen_manual.lua | 18 +- doc/header.md | 1 - doc/images/adeptsense_doc.png | Bin 0 -> 26369 bytes doc/images/adeptsense_lua.png | Bin 0 -> 17967 bytes doc/images/adeptsense_string.png | Bin 0 -> 18926 bytes doc/images/adeptsense_ta.png | Bin 0 -> 38941 bytes doc/images/adeptsense_tadoc.png | Bin 0 -> 65107 bytes doc/images/bufferbrowser.png | Bin 0 -> 72930 bytes doc/images/bufferbrowserfiltered.png | Bin 0 -> 39274 bytes doc/images/commandentry.png | Bin 0 -> 6480 bytes doc/images/commandentrycompletion.png | Bin 0 -> 4578 bytes doc/images/darktheme.png | Bin 0 -> 39619 bytes doc/images/docstatusbar.png | Bin 0 -> 2679 bytes doc/images/findinfiles.png | Bin 0 -> 94166 bytes doc/images/icon.png | Bin 0 -> 2548 bytes doc/images/lighttheme.png | Bin 0 -> 46721 bytes doc/images/linux.png | Bin 0 -> 12554 bytes doc/images/macosx.png | Bin 0 -> 14091 bytes doc/images/matchingbrace.png | Bin 0 -> 6107 bytes doc/images/rectangularselection.png | Bin 0 -> 1928 bytes doc/images/rectangularselection2.png | Bin 0 -> 2094 bytes doc/images/snapopen.png | Bin 0 -> 72278 bytes doc/images/snippet.png | Bin 0 -> 951 bytes doc/images/snippet2.png | Bin 0 -> 5192 bytes doc/images/splitviews.png | Bin 0 -> 136537 bytes doc/images/textadept.png | Bin 0 -> 27344 bytes doc/images/ui.png | Bin 0 -> 109804 bytes doc/images/win32.png | Bin 0 -> 7923 bytes doc/images/wordcompletion.png | Bin 0 -> 3490 bytes doc/images/wordhighlight.png | Bin 0 -> 69127 bytes doc/manual/01_Introduction.md | 63 --- doc/manual/02_Installation.md | 119 ----- doc/manual/03_UserInterface.md | 37 -- doc/manual/04_WorkingWithFiles.md | 69 --- doc/manual/05_FileNavigation.md | 25 - doc/manual/06_AdeptEditing.md | 183 ------- doc/manual/07_Modules.md | 158 ------ doc/manual/08_Themes.md | 88 ---- doc/manual/09_Preferences.md | 143 ------ doc/manual/10_Advanced.md | 84 ---- doc/manual/11_Scripting.md | 81 ---- doc/manual/12_Compiling.md | 109 ----- doc/manual/13_Help.md | 15 - doc/manual/14_Appendix.md | 686 --------------------------- doc/manual/images/adeptsense_doc.png | Bin 26369 -> 0 bytes doc/manual/images/adeptsense_lua.png | Bin 17967 -> 0 bytes doc/manual/images/adeptsense_string.png | Bin 18926 -> 0 bytes doc/manual/images/adeptsense_ta.png | Bin 38941 -> 0 bytes doc/manual/images/adeptsense_tadoc.png | Bin 65107 -> 0 bytes doc/manual/images/bufferbrowser.png | Bin 72930 -> 0 bytes doc/manual/images/bufferbrowserfiltered.png | Bin 39274 -> 0 bytes doc/manual/images/commandentry.png | Bin 6480 -> 0 bytes doc/manual/images/commandentrycompletion.png | Bin 4578 -> 0 bytes doc/manual/images/darktheme.png | Bin 39619 -> 0 bytes doc/manual/images/docstatusbar.png | Bin 2679 -> 0 bytes doc/manual/images/findinfiles.png | Bin 94166 -> 0 bytes doc/manual/images/icon.png | Bin 2548 -> 0 bytes doc/manual/images/lighttheme.png | Bin 46721 -> 0 bytes doc/manual/images/linux.png | Bin 12554 -> 0 bytes doc/manual/images/macosx.png | Bin 14091 -> 0 bytes doc/manual/images/matchingbrace.png | Bin 6107 -> 0 bytes doc/manual/images/rectangularselection.png | Bin 1928 -> 0 bytes doc/manual/images/rectangularselection2.png | Bin 2094 -> 0 bytes doc/manual/images/snapopen.png | Bin 72278 -> 0 bytes doc/manual/images/snippet.png | Bin 951 -> 0 bytes doc/manual/images/snippet2.png | Bin 5192 -> 0 bytes doc/manual/images/splitviews.png | Bin 136537 -> 0 bytes doc/manual/images/textadept.png | Bin 27344 -> 0 bytes doc/manual/images/ui.png | Bin 109804 -> 0 bytes doc/manual/images/win32.png | Bin 7923 -> 0 bytes doc/manual/images/wordcompletion.png | Bin 3490 -> 0 bytes doc/manual/images/wordhighlight.png | Bin 69127 -> 0 bytes 86 files changed, 1869 insertions(+), 1870 deletions(-) create mode 100644 doc/01_Introduction.md create mode 100644 doc/02_Installation.md create mode 100644 doc/03_UserInterface.md create mode 100644 doc/04_WorkingWithFiles.md create mode 100644 doc/05_FileNavigation.md create mode 100644 doc/06_AdeptEditing.md create mode 100644 doc/07_Modules.md create mode 100644 doc/08_Themes.md create mode 100644 doc/09_Preferences.md create mode 100644 doc/10_Advanced.md create mode 100644 doc/11_Scripting.md create mode 100644 doc/12_Compiling.md create mode 100644 doc/13_Help.md create mode 100644 doc/14_Appendix.md create mode 100644 doc/images/adeptsense_doc.png create mode 100644 doc/images/adeptsense_lua.png create mode 100644 doc/images/adeptsense_string.png create mode 100644 doc/images/adeptsense_ta.png create mode 100644 doc/images/adeptsense_tadoc.png create mode 100644 doc/images/bufferbrowser.png create mode 100644 doc/images/bufferbrowserfiltered.png create mode 100644 doc/images/commandentry.png create mode 100644 doc/images/commandentrycompletion.png create mode 100644 doc/images/darktheme.png create mode 100644 doc/images/docstatusbar.png create mode 100644 doc/images/findinfiles.png create mode 100644 doc/images/icon.png create mode 100644 doc/images/lighttheme.png create mode 100644 doc/images/linux.png create mode 100644 doc/images/macosx.png create mode 100644 doc/images/matchingbrace.png create mode 100644 doc/images/rectangularselection.png create mode 100644 doc/images/rectangularselection2.png create mode 100644 doc/images/snapopen.png create mode 100644 doc/images/snippet.png create mode 100644 doc/images/snippet2.png create mode 100644 doc/images/splitviews.png create mode 100644 doc/images/textadept.png create mode 100644 doc/images/ui.png create mode 100644 doc/images/win32.png create mode 100644 doc/images/wordcompletion.png create mode 100644 doc/images/wordhighlight.png delete mode 100644 doc/manual/01_Introduction.md delete mode 100644 doc/manual/02_Installation.md delete mode 100644 doc/manual/03_UserInterface.md delete mode 100644 doc/manual/04_WorkingWithFiles.md delete mode 100644 doc/manual/05_FileNavigation.md delete mode 100644 doc/manual/06_AdeptEditing.md delete mode 100644 doc/manual/07_Modules.md delete mode 100644 doc/manual/08_Themes.md delete mode 100644 doc/manual/09_Preferences.md delete mode 100644 doc/manual/10_Advanced.md delete mode 100644 doc/manual/11_Scripting.md delete mode 100644 doc/manual/12_Compiling.md delete mode 100644 doc/manual/13_Help.md delete mode 100644 doc/manual/14_Appendix.md delete mode 100644 doc/manual/images/adeptsense_doc.png delete mode 100644 doc/manual/images/adeptsense_lua.png delete mode 100644 doc/manual/images/adeptsense_string.png delete mode 100644 doc/manual/images/adeptsense_ta.png delete mode 100644 doc/manual/images/adeptsense_tadoc.png delete mode 100644 doc/manual/images/bufferbrowser.png delete mode 100644 doc/manual/images/bufferbrowserfiltered.png delete mode 100644 doc/manual/images/commandentry.png delete mode 100644 doc/manual/images/commandentrycompletion.png delete mode 100644 doc/manual/images/darktheme.png delete mode 100644 doc/manual/images/docstatusbar.png delete mode 100644 doc/manual/images/findinfiles.png delete mode 100644 doc/manual/images/icon.png delete mode 100644 doc/manual/images/lighttheme.png delete mode 100644 doc/manual/images/linux.png delete mode 100644 doc/manual/images/macosx.png delete mode 100644 doc/manual/images/matchingbrace.png delete mode 100644 doc/manual/images/rectangularselection.png delete mode 100644 doc/manual/images/rectangularselection2.png delete mode 100644 doc/manual/images/snapopen.png delete mode 100644 doc/manual/images/snippet.png delete mode 100644 doc/manual/images/snippet2.png delete mode 100644 doc/manual/images/splitviews.png delete mode 100644 doc/manual/images/textadept.png delete mode 100644 doc/manual/images/ui.png delete mode 100644 doc/manual/images/win32.png delete mode 100644 doc/manual/images/wordcompletion.png delete mode 100644 doc/manual/images/wordhighlight.png (limited to 'doc') diff --git a/doc/01_Introduction.md b/doc/01_Introduction.md new file mode 100644 index 00000000..0bdf97e2 --- /dev/null +++ b/doc/01_Introduction.md @@ -0,0 +1,63 @@ +# Introduction + +## Overview + +![Textadept](images/textadept.png) + +Textadept is a fast, minimalist, and ridiculously extensible cross-platform text +editor for programmers. Written in a combination of C and [Lua][] and +relentlessly optimized for speed and minimalism over the years, Textadept is an +ideal editor for programmers who want endless extensibility options without +sacrificing speed or succumbing to code bloat and featuritis. + +[Lua]: http://lua.org + +### 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][], Textadept is faster +than ever before, though using LuaJIT is overkill. + +[LuaJIT]: http://luajit.org + +### 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 +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 + +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, +from syntax highlighting to opening and saving files to searching and replacing +and more. Textadept gives you complete control over the entire application using +Lua. 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. + +![Split Views](images/splitviews.png) + +## Manual Notation + +* `~/` is denoted as the user's home directory. On Windows machines this is the + value of the `USERHOME` environment variable (typically `C:\Users\\` + or `C:\Documents and Settings\\`). On Linux and Mac OSX machines it + is the value of `HOME` (typically `/home//` and `/Users//` + respectively). +* Any relative directory paths, i.e. paths that do not begin with `/` or `C:\`, + are relative to the location of Textadept. +* Key combinations are not case-sensitive. `Ctrl+N` means the `N` key is pressed + with only the `Control` key being held down, not the `Shift` key. + `Ctrl+Shift+N` means the `N` key is pressed with both `Control` and `Shift` + keys being held down. The same notation is applicable to key chains: + `Ctrl+N, N` vs. `Ctrl+N, Shift+N`. In the first key chain, `Control` and `N` + are pressed followed by `N` with no modifiers. The second has `Control` and + `N` pressed followed by `Shift` and `N`. +* When mentioning key commands, the Mac OSX equivalent will often be shown in + parenthesis. It may be tempting to assume that some Windows/Linux keys map to + 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. diff --git a/doc/02_Installation.md b/doc/02_Installation.md new file mode 100644 index 00000000..ffc8b938 --- /dev/null +++ b/doc/02_Installation.md @@ -0,0 +1,119 @@ +# Installation + +## Requirements + +In its bid for minimalism, Textadept also needs very little to run. In fact, the +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. + +[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][]. + +[GTK+ website]: http://www.gtk.org/download-linux.html + +### Mac OSX + +No requirements other than Mac OSX 10.5 (Leopard) or higher with an Intel CPU. + +### Windows + +No requirements. + +## Download + +Download Textadept from the [project 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. + +[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 + +Unpack the archive anywhere. Run Textadept by running +`/path/to/textadept_VERSION/textadept` from the terminal. You can also create a +symlink to the executable in your `PATH` (e.g. `/usr/bin`) or make a GNOME, KDE, +XFCE, etc. button or menu launcher. + +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 + +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 +distribution. Because the Linux version of Textadept uses the version of GTK +installed on your system, an error like: `error while loading shared libraries: +: cannot open shared object file: No such file or directory` may occur when +trying to run the program. + +The most common occurance of this error is for the `libpng12` library on 64-bit +(x86\_64) Debian and Debian-based Linux distributions like Ubuntu because +`libpng12` has not been replaced in favor of the newer `libpng14`. If you are +experiencing this error, simply rename `textadept.lpng12` to `textadept`. The +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][] page for more information. + +[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 +double-clicking `textadept.app`. + +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 + +By default, GUI apps like Textadept do not utilize environment variables such as +`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 +toolbar, Desktop, etc. + +If you downloaded the set of language-specific modules, unpack it where you +unpacked the Textadept archive. The modules will be contained in +`textadept_VERSION\modules\`. + +![Linux](images/linux.png) +   +![Mac OSX](images/macosx.png) +   +![Win32](images/win32.png) diff --git a/doc/03_UserInterface.md b/doc/03_UserInterface.md new file mode 100644 index 00000000..bda4d1fe --- /dev/null +++ b/doc/03_UserInterface.md @@ -0,0 +1,37 @@ +# User Interface + +![UI](images/ui.png) + +Textadept's user interface was designed to be simple. It consists of a menubar, +editor view, initially hidden find/replace dialog, initially hidden command +entry, and statusbar. Below are brief descriptions of these features. More +in-depth discussion about some of them is provided later in the manual. + +## Menubar + +The completely customizable (and optional!) menubar provides access to all of +Textadept's features. + +## Editor View + +The editor view is where you will spend most of your time in Textadept. It +supports unlimited split views and is completely controllable by Lua. + +## Find and Replace Dialog + +This compact dialog is a great way to slice and dice through your document or +directory of files. You can even find and replace text using Lua patterns. It is +available when you need it and quickly gets out of your way when you do not, +minimizing distractions. + +## Command Entry + +The versatile command entry functions as both a place to execute Lua commands +with the internal Lua state and find text incrementally. You can extend it to do +even more if you would like. Like the find/replace dialog, the command entry +pops in and out as you wish. + +## Statusbar + +The left side of the statusbar displays any status messages. The right side +shows the current buffer's status. diff --git a/doc/04_WorkingWithFiles.md b/doc/04_WorkingWithFiles.md new file mode 100644 index 00000000..e5c30d8e --- /dev/null +++ b/doc/04_WorkingWithFiles.md @@ -0,0 +1,69 @@ +# Working with Files + +## Lack of Tabs + +One of the first things you will notice when opening multiple files in Textadept +is that there is no tab bar showing the files that are open. This was a design +decision. Textadept was built to support unlimited split views, so having a tab +bar with all open buffers would clutter the interface greatly. There is also the +question of where to place the bar (above, below, or to one side) and how many +to have (one for each split view or a single one under the menubar). + +You can see which buffer is active by looking at Textadept's titlebar. Pressing +`Ctrl+Tab` (`^⇥` on Mac OSX) cycles to the next buffer and `Ctrl+Shift+Tab` +(`^⇧⇥`) cycles to the previous one. + +## Buffer Browser + +To move quickly between buffers, press `Ctrl+B` (`⌘B` on Mac OSX) to open the +buffer browser. + +![Buffer Browser](images/bufferbrowser.png) + +The buffer browser shows you a list of currently open buffers, the most recent +towards the bottom. Typing part of any filename filters the list. Spaces are +wildcards. You can also just use the arrow keys. Pressing `Enter` or clicking +`OK` switches to the selected buffer. + +![Buffer Browser Filtered](images/bufferbrowserfiltered.png) + +## Split Views + +Textadept allows you to split the editor window as many times as you like either +horizontally or vertically. `Ctrl+Alt+S` or `Ctrl+Alt+H` splits horizontally +(top-bottom) and `Ctrl+Alt+V` splits vertically (`^S` and `^V` respectively on +Mac OSX). You can resize the splitter bar by clicking and dragging with the +mouse or using `Ctrl+Alt++` and `Ctrl+Alt+-` (`^+` and `^-`). The same file can +be worked with in multiple split views. + +Pressing `Ctrl+Alt+N` (`^⌥⇥` on Mac OSX) goes to the next view and `Ctrl+Alt+P` +(`^⌥⇧⇥`) goes to the previous one. + +To unsplit a view, enter the view to keep open and press `Ctrl+Alt+W` (`^W` on +Mac OSX). To unsplit all views, use `Ctrl+Alt+Shift+W` (`^⇧W`). + +## Sessions + +By default, Textadept saves the list of open buffers on exit so it can reload +them the next time it starts up. You can disable this by passing the `-n` or +`--no-session` switch to Textadept on startup. Sessions can be manually saved +and opened via the `File -> Save Session...` and `File -> Load Session...` +menus. + +Sessions save additional information such as current split views, caret and +scroll positions in each buffer, Textadept's window size, and recently opened +files. + +## Snapopen + +A quicker, though slightly more limited alternative to the standard +`File -> Open` dialog is snapopen. It behaves like the buffer browser, but +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][]. +`Ctrl+U` (`⌘U`) snaps open `~/.textadept/`. + +[LuaDoc]: api/_M.textadept.snapopen.html + +![Snapopen](images/snapopen.png) diff --git a/doc/05_FileNavigation.md b/doc/05_FileNavigation.md new file mode 100644 index 00000000..953464a7 --- /dev/null +++ b/doc/05_FileNavigation.md @@ -0,0 +1,25 @@ +# File Navigation + +## Bookmarks + +You can place bookmarks on lines in buffers to jump back to them later. Use the +`Tools -> Bookmark` menu options or key commands to do so. + +## Goto Line + +To jump to a specific line in a file, press `Ctrl+J` (`⌘J` on Mac OSX) and +specify the line number in the prompt and press `Enter` (`↩`) or click `OK`. + +## Goto Matching Brace + +By default, Textadept will highlight the matching brace characters under the +caret : `(`, `)`, `[`, `]`, `{`, `}`, `<`, and `>`. Pressing `Ctrl+M` (`^M` on +Mac OSX) moves the caret to that matching brace and `Ctrl+Shift+M` (`^⇧M`) +extends the selection. + +![Matching Braces](images/matchingbrace.png) + +## Mac OSX + +Textadept supports the keybindings you are accustomed to for navigating text +fields in Mac OSX. diff --git a/doc/06_AdeptEditing.md b/doc/06_AdeptEditing.md new file mode 100644 index 00000000..30deac58 --- /dev/null +++ b/doc/06_AdeptEditing.md @@ -0,0 +1,183 @@ +# Adept Editing + +## Key Commands + +Textadept is entirely keyboard-driven. See the comprehensive list of key +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][] page if you would like +to disable this. + +[preferences]: 9_Preferences.html#Module.Settings + +## Word Completion + +Textadept provides buffer-based word completion. Start typing a word, press +`Ctrl+Return` (`^⎋` on Mac OSX), and a list of suggested completions based on +words in the current document is provided. Continuing to type changes the +suggestion. Press `Return` (`↩`) to complete the selected word. + +![Word Completion](images/wordcompletion.png) + +## Adeptsense + +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][]. Symbol completion +is available by pressing `Ctrl+Space` (`⌥⎋` on Mac OSX). Documentation for +symbols is available with `Ctrl+H` (`^H`). + +![Adeptsense Lua](images/adeptsense_lua.png) +     +![Adeptsense Lua String](images/adeptsense_string.png) + +![Adeptsense Doc](images/adeptsense_doc.png) + +For more information on adding adeptsense support for another language, see +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][] 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` +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. + +[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 +a search result jumps to it in the file. You can also use the `Ctrl+Alt+G` and +`Ctrl+Alt+Shift+G` (`^⌘G` and `^⌘⇧G` on Mac OSX) key commands. Replace in Files +is not supported. You will have to `Find in Files` first, and then `Replace All` +for each file a result is found in. The `Match Case`, `Whole Word`, and +`Lua pattern` flags still apply. + +![Find in Files](images/findinfiles.png) + +### 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. Pressing `Esc` (`⎋`) stops it. + +### 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 +then `Replace All`. + +## Indentation + +### 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 + +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. + +![Document Statusbar](images/docstatusbar.png) + +[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][] or the +[theme][]. + +[language-specific module]: 7_Modules.html#Buffer.Properties +[theme]: 8_Themes.html#Buffer + +### 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, +all tabs are converted to spaces. + +## Selecting Text + +### 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. + +![Rectangular Selection](images/rectangularselection.png) +     +![Rectangular Edit](images/rectangularselection2.png) + +### 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` +creates multiple selections. Start typing to enter text at each selection. + +This is currently unavailable on Mac OSX. + +### 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. +Typing `Ctrl++` (`^+`) as a follow-up selects the double-quotes too. See the +`Edit -> Select In...` menu for available entities and their key commands. + +## Enclosing Text + +As a complement to selecting entities, you can enclose text as entities. The +`Edit -> Selection -> Enclose In...` menu contains all available entities and +their key commands. + +If no text is selected, the word to the left of the caret is enclosed. + +## Word Highlight + +All occurrences of a given word are highlighted by putting the caret over the +word and pressing `Ctrl+Alt+Shift+H` (`⌘⇧H` on Mac OSX). This is useful to show +occurrences of a variable name in source code. + +![Word Highlight](images/wordhighlight.png) + +## Editing Modes + +### 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 mode is enabled and disabled with the `Insert` key. When enabled, +characters in the buffer will be overwritten instead of inserted as you type. +The caret also changes to an underline when in overwrite mode. diff --git a/doc/07_Modules.md b/doc/07_Modules.md new file mode 100644 index 00000000..6a9f334b --- /dev/null +++ b/doc/07_Modules.md @@ -0,0 +1,158 @@ +# Modules + +Most of Textadept's functionality comes from modules written in Lua. A module +consists of a single directory with an `init.lua` script to load any additional +Lua files (typically in the same location). Essentially there are two classes of +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 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][] 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 + +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. + +[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 + +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). + +![Snippet](images/snippet.png) +     +![Snippet Expanded](images/snippet2.png) + +[snippets]: api/_M.textadept.snippets.html + +### Commands + +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. + +[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 + +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 + +Pressing `Ctrl+/` (`⌘/` on Mac OSX) comments or uncomments the code on the +selected lines. + +### 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. + +### 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 [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][]. + +[here]: http://foicica.com/hg +[Mercurial]: http://mercurial.selenic.com +[wiki]: http://caladbolg.net/textadeptwiki + +## Installing Modules + +It is recommended to put all custom or user-created modules in your +`~/.textadept/modules/` directory so they will not be overwritten when you +update Textadept. Also, modules in that directory override any modules in +Textadept's `modules/` directory. This means that if you have your own `lua` +module, it will be loaded instead of the one that comes with Textadept. + +## Developing Modules + +See the [LuaDoc][] for modules. + +[LuaDoc]: api/_M.html + +## Customizing Modules + +It is never recommended to modify the default modules that come with Textadept, +even if you just want to change the buffer settings for a language-specific +module or add a few more snippets. Instead you have two options: load your own +module instead of the default one or load your custom module code after the +default module loads. To load your own module, simply place it appropriately in +`~/.textadept/modules/`. To load your module code after the default module +loads, create a `post_init.lua` Lua script in the appropriate +`~/.textadept/modules/` sub-folder. Please note that for generic modules, only +the first option applies. Either option applies for language-specific modules. + +Suppose you wanted to completely change the menubar structure. You would first +create a new `menu.lua` and then put it in `~/.textadept/modules/textadept/`. +Now when Textadept looks for `menu.lua`, it will load yours instead of its own. +Similarly, if you copy the default Lua language-specific module (`modules/lua`) +to `~/.textadept/modules/` and make custom changes, that module is loaded for +editing Lua code instead of the default module. + +If you keep a modified copy of language-specific modules, you will likely want +to update them with each new Textadept release. Instead of potentially wasting +time merging your changes, you can load custom code independent of the module in +a `post_init.lua` file. For example, instead of copying the `lua` module and +changing its `set_buffer_properties()` function to use tabs, you can do this +from `post_init.lua`: + + function _M.lua.set_buffer_properties() + buffer.use_tabs = true + end + +Similarly, you can use `post_init.lua` to change the compile/run commands, load +more [Adeptsense tags][], and add additional key commands and snippets. + +[Adeptsense tags]: api/_M.textadept.adeptsense.html#load_ctags diff --git a/doc/08_Themes.md b/doc/08_Themes.md new file mode 100644 index 00000000..488c7b0a --- /dev/null +++ b/doc/08_Themes.md @@ -0,0 +1,88 @@ +# Themes + +Textadept's look and feel can be customized with themes. The themes that come +with Textadept are `light` and `dark`'. By default the `light` theme is used. To +change the theme, create a `~/.textadept/theme` file whose first line of text is +the name of the theme you would like to use. + +![Light Theme](images/lighttheme.png) +     +![Dark Theme](images/darktheme.png) + +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]. + +[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 +your `~/.textadept/themes/` directory so they will not be overwritten when you +update Textadept. Themes in that directory override any themes in Textadept's +`themes/` directory. This means that if you have your own `light` theme, it will +be loaded instead of the one that comes with Textadept. + +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 + +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][] page for more information on how to create styles and colors. + +[lexer]: api/lexer.html + +### 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 +use tabs: + + buffer.tab_width = 4 + buffer.use_tabs = true + buffer.indent = 4 + +See the [LuaDoc][] for documentation on the properties. + +[LuaDoc]: api/buffer.html + +### View + +`view.lua` contains view-specific properties like caret and selection colors. +See the [LuaDoc][] for documentation on the properties. + +[LuaDoc]: api/buffer.html + +## Testing Themes + +You can reload or switch between themes on the fly using `Ctrl+Shift+T` (⌘⇧T on +Mac OSX), but be aware that the Scintilla views do not reset themselves, so any +options set explicitly in the previous theme's `view.lua` file that are not set +explicitly in the new theme will carry over. The switch feature is intended +primarily for theme exploration and/or development and can be slow when many +buffers or views are open. + +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][]. 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" + +[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][]. 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/09_Preferences.md b/doc/09_Preferences.md new file mode 100644 index 00000000..8832c698 --- /dev/null +++ b/doc/09_Preferences.md @@ -0,0 +1,143 @@ +# Preferences + +At this point it is assumed you are at least familiar with the basics of +[Lua][]. You do not have to know a lot of the language to configure Textadept. + +[Lua]: http://www.lua.org + +## User Init + +Textadept loads modules from your `~/.textadept/init.lua` on startup. If this +file does not exist, Textadept creates it with a list of default modules to +load. You can then use the file to indicate what else you want Textadept to +load. For example if you created a generic module called `foo` that you wanted +to load alongside the default modules, your `~/.textadept/init.lua` would +contain + + require 'textadept' + _M.foo = require 'foo' + +Please note that the `textadept` module populates the `_M.textadept` table +itself because of internal dependencies. Normally, modules do not do this, hence +why `_M.foo = require 'foo'` is used. + +If instead you wanted to load all of Textadept's default modules except for the +menu, copy the `textadept` module's `init.lua` (located in the +`modules/textadept/` directory) to `~/.textadept/modules/textadept/` and change + + M.menu = require 'textadept.menu' + +to + + --M.menu = require 'textadept.menu' + +Of course if you prefer, you can put the relevant code directly in +`~/.textadept/init.lua` instead. + +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 + +Many of Textadept's modules have settings you can change from your +`~/.textadept/init.lua`. These settings are viewed from module's +[LuaDoc][]. For example, to disable character autopairing and +whitespace stripping on save, your `~/.textadept/init.lua` might look like: + + require 'textadept' + + _M.textadept.editing.AUTOPAIR = false + _M.textadept.editing.STRIP_WHITESPACE_ON_SAVE = false + +[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][] page. + +[scripting]: 11_Scripting.html + +#### Snippets + +You can add global snippets to `snippets` such as: + + snippets['file'] = '%' + snippets['path'] = "%<(buffer.filename or ''):match('^.+[/\\]')>" + +So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX) will insert +the snippet. + +#### 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 +Textadept. Instead, modify `keys` from within your `~/.textadept/init.lua` or +from a file loaded by `~/.textadept/init.lua`. For example maybe you want +`Ctrl+Shift+C` to create a new buffer instead of `Ctrl+N`: + + keys.cC = new_buffer + keys.cn = nil + +## Locale + +Most messages displayed by Textadept are localized. `core/locale.conf` contains +these messages. By default, Textadept is localized in English. To use a +different language, put a translated version of `core/locale.conf` in your +`~/.textadept/` folder. Translations are located in `core/locales/`. + +Feel free to translate Textadept and send your modified `locale.conf` files +to me. I will include them in future releases. + +## Mime Types + +Textadept recognizes a wide range of programming language files by any of the +following: + +* File extension. +* Keywords in the file's shebang (`#!/path/to/exe`) line. +* A pattern that matches the text of the file's first line. + +Built-in mime-types are located in `modules/textadept/mime_types.conf`. You +can override or add to them in your `~/.textadept/mime_types.conf`: + + % Recognize .luadoc files as Lua code. + luadoc lua + + % Change .html files to be recognized as XML files instead of HTML ones. + html xml + +It is not recommended to edit Textadept's `modules/textadept/mime_types.conf` +because your changes may be overwritten when updating Textadept. + +### Detect by File Extension + + file_ext lexer + +Note: `file_ext` should not start with a `.` (period). + +### Detect by Shebang Keywords + + #shebang_word lexer + +Examples of `shebang_word`'s are `lua`, `ruby`, `python`. + +### 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. + +## 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][] +* [Block Quotes][] + +[Run/Compile commands]: http://caladbolg.net/textadeptwiki/index.php?n=Main.RunSupplemental +[Block Quotes]: http://caladbolg.net/textadeptwiki/index.php?n=Main.CommentSupplemental diff --git a/doc/10_Advanced.md b/doc/10_Advanced.md new file mode 100644 index 00000000..21cb29ae --- /dev/null +++ b/doc/10_Advanced.md @@ -0,0 +1,84 @@ +# Advanced + +## Command Entry + +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][] 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()`][]. Use `_G.print()` for Lua's `print()`. + +![Command Entry](images/commandentry.png) + +[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 +to make a selection and press `Enter` (`↩`) to insert it. + +![Command Completion](images/commandentrycompletion.png) + +### Extending + +You can extend the command entry to do more than enter Lua commands. An +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][], 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 + +Sometimes it is easier to use an existing shell command to manipulate text +instead of using the command entry. An example would be sorting all text in a +buffer (or a selection). You could do the following from the command entry: + + ls={}; for l in buffer:get_text():gmatch('[^\n]+') do ls[#ls+1]=l end; + table.sort(ls); buffer:set_text(table.concat(ls, '\n')) + +A simpler way would be to press `Ctrl+|` (`⌘|` on Mac OSX), enter the shell +command `sort`, and hit `Enter` (`↩`). + +The standard input (stdin) for shell commands is determined as follows: + +* If text is selected and spans multiple lines, all text on the lines containing + the selection is used. However, if the end of the selection is at the + beginning of a line, only the EOL (end of line) characters from the previous + line are included as input. The rest of the line is excluded. +* If text is selected and spans a single line, only the selected text is used. +* If no text is selected, the entire buffer is used. + +The input text is replaced with the standard output (stdout) of the command. + +## File Encoding + +Textadept represents all characters and strings internally as UTF-8. You will +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`][]. + +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/11_Scripting.md b/doc/11_Scripting.md new file mode 100644 index 00000000..86eb1a5a --- /dev/null +++ b/doc/11_Scripting.md @@ -0,0 +1,81 @@ +# Scripting + +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][] for more information. + +![Adeptsense ta](images/adeptsense_ta.png) +     +![Adeptsense tadoc](images/adeptsense_tadoc.png) + +[`lua` module documentation]: api/_M.lua.html + +## LuaDoc and Examples + +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][] 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`. +* `LUA_ROOT` is `/usr/` in Linux systems instead of `/usr/local/`. +* All compatibility flags for Lua 5.1 are turned off. (`LUA_COMPAT_UNPACK`, + `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][]. 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. + +[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 + +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 + +Lexer Lua modules are responsible for the syntax highlighting of source code. +They are located in `lexers/`. + +### 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 + +Built-in themes to customize the look and behavior of Textadept are located in +`themes/`. + +### User + +User Lua modules are contained in the `~/.textadept/` folder. This folder may +contain `lexers/`, `modules/`, and `themes/` subdirectories. + +### 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/12_Compiling.md b/doc/12_Compiling.md new file mode 100644 index 00000000..aa7b2303 --- /dev/null +++ b/doc/12_Compiling.md @@ -0,0 +1,109 @@ +# Compiling + +## Requirements + +Unfortunately, the requirements for building Textadept are not quite as minimal +as running it. + +### 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][]. 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. + +[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][] (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][] 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 + +[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 + +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 +`/usr/bin/` or elsewhere in your `PATH`. + +BSD users please run `make BSD=1`. + +### 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 + +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 +this point it is recommended to build a new `textadept.app` from an existing +one. Download the most recent app and replace `Contents/MacOS/textadept.osx`, +all `.dylib` files in `Contents/Resources/lib`, and all `.so` files in +`Contents/Resources/lib/gtk-2.0//{engines,immodules,loaders}` with your +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 + +If the build fails because of a + + `redefinition of 'struct Sci_TextRange'` + +error, open `src/scintilla/include/Scintilla.h` and comment out the following +lines (put `//` at the start of the line): + + #define CharacterRange Sci_CharacterRange + #define TextRange Sci_TextRange + #define TextToFind Sci_TextToFind + +### Compiling with LuaJIT + +[LuaJIT][] is a Just-In-Time Compiler for Lua and can boost the speed of Lua +programs. I have noticed that syntax highlighting can be up to 2 times faster +with LuaJIT than with vanilla Lua. This difference is largely unnoticable on +modern computers and usually only discernable when initially loading large +files. Other than syntax highlighting, LuaJIT offers no real benefit +performance-wise to justify it being Textadept's default runtime. LuaJIT's +[ffi library][], however, appears to be useful for interfacing with external, +non-Lua, libraries. + +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 +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/13_Help.md b/doc/13_Help.md new file mode 100644 index 00000000..800a18cb --- /dev/null +++ b/doc/13_Help.md @@ -0,0 +1,15 @@ +# Help + +## Command Line Parameters + +Passing `-h` or `--help` to Textadept shows a list of available command line +parameters. + +## Online Help + +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/14_Appendix.md b/doc/14_Appendix.md new file mode 100644 index 00000000..61ad842d --- /dev/null +++ b/doc/14_Appendix.md @@ -0,0 +1,686 @@ +# Appendix + +## Key Bindings + +Linux / Win32 | Mac OSX | Command | +--------------|---------|---------| +**File** ||| +Ctrl+N |⌘N |New file +Ctrl+O |⌘O |Open file +Ctrl+Alt+O |^⌘O |Open recent file... +Ctrl+Shift+O|⌘⇧O |Reload file +Ctrl+S |⌘S |Save file +Ctrl+Shift+S|⌘⇧S |Save file as.. +Ctrl+W |⌘W |Close file +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 +Ctrl+X
Shift+Del |⌘X
⇧⌦|Cut +Ctrl+C
Ctrl+Ins |⌘C |Copy +Ctrl+V
Shift+Ins |⌘V |Paste +Ctrl+D |⌘D |Duplicate line +Del |⌦
^D |Delete +Alt+Del |^⌦ |Delete word +Ctrl+A |⌘A |Select all +Ctrl+M |^M |Match brace +Ctrl+Enter |^⎋ |Complete word +Ctrl+Alt+Shift+H |⌘⇧H |Highlight word +Ctrl+/ |^/ |Toggle block comment +Ctrl+T |^T |Transpose characters +Ctrl+Shift+J |^J |Join lines +Ctrl+Shift+M |^⇧M |Select to matching brace +Ctrl+< |⌘< |Select between XML tags +Ctrl+> |⌘> |Select in XML tag +Ctrl+" |⌘" |Select in double quotes +Ctrl+' |⌘' |Select in single quotes +Ctrl+( |⌘( |Select in parentheses +Ctrl+[ |⌘[ |Select in brackets +Ctrl+{ |⌘{ |Select in braces +Ctrl+Shift+D |⌘⇧D |Select word +Ctrl+Shift+N |⌘⇧N |Select line +Ctrl+Shift+P |⌘⇧P |Select paragraph +Ctrl+Shift+I |⌘⇧I |Select indented block +Ctrl+Alt+U |^U |Upper case selection +Ctrl+Alt+Shift+U |^⇧U |Lower case selection +Alt+< |^< |Enclose as XML tags +Alt+> |^> |Enclose as single XML tag +Alt+" |^" |Enclose in double quotes +Alt+' |^' |Enclose in single quotes +Alt+( |^( |Enclose in parentheses +Alt+[ |^[ |Enclose in brackets +Alt+{ |^{ |Enclose in braces +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 +Ctrl+Shift+G
Shift+F3|⌘⇧G |Find previous +Ctrl+Alt+R |^R |Replace +Ctrl+Alt+Shift+R |^⇧R |Replace all +Ctrl+Alt+F |^⌘F |Find incremental +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 +Ctrl+R |⌘R |Run +Ctrl+Shift+R |⌘⇧R |Compile +Ctrl+| |⌘||Filter text through +Ctrl+Space |⌥⎋ |Complete symbol +Ctrl+H |^H |Show documentation +Tab |⇥ |Expand snippet or next placeholder +Ctrl+K |⌥⇥ |Insert snippet... +Shift+Tab |⇧⇥ |Previous snippet placeholder +Ctrl+Shift+K |⌥⇧⇥ |Cancel snippet +Ctrl+F2 |⌘F2 |Toggle bookmark +Ctrl+Shift+F2 |⌘⇧F2 |Clear bookmarks +F2 |F2 |Next bookark +Shift+F2 |⇧F2 |Previous bookmark +Alt+F2 |⌥F2 |Goto bookmark... +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 +Ctrl+B |⌘B |Switch to buffer... +None |None |Tab width: 2 +None |None |Tab width: 3 +None |None |Tab width: 4 +None |None |Tab width: 8 +Ctrl+Alt+Shift+T|^⇧T |Toggle use tabs +Ctrl+Alt+I |^I |Convert indentation +None |None |`CRLF` EOL mode +None |None |`CR` EOL mode +None |None |`LF` EOL mode +None |None |`UTF-8` encoding +None |None |`ASCII` encoding +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 +Ctrl+Alt+S
Ctrl+Alt+H|^S |Split view horizontal +Ctrl+Alt+V |^V |Split view vertical +Ctrl+Alt+W |^W |Unsplit view +Ctrl+Alt+Shift+W |^⇧W |Unsplit all views +Ctrl+Alt++
Ctrl+Alt+=|^+
^=|Grow view +Ctrl+Alt+- |^- |Shrink view +None |None |Toggle current fold +Ctrl+Alt+Enter |^↩ |Toggle view EOL +Ctrl+Alt+\\ |^\\ |Toggle wrap mode +Ctrl+Alt+Shift+I |^⇧I |Toggle show indent guides +Ctrl+Alt+Shift+S |^⇧S |Toggle view whitespace +Ctrl+Alt+Shift+V |^⇧V |Toggle virtual space +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 +Ctrl+Down |^⇣ |Scroll line down +Alt+Shift+Down |⌥⇧⇣ |Line down extend rect. selection +Up |⇡
^P |Line up +Shift+Up |⇧⇡
^⇧P |Line up extend selection +Ctrl+Up |^⇡ |Scroll line up +Alt+Shift+Up |⌥⇧⇡ |Line up extend rect. selection +Left |⇠
^B |Char left +Shift+Left |⇧⇠
^⇧B |Char left extend selection +Ctrl+Left |^⇠
^⌘B |Word left +Ctrl+Shift+Left |^⇧⇠
^⌘⇧B|Word left extend selection +Alt+Shift+Left |⌥⇧⇠ |Char left extend rect. selection +Right |⇢
^F |Char right +Shift+Right |⇧⇢
^⇧F |Char right extend selection +Ctrl+Right |^⇢
^⌘F |Word right +Ctrl+Shift+Right |^⇧⇢
^⌘⇧F|Word right extend selection +Alt+Shift+Right |⌥⇧⇢ |Char right extend rect. selection +Home |⌘⇠
^A |Line start +Shift+Home |⌘⇧⇠
^⇧A |Line start extend selection +Ctrl+Home |⌘⇡
⌘↖ |Document start +Ctrl+Shift+Home |⌘⇧⇡
⌘⇧↖ |Document start extend selection +Alt+Shift+Home |⌥⇧↖ |Line start extend rect. selection +End |⌘⇢
^E |Line end +Shift+End |⌘⇧⇢
^⇧E |Line end extend selection +Ctrl+End |⌘⇣
⌘↘ |Document end +Ctrl+Shift+End |⌘⇧⇣
⌘⇧↘ |Document end extend selection +Alt+Shift+End |⌥⇧↘ |Line end extend rect. selection +PageUp |⇞ |Page up +Shift+PageUp |⇧⇞ |Page up extend selection +Alt+Shift+PageUp |⌥⇧⇞ |Page up extend rect. selection +PageDown |⇟ |Page down +Shift+PageDown |⇧⇟ |Page down extend selection +Alt+Shift+PageDown |⌥⇧⇟ |Page down extend rect. selection +Ctrl+Del |⌘⌦ |Delete word right +Ctrl+Shift+Del |⌘⇧⌦ |Delete line right +Ins |Ins |Toggle overtype +Backspace
Shift+Backspace|⌫
⇧⌫ |Delete back +Ctrl+Backspace |⌘⌫ |Delete word left +Ctrl+Shift+Backspace |⌘⇧⌫ |Delete line left +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][]. + +_Character Class:_ + +A character class is used to represent a set of characters. The following +combinations are allowed in describing a character class: + +* **_`x`_:** (where _x_ is not one of the magic characters `^$()%.[]*+-?`) + represents the character _x_ itself. +* **`.`:** (a dot) represents all characters. +* **`%a`:** represents all letters. +* **`%c`:** represents all control characters. +* **`%d`:** represents all digits. +* **`%g`:** represents all printable characters except space. +* **`%l`:** represents all lowercase letters. +* **`%p`:** represents all punctuation characters. +* **`%s`:** represents all space characters. +* **`%u`:** represents all uppercase letters. +* **`%w`:** represents all alphanumeric characters. +* **`%x`:** represents all hexadecimal digits. +* **`%`_`x`_:** (where _x_ is any non-alphanumeric character) represents the + character _x_. This is the standard way to escape the magic characters. Any + punctuation character (even the non magic) can be preceded by a '`%`' when + used to represent itself in a pattern. +* **`[set]`:** represents the class which is the union of all characters in set. + A range of characters can be specified by separating the end characters of the + range with a '`-`'. All classes `%`_x_ described above can also be used as + components in set. All other characters in set represent themselves. For + example, `[%w_]` (or `[_%w]`) represents all alphanumeric characters plus the + underscore, `[0-7]` represents the octal digits, and `[0-7%l%-]` represents + the octal digits plus the lowercase letters plus the '`-`' character. +

+ The interaction between ranges and classes is not defined. Therefore, patterns + like `[%a-z]` or `[a-%%]` have no meaning. +* **`[^set]`:** represents the complement of _set_, where _set_ is interpreted + as above. + +For all classes represented by single letters (`%a`, `%c`, etc.), the +corresponding uppercase letter represents the complement of the class. For +instance, `%S` represents all non-space characters. + +The definitions of letter, space, and other character groups depend on the +current locale. In particular, the class `[a-z]` may not be equivalent to `%l`. + +_Pattern Item:_ + +A _pattern item_ can be + +* a single character class, which matches any single character in the class; +* a single character class followed by '`*`', which matches 0 or more + repetitions of characters in the class. These repetition items will always + match the longest possible sequence; +* a single character class followed by '`+`', which matches 1 or more + repetitions of characters in the class. These repetition items will always + match the longest possible sequence; +* a single character class followed by '`-`', which also matches 0 or more + repetitions of characters in the class. Unlike '`*`', these repetition items + will always match the _shortest_ possible sequence; +* a single character class followed by '`?`', which matches 0 or 1 occurrence of + a character in the class; +* `%n`, for _n_ between 1 and 9; such item matches a substring equal to the + _n_-th captured string (see below); +* `%bxy`, where _x_ and _y_ are two distinct characters; such item matches + strings that start with _x_, end with _y_, and where the _x_ and _y_ are + balanced. This means that, if one reads the string from left to right, + counting +_1_ for an _x_ and -_1_ for a _y_, the ending _y_ is the first _y_ + where the count reaches 0. For instance, the item `%b()` matches expressions + with balanced parentheses. +* `%f[set]`, a _frontier pattern_; such item matches an empty string at any + position such that the next character belongs to _set_ and the previous + character does not belong to _set_. The set _set_ is interpreted as previously + described. The beginning and the end of the subject are handled as if they + were the character `'\0'`. + +_Pattern:_ + +A _pattern_ is a sequence of pattern items. A '`^`' at the beginning of a +pattern anchors the match at the beginning of the subject string. A '`$`' at the +end of a pattern anchors the match at the end of the subject string. At other +positions, '`^`' and '`$`' have no special meaning and represent themselves. + +_Captures:_ + +A pattern can contain sub-patterns enclosed in parentheses; they describe +_captures_. When a match succeeds, the substrings of the subject string that +match captures are stored (_captured_) for future use. Captures are numbered +according to their left parentheses. For instance, in the pattern +`"(a*(.)%w(%s*))"`, the part of the string matching `"a*(.)%w(%s*)"` is stored +as the first capture (and therefore has number 1); the character matching "`.`" +is captured with number 2, and the part matching "`%s*`" has number 3. + +As a special case, the empty capture `()` captures the current string position +(a number). For instance, if we apply the pattern `"()aa()"` on the string +`"flaaap"`, there will be two captures: 3 and 5. + +[Lua 5.2 Reference Manual]: http://www.lua.org/manual/5.2/manual.html#6.4.1 + +## 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/gen_manual.lua b/doc/gen_manual.lua index fcdf0b14..47c1bb8c 100644 --- a/doc/gen_manual.lua +++ b/doc/gen_manual.lua @@ -5,7 +5,7 @@ local HTML = [[ %(title) - + @@ -36,13 +36,13 @@ local template = {} -- Get manual pages. local pages = {} local lfs = require 'lfs' -for file in lfs.dir('manual/') do +for file in lfs.dir('.') do if file:find('^%d+_.-%.md$') then pages[#pages + 1] = file end end table.sort(pages) -pages[#pages + 1] = '../../README.md' -pages[#pages + 1] = '../../CHANGELOG.md' -pages[#pages + 1] = '../../THANKS.md' +pages[#pages + 1] = '../README.md' +pages[#pages + 1] = '../CHANGELOG.md' +pages[#pages + 1] = '../THANKS.md' -- Create the header and footer. local p = io.popen('markdown header.md') @@ -53,7 +53,7 @@ template.footer = p:read('*all') p:close() -- Create the navigation list. -local navfile = 'manual/.nav.md' +local navfile = '.nav.md' local f = io.open(navfile, 'wb') for _, page in ipairs(pages) do local name = page:match('^%A+(.-)%.md$'):gsub('(%l)(%u)', '%1 %2') @@ -61,7 +61,7 @@ for _, page in ipairs(pages) do f:write('* [', name, '](', page:gsub('%.md$', '.html'), ')\n') end f:close() -p = io.popen('markdown "'..navfile..'"') +p = io.popen('markdown '..navfile) template.nav = p:read('*all') p:close() @@ -69,11 +69,11 @@ p:close() for _, page in ipairs(pages) do local name = page:match('^%A+(.-)%.md$'):gsub('(%l)(%u)', '%1 %2') template.title = name..' - Textadept Manual' - p = io.popen('markdown -f toc -T "manual/'..page..'"') + p = io.popen('markdown -f toc -T '..page) template.toc, template.main = p:read('*all'):match('^(.-\n\n)(.+)$') p:close() if page:find('^%.%./') then page = page:match('^%A+(.+)$') end - f = io.open('manual/'..page:gsub('%.md$', '.html'), 'wb') + f = io.open(page:gsub('%.md$', '.html'), 'wb') local html = HTML:gsub('%%%(([^)]+)%)', template) f:write(html) f:close() diff --git a/doc/header.md b/doc/header.md index 3ff4f97b..84995ac0 100644 --- a/doc/header.md +++ b/doc/header.md @@ -2,7 +2,6 @@ * [Home](http://foicica.com/textadept) | * [Download](http://foicica.com/textadept/download) | -* [Manual](http://foicica.com/textadept/manual) | * [Lua API](http://foicica.com/textadept/api) | * [Source](http://foicica.com/hg/textadept) | * [Language Modules](http://foicica.com/hg) | diff --git a/doc/images/adeptsense_doc.png b/doc/images/adeptsense_doc.png new file mode 100644 index 00000000..36356591 Binary files /dev/null and b/doc/images/adeptsense_doc.png differ diff --git a/doc/images/adeptsense_lua.png b/doc/images/adeptsense_lua.png new file mode 100644 index 00000000..75e581f2 Binary files /dev/null and b/doc/images/adeptsense_lua.png differ diff --git a/doc/images/adeptsense_string.png b/doc/images/adeptsense_string.png new file mode 100644 index 00000000..ed5f4244 Binary files /dev/null and b/doc/images/adeptsense_string.png differ diff --git a/doc/images/adeptsense_ta.png b/doc/images/adeptsense_ta.png new file mode 100644 index 00000000..e280fc72 Binary files /dev/null and b/doc/images/adeptsense_ta.png differ diff --git a/doc/images/adeptsense_tadoc.png b/doc/images/adeptsense_tadoc.png new file mode 100644 index 00000000..8ccd325e Binary files /dev/null and b/doc/images/adeptsense_tadoc.png differ diff --git a/doc/images/bufferbrowser.png b/doc/images/bufferbrowser.png new file mode 100644 index 00000000..de7defe1 Binary files /dev/null and b/doc/images/bufferbrowser.png differ diff --git a/doc/images/bufferbrowserfiltered.png b/doc/images/bufferbrowserfiltered.png new file mode 100644 index 00000000..c4c01486 Binary files /dev/null and b/doc/images/bufferbrowserfiltered.png differ diff --git a/doc/images/commandentry.png b/doc/images/commandentry.png new file mode 100644 index 00000000..cbcd66a7 Binary files /dev/null and b/doc/images/commandentry.png differ diff --git a/doc/images/commandentrycompletion.png b/doc/images/commandentrycompletion.png new file mode 100644 index 00000000..a4b83059 Binary files /dev/null and b/doc/images/commandentrycompletion.png differ diff --git a/doc/images/darktheme.png b/doc/images/darktheme.png new file mode 100644 index 00000000..0c683dc7 Binary files /dev/null and b/doc/images/darktheme.png differ diff --git a/doc/images/docstatusbar.png b/doc/images/docstatusbar.png new file mode 100644 index 00000000..5e709ab2 Binary files /dev/null and b/doc/images/docstatusbar.png differ diff --git a/doc/images/findinfiles.png b/doc/images/findinfiles.png new file mode 100644 index 00000000..2f8783aa Binary files /dev/null and b/doc/images/findinfiles.png differ diff --git a/doc/images/icon.png b/doc/images/icon.png new file mode 100644 index 00000000..c9457dfe Binary files /dev/null and b/doc/images/icon.png differ diff --git a/doc/images/lighttheme.png b/doc/images/lighttheme.png new file mode 100644 index 00000000..e5100912 Binary files /dev/null and b/doc/images/lighttheme.png differ diff --git a/doc/images/linux.png b/doc/images/linux.png new file mode 100644 index 00000000..a8640022 Binary files /dev/null and b/doc/images/linux.png differ diff --git a/doc/images/macosx.png b/doc/images/macosx.png new file mode 100644 index 00000000..2035a95b Binary files /dev/null and b/doc/images/macosx.png differ diff --git a/doc/images/matchingbrace.png b/doc/images/matchingbrace.png new file mode 100644 index 00000000..22a99c19 Binary files /dev/null and b/doc/images/matchingbrace.png differ diff --git a/doc/images/rectangularselection.png b/doc/images/rectangularselection.png new file mode 100644 index 00000000..3fe77a6a Binary files /dev/null and b/doc/images/rectangularselection.png differ diff --git a/doc/images/rectangularselection2.png b/doc/images/rectangularselection2.png new file mode 100644 index 00000000..a4a84f61 Binary files /dev/null and b/doc/images/rectangularselection2.png differ diff --git a/doc/images/snapopen.png b/doc/images/snapopen.png new file mode 100644 index 00000000..8ae1bb74 Binary files /dev/null and b/doc/images/snapopen.png differ diff --git a/doc/images/snippet.png b/doc/images/snippet.png new file mode 100644 index 00000000..d73c621a Binary files /dev/null and b/doc/images/snippet.png differ diff --git a/doc/images/snippet2.png b/doc/images/snippet2.png new file mode 100644 index 00000000..cbafb98c Binary files /dev/null and b/doc/images/snippet2.png differ diff --git a/doc/images/splitviews.png b/doc/images/splitviews.png new file mode 100644 index 00000000..bdb516ec Binary files /dev/null and b/doc/images/splitviews.png differ diff --git a/doc/images/textadept.png b/doc/images/textadept.png new file mode 100644 index 00000000..8731e5cc Binary files /dev/null and b/doc/images/textadept.png differ diff --git a/doc/images/ui.png b/doc/images/ui.png new file mode 100644 index 00000000..e9c97f4c Binary files /dev/null and b/doc/images/ui.png differ diff --git a/doc/images/win32.png b/doc/images/win32.png new file mode 100644 index 00000000..996c2b5f Binary files /dev/null and b/doc/images/win32.png differ diff --git a/doc/images/wordcompletion.png b/doc/images/wordcompletion.png new file mode 100644 index 00000000..e55280a9 Binary files /dev/null and b/doc/images/wordcompletion.png differ diff --git a/doc/images/wordhighlight.png b/doc/images/wordhighlight.png new file mode 100644 index 00000000..61c8832b Binary files /dev/null and b/doc/images/wordhighlight.png differ diff --git a/doc/manual/01_Introduction.md b/doc/manual/01_Introduction.md deleted file mode 100644 index 0bdf97e2..00000000 --- a/doc/manual/01_Introduction.md +++ /dev/null @@ -1,63 +0,0 @@ -# Introduction - -## Overview - -![Textadept](images/textadept.png) - -Textadept is a fast, minimalist, and ridiculously extensible cross-platform text -editor for programmers. Written in a combination of C and [Lua][] and -relentlessly optimized for speed and minimalism over the years, Textadept is an -ideal editor for programmers who want endless extensibility options without -sacrificing speed or succumbing to code bloat and featuritis. - -[Lua]: http://lua.org - -### 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][], Textadept is faster -than ever before, though using LuaJIT is overkill. - -[LuaJIT]: http://luajit.org - -### 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 -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 - -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, -from syntax highlighting to opening and saving files to searching and replacing -and more. Textadept gives you complete control over the entire application using -Lua. 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. - -![Split Views](images/splitviews.png) - -## Manual Notation - -* `~/` is denoted as the user's home directory. On Windows machines this is the - value of the `USERHOME` environment variable (typically `C:\Users\\` - or `C:\Documents and Settings\\`). On Linux and Mac OSX machines it - is the value of `HOME` (typically `/home//` and `/Users//` - respectively). -* Any relative directory paths, i.e. paths that do not begin with `/` or `C:\`, - are relative to the location of Textadept. -* Key combinations are not case-sensitive. `Ctrl+N` means the `N` key is pressed - with only the `Control` key being held down, not the `Shift` key. - `Ctrl+Shift+N` means the `N` key is pressed with both `Control` and `Shift` - keys being held down. The same notation is applicable to key chains: - `Ctrl+N, N` vs. `Ctrl+N, Shift+N`. In the first key chain, `Control` and `N` - are pressed followed by `N` with no modifiers. The second has `Control` and - `N` pressed followed by `Shift` and `N`. -* When mentioning key commands, the Mac OSX equivalent will often be shown in - parenthesis. It may be tempting to assume that some Windows/Linux keys map to - 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. diff --git a/doc/manual/02_Installation.md b/doc/manual/02_Installation.md deleted file mode 100644 index ffc8b938..00000000 --- a/doc/manual/02_Installation.md +++ /dev/null @@ -1,119 +0,0 @@ -# Installation - -## Requirements - -In its bid for minimalism, Textadept also needs very little to run. In fact, the -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. - -[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][]. - -[GTK+ website]: http://www.gtk.org/download-linux.html - -### Mac OSX - -No requirements other than Mac OSX 10.5 (Leopard) or higher with an Intel CPU. - -### Windows - -No requirements. - -## Download - -Download Textadept from the [project 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. - -[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 - -Unpack the archive anywhere. Run Textadept by running -`/path/to/textadept_VERSION/textadept` from the terminal. You can also create a -symlink to the executable in your `PATH` (e.g. `/usr/bin`) or make a GNOME, KDE, -XFCE, etc. button or menu launcher. - -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 - -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 -distribution. Because the Linux version of Textadept uses the version of GTK -installed on your system, an error like: `error while loading shared libraries: -: cannot open shared object file: No such file or directory` may occur when -trying to run the program. - -The most common occurance of this error is for the `libpng12` library on 64-bit -(x86\_64) Debian and Debian-based Linux distributions like Ubuntu because -`libpng12` has not been replaced in favor of the newer `libpng14`. If you are -experiencing this error, simply rename `textadept.lpng12` to `textadept`. The -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][] page for more information. - -[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 -double-clicking `textadept.app`. - -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 - -By default, GUI apps like Textadept do not utilize environment variables such as -`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 -toolbar, Desktop, etc. - -If you downloaded the set of language-specific modules, unpack it where you -unpacked the Textadept archive. The modules will be contained in -`textadept_VERSION\modules\`. - -![Linux](images/linux.png) -   -![Mac OSX](images/macosx.png) -   -![Win32](images/win32.png) diff --git a/doc/manual/03_UserInterface.md b/doc/manual/03_UserInterface.md deleted file mode 100644 index bda4d1fe..00000000 --- a/doc/manual/03_UserInterface.md +++ /dev/null @@ -1,37 +0,0 @@ -# User Interface - -![UI](images/ui.png) - -Textadept's user interface was designed to be simple. It consists of a menubar, -editor view, initially hidden find/replace dialog, initially hidden command -entry, and statusbar. Below are brief descriptions of these features. More -in-depth discussion about some of them is provided later in the manual. - -## Menubar - -The completely customizable (and optional!) menubar provides access to all of -Textadept's features. - -## Editor View - -The editor view is where you will spend most of your time in Textadept. It -supports unlimited split views and is completely controllable by Lua. - -## Find and Replace Dialog - -This compact dialog is a great way to slice and dice through your document or -directory of files. You can even find and replace text using Lua patterns. It is -available when you need it and quickly gets out of your way when you do not, -minimizing distractions. - -## Command Entry - -The versatile command entry functions as both a place to execute Lua commands -with the internal Lua state and find text incrementally. You can extend it to do -even more if you would like. Like the find/replace dialog, the command entry -pops in and out as you wish. - -## Statusbar - -The left side of the statusbar displays any status messages. The right side -shows the current buffer's status. diff --git a/doc/manual/04_WorkingWithFiles.md b/doc/manual/04_WorkingWithFiles.md deleted file mode 100644 index 201e46cf..00000000 --- a/doc/manual/04_WorkingWithFiles.md +++ /dev/null @@ -1,69 +0,0 @@ -# Working with Files - -## Lack of Tabs - -One of the first things you will notice when opening multiple files in Textadept -is that there is no tab bar showing the files that are open. This was a design -decision. Textadept was built to support unlimited split views, so having a tab -bar with all open buffers would clutter the interface greatly. There is also the -question of where to place the bar (above, below, or to one side) and how many -to have (one for each split view or a single one under the menubar). - -You can see which buffer is active by looking at Textadept's titlebar. Pressing -`Ctrl+Tab` (`^⇥` on Mac OSX) cycles to the next buffer and `Ctrl+Shift+Tab` -(`^⇧⇥`) cycles to the previous one. - -## Buffer Browser - -To move quickly between buffers, press `Ctrl+B` (`⌘B` on Mac OSX) to open the -buffer browser. - -![Buffer Browser](images/bufferbrowser.png) - -The buffer browser shows you a list of currently open buffers, the most recent -towards the bottom. Typing part of any filename filters the list. Spaces are -wildcards. You can also just use the arrow keys. Pressing `Enter` or clicking -`OK` switches to the selected buffer. - -![Buffer Browser Filtered](images/bufferbrowserfiltered.png) - -## Split Views - -Textadept allows you to split the editor window as many times as you like either -horizontally or vertically. `Ctrl+Alt+S` or `Ctrl+Alt+H` splits horizontally -(top-bottom) and `Ctrl+Alt+V` splits vertically (`^S` and `^V` respectively on -Mac OSX). You can resize the splitter bar by clicking and dragging with the -mouse or using `Ctrl+Alt++` and `Ctrl+Alt+-` (`^+` and `^-`). The same file can -be worked with in multiple split views. - -Pressing `Ctrl+Alt+N` (`^⌥⇥` on Mac OSX) goes to the next view and `Ctrl+Alt+P` -(`^⌥⇧⇥`) goes to the previous one. - -To unsplit a view, enter the view to keep open and press `Ctrl+Alt+W` (`^W` on -Mac OSX). To unsplit all views, use `Ctrl+Alt+Shift+W` (`^⇧W`). - -## Sessions - -By default, Textadept saves the list of open buffers on exit so it can reload -them the next time it starts up. You can disable this by passing the `-n` or -`--no-session` switch to Textadept on startup. Sessions can be manually saved -and opened via the `File -> Save Session...` and `File -> Load Session...` -menus. - -Sessions save additional information such as current split views, caret and -scroll positions in each buffer, Textadept's window size, and recently opened -files. - -## Snapopen - -A quicker, though slightly more limited alternative to the standard -`File -> Open` dialog is snapopen. It behaves like the buffer browser, but -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][]. -`Ctrl+U` (`⌘U`) snaps open `~/.textadept/`. - -[LuaDoc]: ../api/_M.textadept.snapopen.html - -![Snapopen](images/snapopen.png) diff --git a/doc/manual/05_FileNavigation.md b/doc/manual/05_FileNavigation.md deleted file mode 100644 index 953464a7..00000000 --- a/doc/manual/05_FileNavigation.md +++ /dev/null @@ -1,25 +0,0 @@ -# File Navigation - -## Bookmarks - -You can place bookmarks on lines in buffers to jump back to them later. Use the -`Tools -> Bookmark` menu options or key commands to do so. - -## Goto Line - -To jump to a specific line in a file, press `Ctrl+J` (`⌘J` on Mac OSX) and -specify the line number in the prompt and press `Enter` (`↩`) or click `OK`. - -## Goto Matching Brace - -By default, Textadept will highlight the matching brace characters under the -caret : `(`, `)`, `[`, `]`, `{`, `}`, `<`, and `>`. Pressing `Ctrl+M` (`^M` on -Mac OSX) moves the caret to that matching brace and `Ctrl+Shift+M` (`^⇧M`) -extends the selection. - -![Matching Braces](images/matchingbrace.png) - -## Mac OSX - -Textadept supports the keybindings you are accustomed to for navigating text -fields in Mac OSX. diff --git a/doc/manual/06_AdeptEditing.md b/doc/manual/06_AdeptEditing.md deleted file mode 100644 index 9dee1183..00000000 --- a/doc/manual/06_AdeptEditing.md +++ /dev/null @@ -1,183 +0,0 @@ -# Adept Editing - -## Key Commands - -Textadept is entirely keyboard-driven. See the comprehensive list of key -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][] page if you would like -to disable this. - -[preferences]: 9_Preferences.html#Module.Settings - -## Word Completion - -Textadept provides buffer-based word completion. Start typing a word, press -`Ctrl+Return` (`^⎋` on Mac OSX), and a list of suggested completions based on -words in the current document is provided. Continuing to type changes the -suggestion. Press `Return` (`↩`) to complete the selected word. - -![Word Completion](images/wordcompletion.png) - -## Adeptsense - -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][]. Symbol completion -is available by pressing `Ctrl+Space` (`⌥⎋` on Mac OSX). Documentation for -symbols is available with `Ctrl+H` (`^H`). - -![Adeptsense Lua](images/adeptsense_lua.png) -     -![Adeptsense Lua String](images/adeptsense_string.png) - -![Adeptsense Doc](images/adeptsense_doc.png) - -For more information on adding adeptsense support for another language, see -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][] 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` -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. - -[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 -a search result jumps to it in the file. You can also use the `Ctrl+Alt+G` and -`Ctrl+Alt+Shift+G` (`^⌘G` and `^⌘⇧G` on Mac OSX) key commands. Replace in Files -is not supported. You will have to `Find in Files` first, and then `Replace All` -for each file a result is found in. The `Match Case`, `Whole Word`, and -`Lua pattern` flags still apply. - -![Find in Files](images/findinfiles.png) - -### 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. Pressing `Esc` (`⎋`) stops it. - -### 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 -then `Replace All`. - -## Indentation - -### 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 - -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. - -![Document Statusbar](images/docstatusbar.png) - -[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][] or the -[theme][]. - -[language-specific module]: 7_Modules.html#Buffer.Properties -[theme]: 8_Themes.html#Buffer - -### 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, -all tabs are converted to spaces. - -## Selecting Text - -### 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. - -![Rectangular Selection](images/rectangularselection.png) -     -![Rectangular Edit](images/rectangularselection2.png) - -### 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` -creates multiple selections. Start typing to enter text at each selection. - -This is currently unavailable on Mac OSX. - -### 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. -Typing `Ctrl++` (`^+`) as a follow-up selects the double-quotes too. See the -`Edit -> Select In...` menu for available entities and their key commands. - -## Enclosing Text - -As a complement to selecting entities, you can enclose text as entities. The -`Edit -> Selection -> Enclose In...` menu contains all available entities and -their key commands. - -If no text is selected, the word to the left of the caret is enclosed. - -## Word Highlight - -All occurrences of a given word are highlighted by putting the caret over the -word and pressing `Ctrl+Alt+Shift+H` (`⌘⇧H` on Mac OSX). This is useful to show -occurrences of a variable name in source code. - -![Word Highlight](images/wordhighlight.png) - -## Editing Modes - -### 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 mode is enabled and disabled with the `Insert` key. When enabled, -characters in the buffer will be overwritten instead of inserted as you type. -The caret also changes to an underline when in overwrite mode. diff --git a/doc/manual/07_Modules.md b/doc/manual/07_Modules.md deleted file mode 100644 index 1b915c85..00000000 --- a/doc/manual/07_Modules.md +++ /dev/null @@ -1,158 +0,0 @@ -# Modules - -Most of Textadept's functionality comes from modules written in Lua. A module -consists of a single directory with an `init.lua` script to load any additional -Lua files (typically in the same location). Essentially there are two classes of -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 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][] 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 - -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. - -[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 - -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). - -![Snippet](images/snippet.png) -     -![Snippet Expanded](images/snippet2.png) - -[snippets]: ../api/_M.textadept.snippets.html - -### Commands - -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. - -[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 - -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 - -Pressing `Ctrl+/` (`⌘/` on Mac OSX) comments or uncomments the code on the -selected lines. - -### 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. - -### 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 [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][]. - -[here]: http://foicica.com/hg -[Mercurial]: http://mercurial.selenic.com -[wiki]: http://caladbolg.net/textadeptwiki - -## Installing Modules - -It is recommended to put all custom or user-created modules in your -`~/.textadept/modules/` directory so they will not be overwritten when you -update Textadept. Also, modules in that directory override any modules in -Textadept's `modules/` directory. This means that if you have your own `lua` -module, it will be loaded instead of the one that comes with Textadept. - -## Developing Modules - -See the [LuaDoc][] for modules. - -[LuaDoc]: ../api/_M.html - -## Customizing Modules - -It is never recommended to modify the default modules that come with Textadept, -even if you just want to change the buffer settings for a language-specific -module or add a few more snippets. Instead you have two options: load your own -module instead of the default one or load your custom module code after the -default module loads. To load your own module, simply place it appropriately in -`~/.textadept/modules/`. To load your module code after the default module -loads, create a `post_init.lua` Lua script in the appropriate -`~/.textadept/modules/` sub-folder. Please note that for generic modules, only -the first option applies. Either option applies for language-specific modules. - -Suppose you wanted to completely change the menubar structure. You would first -create a new `menu.lua` and then put it in `~/.textadept/modules/textadept/`. -Now when Textadept looks for `menu.lua`, it will load yours instead of its own. -Similarly, if you copy the default Lua language-specific module (`modules/lua`) -to `~/.textadept/modules/` and make custom changes, that module is loaded for -editing Lua code instead of the default module. - -If you keep a modified copy of language-specific modules, you will likely want -to update them with each new Textadept release. Instead of potentially wasting -time merging your changes, you can load custom code independent of the module in -a `post_init.lua` file. For example, instead of copying the `lua` module and -changing its `set_buffer_properties()` function to use tabs, you can do this -from `post_init.lua`: - - function _M.lua.set_buffer_properties() - buffer.use_tabs = true - end - -Similarly, you can use `post_init.lua` to change the compile/run commands, load -more [Adeptsense tags][], and add additional key commands and snippets. - -[Adeptsense tags]: ../api/_M.textadept.adeptsense.html#load_ctags diff --git a/doc/manual/08_Themes.md b/doc/manual/08_Themes.md deleted file mode 100644 index b40135e2..00000000 --- a/doc/manual/08_Themes.md +++ /dev/null @@ -1,88 +0,0 @@ -# Themes - -Textadept's look and feel can be customized with themes. The themes that come -with Textadept are `light` and `dark`'. By default the `light` theme is used. To -change the theme, create a `~/.textadept/theme` file whose first line of text is -the name of the theme you would like to use. - -![Light Theme](images/lighttheme.png) -     -![Dark Theme](images/darktheme.png) - -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]. - -[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 -your `~/.textadept/themes/` directory so they will not be overwritten when you -update Textadept. Themes in that directory override any themes in Textadept's -`themes/` directory. This means that if you have your own `light` theme, it will -be loaded instead of the one that comes with Textadept. - -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 - -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][] page for more information on how to create styles and colors. - -[lexer]: ../api/lexer.html - -### 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 -use tabs: - - buffer.tab_width = 4 - buffer.use_tabs = true - buffer.indent = 4 - -See the [LuaDoc][] for documentation on the properties. - -[LuaDoc]: ../api/buffer.html - -### View - -`view.lua` contains view-specific properties like caret and selection colors. -See the [LuaDoc][] for documentation on the properties. - -[LuaDoc]: ../api/buffer.html - -## Testing Themes - -You can reload or switch between themes on the fly using `Ctrl+Shift+T` (⌘⇧T on -Mac OSX), but be aware that the Scintilla views do not reset themselves, so any -options set explicitly in the previous theme's `view.lua` file that are not set -explicitly in the new theme will carry over. The switch feature is intended -primarily for theme exploration and/or development and can be slow when many -buffers or views are open. - -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][]. 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" - -[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][]. 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/09_Preferences.md b/doc/manual/09_Preferences.md deleted file mode 100644 index abceaa97..00000000 --- a/doc/manual/09_Preferences.md +++ /dev/null @@ -1,143 +0,0 @@ -# Preferences - -At this point it is assumed you are at least familiar with the basics of -[Lua][]. You do not have to know a lot of the language to configure Textadept. - -[Lua]: http://www.lua.org - -## User Init - -Textadept loads modules from your `~/.textadept/init.lua` on startup. If this -file does not exist, Textadept creates it with a list of default modules to -load. You can then use the file to indicate what else you want Textadept to -load. For example if you created a generic module called `foo` that you wanted -to load alongside the default modules, your `~/.textadept/init.lua` would -contain - - require 'textadept' - _M.foo = require 'foo' - -Please note that the `textadept` module populates the `_M.textadept` table -itself because of internal dependencies. Normally, modules do not do this, hence -why `_M.foo = require 'foo'` is used. - -If instead you wanted to load all of Textadept's default modules except for the -menu, copy the `textadept` module's `init.lua` (located in the -`modules/textadept/` directory) to `~/.textadept/modules/textadept/` and change - - M.menu = require 'textadept.menu' - -to - - --M.menu = require 'textadept.menu' - -Of course if you prefer, you can put the relevant code directly in -`~/.textadept/init.lua` instead. - -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 - -Many of Textadept's modules have settings you can change from your -`~/.textadept/init.lua`. These settings are viewed from module's -[LuaDoc][]. For example, to disable character autopairing and -whitespace stripping on save, your `~/.textadept/init.lua` might look like: - - require 'textadept' - - _M.textadept.editing.AUTOPAIR = false - _M.textadept.editing.STRIP_WHITESPACE_ON_SAVE = false - -[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][] page. - -[scripting]: 11_Scripting.html - -#### Snippets - -You can add global snippets to `snippets` such as: - - snippets['file'] = '%' - snippets['path'] = "%<(buffer.filename or ''):match('^.+[/\\]')>" - -So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX) will insert -the snippet. - -#### 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 -Textadept. Instead, modify `keys` from within your `~/.textadept/init.lua` or -from a file loaded by `~/.textadept/init.lua`. For example maybe you want -`Ctrl+Shift+C` to create a new buffer instead of `Ctrl+N`: - - keys.cC = new_buffer - keys.cn = nil - -## Locale - -Most messages displayed by Textadept are localized. `core/locale.conf` contains -these messages. By default, Textadept is localized in English. To use a -different language, put a translated version of `core/locale.conf` in your -`~/.textadept/` folder. Translations are located in `core/locales/`. - -Feel free to translate Textadept and send your modified `locale.conf` files -to me. I will include them in future releases. - -## Mime Types - -Textadept recognizes a wide range of programming language files by any of the -following: - -* File extension. -* Keywords in the file's shebang (`#!/path/to/exe`) line. -* A pattern that matches the text of the file's first line. - -Built-in mime-types are located in `modules/textadept/mime_types.conf`. You -can override or add to them in your `~/.textadept/mime_types.conf`: - - % Recognize .luadoc files as Lua code. - luadoc lua - - % Change .html files to be recognized as XML files instead of HTML ones. - html xml - -It is not recommended to edit Textadept's `modules/textadept/mime_types.conf` -because your changes may be overwritten when updating Textadept. - -### Detect by File Extension - - file_ext lexer - -Note: `file_ext` should not start with a `.` (period). - -### Detect by Shebang Keywords - - #shebang_word lexer - -Examples of `shebang_word`'s are `lua`, `ruby`, `python`. - -### 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. - -## 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][] -* [Block Quotes][] - -[Run/Compile commands]: http://caladbolg.net/textadeptwiki/index.php?n=Main.RunSupplemental -[Block Quotes]: http://caladbolg.net/textadeptwiki/index.php?n=Main.CommentSupplemental diff --git a/doc/manual/10_Advanced.md b/doc/manual/10_Advanced.md deleted file mode 100644 index d81687aa..00000000 --- a/doc/manual/10_Advanced.md +++ /dev/null @@ -1,84 +0,0 @@ -# Advanced - -## Command Entry - -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][] 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()`][]. Use `_G.print()` for Lua's `print()`. - -![Command Entry](images/commandentry.png) - -[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 -to make a selection and press `Enter` (`↩`) to insert it. - -![Command Completion](images/commandentrycompletion.png) - -### Extending - -You can extend the command entry to do more than enter Lua commands. An -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][], 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 - -Sometimes it is easier to use an existing shell command to manipulate text -instead of using the command entry. An example would be sorting all text in a -buffer (or a selection). You could do the following from the command entry: - - ls={}; for l in buffer:get_text():gmatch('[^\n]+') do ls[#ls+1]=l end; - table.sort(ls); buffer:set_text(table.concat(ls, '\n')) - -A simpler way would be to press `Ctrl+|` (`⌘|` on Mac OSX), enter the shell -command `sort`, and hit `Enter` (`↩`). - -The standard input (stdin) for shell commands is determined as follows: - -* If text is selected and spans multiple lines, all text on the lines containing - the selection is used. However, if the end of the selection is at the - beginning of a line, only the EOL (end of line) characters from the previous - line are included as input. The rest of the line is excluded. -* If text is selected and spans a single line, only the selected text is used. -* If no text is selected, the entire buffer is used. - -The input text is replaced with the standard output (stdout) of the command. - -## File Encoding - -Textadept represents all characters and strings internally as UTF-8. You will -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`][]. - -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 deleted file mode 100644 index 463d01bc..00000000 --- a/doc/manual/11_Scripting.md +++ /dev/null @@ -1,81 +0,0 @@ -# Scripting - -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][] for more information. - -![Adeptsense ta](images/adeptsense_ta.png) -     -![Adeptsense tadoc](images/adeptsense_tadoc.png) - -[`lua` module documentation]: ../api/_M.lua.html - -## LuaDoc and Examples - -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][] 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`. -* `LUA_ROOT` is `/usr/` in Linux systems instead of `/usr/local/`. -* All compatibility flags for Lua 5.1 are turned off. (`LUA_COMPAT_UNPACK`, - `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][]. 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. - -[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 - -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 - -Lexer Lua modules are responsible for the syntax highlighting of source code. -They are located in `lexers/`. - -### 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 - -Built-in themes to customize the look and behavior of Textadept are located in -`themes/`. - -### User - -User Lua modules are contained in the `~/.textadept/` folder. This folder may -contain `lexers/`, `modules/`, and `themes/` subdirectories. - -### 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 deleted file mode 100644 index aa7b2303..00000000 --- a/doc/manual/12_Compiling.md +++ /dev/null @@ -1,109 +0,0 @@ -# Compiling - -## Requirements - -Unfortunately, the requirements for building Textadept are not quite as minimal -as running it. - -### 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][]. 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. - -[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][] (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][] 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 - -[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 - -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 -`/usr/bin/` or elsewhere in your `PATH`. - -BSD users please run `make BSD=1`. - -### 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 - -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 -this point it is recommended to build a new `textadept.app` from an existing -one. Download the most recent app and replace `Contents/MacOS/textadept.osx`, -all `.dylib` files in `Contents/Resources/lib`, and all `.so` files in -`Contents/Resources/lib/gtk-2.0//{engines,immodules,loaders}` with your -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 - -If the build fails because of a - - `redefinition of 'struct Sci_TextRange'` - -error, open `src/scintilla/include/Scintilla.h` and comment out the following -lines (put `//` at the start of the line): - - #define CharacterRange Sci_CharacterRange - #define TextRange Sci_TextRange - #define TextToFind Sci_TextToFind - -### Compiling with LuaJIT - -[LuaJIT][] is a Just-In-Time Compiler for Lua and can boost the speed of Lua -programs. I have noticed that syntax highlighting can be up to 2 times faster -with LuaJIT than with vanilla Lua. This difference is largely unnoticable on -modern computers and usually only discernable when initially loading large -files. Other than syntax highlighting, LuaJIT offers no real benefit -performance-wise to justify it being Textadept's default runtime. LuaJIT's -[ffi library][], however, appears to be useful for interfacing with external, -non-Lua, libraries. - -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 -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 deleted file mode 100644 index 800a18cb..00000000 --- a/doc/manual/13_Help.md +++ /dev/null @@ -1,15 +0,0 @@ -# Help - -## Command Line Parameters - -Passing `-h` or `--help` to Textadept shows a list of available command line -parameters. - -## Online Help - -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 deleted file mode 100644 index 426ab35f..00000000 --- a/doc/manual/14_Appendix.md +++ /dev/null @@ -1,686 +0,0 @@ -# Appendix - -## Key Bindings - -Linux / Win32 | Mac OSX | Command | ---------------|---------|---------| -**File** ||| -Ctrl+N |⌘N |New file -Ctrl+O |⌘O |Open file -Ctrl+Alt+O |^⌘O |Open recent file... -Ctrl+Shift+O|⌘⇧O |Reload file -Ctrl+S |⌘S |Save file -Ctrl+Shift+S|⌘⇧S |Save file as.. -Ctrl+W |⌘W |Close file -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 -Ctrl+X
Shift+Del |⌘X
⇧⌦|Cut -Ctrl+C
Ctrl+Ins |⌘C |Copy -Ctrl+V
Shift+Ins |⌘V |Paste -Ctrl+D |⌘D |Duplicate line -Del |⌦
^D |Delete -Alt+Del |^⌦ |Delete word -Ctrl+A |⌘A |Select all -Ctrl+M |^M |Match brace -Ctrl+Enter |^⎋ |Complete word -Ctrl+Alt+Shift+H |⌘⇧H |Highlight word -Ctrl+/ |^/ |Toggle block comment -Ctrl+T |^T |Transpose characters -Ctrl+Shift+J |^J |Join lines -Ctrl+Shift+M |^⇧M |Select to matching brace -Ctrl+< |⌘< |Select between XML tags -Ctrl+> |⌘> |Select in XML tag -Ctrl+" |⌘" |Select in double quotes -Ctrl+' |⌘' |Select in single quotes -Ctrl+( |⌘( |Select in parentheses -Ctrl+[ |⌘[ |Select in brackets -Ctrl+{ |⌘{ |Select in braces -Ctrl+Shift+D |⌘⇧D |Select word -Ctrl+Shift+N |⌘⇧N |Select line -Ctrl+Shift+P |⌘⇧P |Select paragraph -Ctrl+Shift+I |⌘⇧I |Select indented block -Ctrl+Alt+U |^U |Upper case selection -Ctrl+Alt+Shift+U |^⇧U |Lower case selection -Alt+< |^< |Enclose as XML tags -Alt+> |^> |Enclose as single XML tag -Alt+" |^" |Enclose in double quotes -Alt+' |^' |Enclose in single quotes -Alt+( |^( |Enclose in parentheses -Alt+[ |^[ |Enclose in brackets -Alt+{ |^{ |Enclose in braces -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 -Ctrl+Shift+G
Shift+F3|⌘⇧G |Find previous -Ctrl+Alt+R |^R |Replace -Ctrl+Alt+Shift+R |^⇧R |Replace all -Ctrl+Alt+F |^⌘F |Find incremental -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 -Ctrl+R |⌘R |Run -Ctrl+Shift+R |⌘⇧R |Compile -Ctrl+| |⌘||Filter text through -Ctrl+Space |⌥⎋ |Complete symbol -Ctrl+H |^H |Show documentation -Tab |⇥ |Expand snippet or next placeholder -Ctrl+K |⌥⇥ |Insert snippet... -Shift+Tab |⇧⇥ |Previous snippet placeholder -Ctrl+Shift+K |⌥⇧⇥ |Cancel snippet -Ctrl+F2 |⌘F2 |Toggle bookmark -Ctrl+Shift+F2 |⌘⇧F2 |Clear bookmarks -F2 |F2 |Next bookark -Shift+F2 |⇧F2 |Previous bookmark -Alt+F2 |⌥F2 |Goto bookmark... -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 -Ctrl+B |⌘B |Switch to buffer... -None |None |Tab width: 2 -None |None |Tab width: 3 -None |None |Tab width: 4 -None |None |Tab width: 8 -Ctrl+Alt+Shift+T|^⇧T |Toggle use tabs -Ctrl+Alt+I |^I |Convert indentation -None |None |`CRLF` EOL mode -None |None |`CR` EOL mode -None |None |`LF` EOL mode -None |None |`UTF-8` encoding -None |None |`ASCII` encoding -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 -Ctrl+Alt+S
Ctrl+Alt+H|^S |Split view horizontal -Ctrl+Alt+V |^V |Split view vertical -Ctrl+Alt+W |^W |Unsplit view -Ctrl+Alt+Shift+W |^⇧W |Unsplit all views -Ctrl+Alt++
Ctrl+Alt+=|^+
^=|Grow view -Ctrl+Alt+- |^- |Shrink view -None |None |Toggle current fold -Ctrl+Alt+Enter |^↩ |Toggle view EOL -Ctrl+Alt+\\ |^\\ |Toggle wrap mode -Ctrl+Alt+Shift+I |^⇧I |Toggle show indent guides -Ctrl+Alt+Shift+S |^⇧S |Toggle view whitespace -Ctrl+Alt+Shift+V |^⇧V |Toggle virtual space -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 -Ctrl+Down |^⇣ |Scroll line down -Alt+Shift+Down |⌥⇧⇣ |Line down extend rect. selection -Up |⇡
^P |Line up -Shift+Up |⇧⇡
^⇧P |Line up extend selection -Ctrl+Up |^⇡ |Scroll line up -Alt+Shift+Up |⌥⇧⇡ |Line up extend rect. selection -Left |⇠
^B |Char left -Shift+Left |⇧⇠
^⇧B |Char left extend selection -Ctrl+Left |^⇠
^⌘B |Word left -Ctrl+Shift+Left |^⇧⇠
^⌘⇧B|Word left extend selection -Alt+Shift+Left |⌥⇧⇠ |Char left extend rect. selection -Right |⇢
^F |Char right -Shift+Right |⇧⇢
^⇧F |Char right extend selection -Ctrl+Right |^⇢
^⌘F |Word right -Ctrl+Shift+Right |^⇧⇢
^⌘⇧F|Word right extend selection -Alt+Shift+Right |⌥⇧⇢ |Char right extend rect. selection -Home |⌘⇠
^A |Line start -Shift+Home |⌘⇧⇠
^⇧A |Line start extend selection -Ctrl+Home |⌘⇡
⌘↖ |Document start -Ctrl+Shift+Home |⌘⇧⇡
⌘⇧↖ |Document start extend selection -Alt+Shift+Home |⌥⇧↖ |Line start extend rect. selection -End |⌘⇢
^E |Line end -Shift+End |⌘⇧⇢
^⇧E |Line end extend selection -Ctrl+End |⌘⇣
⌘↘ |Document end -Ctrl+Shift+End |⌘⇧⇣
⌘⇧↘ |Document end extend selection -Alt+Shift+End |⌥⇧↘ |Line end extend rect. selection -PageUp |⇞ |Page up -Shift+PageUp |⇧⇞ |Page up extend selection -Alt+Shift+PageUp |⌥⇧⇞ |Page up extend rect. selection -PageDown |⇟ |Page down -Shift+PageDown |⇧⇟ |Page down extend selection -Alt+Shift+PageDown |⌥⇧⇟ |Page down extend rect. selection -Ctrl+Del |⌘⌦ |Delete word right -Ctrl+Shift+Del |⌘⇧⌦ |Delete line right -Ins |Ins |Toggle overtype -Backspace
Shift+Backspace|⌫
⇧⌫ |Delete back -Ctrl+Backspace |⌘⌫ |Delete word left -Ctrl+Shift+Backspace |⌘⇧⌫ |Delete line left -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][]. - -_Character Class:_ - -A character class is used to represent a set of characters. The following -combinations are allowed in describing a character class: - -* **_`x`_:** (where _x_ is not one of the magic characters `^$()%.[]*+-?`) - represents the character _x_ itself. -* **`.`:** (a dot) represents all characters. -* **`%a`:** represents all letters. -* **`%c`:** represents all control characters. -* **`%d`:** represents all digits. -* **`%g`:** represents all printable characters except space. -* **`%l`:** represents all lowercase letters. -* **`%p`:** represents all punctuation characters. -* **`%s`:** represents all space characters. -* **`%u`:** represents all uppercase letters. -* **`%w`:** represents all alphanumeric characters. -* **`%x`:** represents all hexadecimal digits. -* **`%`_`x`_:** (where _x_ is any non-alphanumeric character) represents the - character _x_. This is the standard way to escape the magic characters. Any - punctuation character (even the non magic) can be preceded by a '`%`' when - used to represent itself in a pattern. -* **`[set]`:** represents the class which is the union of all characters in set. - A range of characters can be specified by separating the end characters of the - range with a '`-`'. All classes `%`_x_ described above can also be used as - components in set. All other characters in set represent themselves. For - example, `[%w_]` (or `[_%w]`) represents all alphanumeric characters plus the - underscore, `[0-7]` represents the octal digits, and `[0-7%l%-]` represents - the octal digits plus the lowercase letters plus the '`-`' character. -

- The interaction between ranges and classes is not defined. Therefore, patterns - like `[%a-z]` or `[a-%%]` have no meaning. -* **`[^set]`:** represents the complement of _set_, where _set_ is interpreted - as above. - -For all classes represented by single letters (`%a`, `%c`, etc.), the -corresponding uppercase letter represents the complement of the class. For -instance, `%S` represents all non-space characters. - -The definitions of letter, space, and other character groups depend on the -current locale. In particular, the class `[a-z]` may not be equivalent to `%l`. - -_Pattern Item:_ - -A _pattern item_ can be - -* a single character class, which matches any single character in the class; -* a single character class followed by '`*`', which matches 0 or more - repetitions of characters in the class. These repetition items will always - match the longest possible sequence; -* a single character class followed by '`+`', which matches 1 or more - repetitions of characters in the class. These repetition items will always - match the longest possible sequence; -* a single character class followed by '`-`', which also matches 0 or more - repetitions of characters in the class. Unlike '`*`', these repetition items - will always match the _shortest_ possible sequence; -* a single character class followed by '`?`', which matches 0 or 1 occurrence of - a character in the class; -* `%n`, for _n_ between 1 and 9; such item matches a substring equal to the - _n_-th captured string (see below); -* `%bxy`, where _x_ and _y_ are two distinct characters; such item matches - strings that start with _x_, end with _y_, and where the _x_ and _y_ are - balanced. This means that, if one reads the string from left to right, - counting +_1_ for an _x_ and -_1_ for a _y_, the ending _y_ is the first _y_ - where the count reaches 0. For instance, the item `%b()` matches expressions - with balanced parentheses. -* `%f[set]`, a _frontier pattern_; such item matches an empty string at any - position such that the next character belongs to _set_ and the previous - character does not belong to _set_. The set _set_ is interpreted as previously - described. The beginning and the end of the subject are handled as if they - were the character `'\0'`. - -_Pattern:_ - -A _pattern_ is a sequence of pattern items. A '`^`' at the beginning of a -pattern anchors the match at the beginning of the subject string. A '`$`' at the -end of a pattern anchors the match at the end of the subject string. At other -positions, '`^`' and '`$`' have no special meaning and represent themselves. - -_Captures:_ - -A pattern can contain sub-patterns enclosed in parentheses; they describe -_captures_. When a match succeeds, the substrings of the subject string that -match captures are stored (_captured_) for future use. Captures are numbered -according to their left parentheses. For instance, in the pattern -`"(a*(.)%w(%s*))"`, the part of the string matching `"a*(.)%w(%s*)"` is stored -as the first capture (and therefore has number 1); the character matching "`.`" -is captured with number 2, and the part matching "`%s*`" has number 3. - -As a special case, the empty capture `()` captures the current string position -(a number). For instance, if we apply the pattern `"()aa()"` on the string -`"flaaap"`, there will be two captures: 3 and 5. - -[Lua 5.2 Reference Manual]: http://www.lua.org/manual/5.2/manual.html#6.4.1 - -## 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/images/adeptsense_doc.png b/doc/manual/images/adeptsense_doc.png deleted file mode 100644 index 36356591..00000000 Binary files a/doc/manual/images/adeptsense_doc.png and /dev/null differ diff --git a/doc/manual/images/adeptsense_lua.png b/doc/manual/images/adeptsense_lua.png deleted file mode 100644 index 75e581f2..00000000 Binary files a/doc/manual/images/adeptsense_lua.png and /dev/null differ diff --git a/doc/manual/images/adeptsense_string.png b/doc/manual/images/adeptsense_string.png deleted file mode 100644 index ed5f4244..00000000 Binary files a/doc/manual/images/adeptsense_string.png and /dev/null differ diff --git a/doc/manual/images/adeptsense_ta.png b/doc/manual/images/adeptsense_ta.png deleted file mode 100644 index e280fc72..00000000 Binary files a/doc/manual/images/adeptsense_ta.png and /dev/null differ diff --git a/doc/manual/images/adeptsense_tadoc.png b/doc/manual/images/adeptsense_tadoc.png deleted file mode 100644 index 8ccd325e..00000000 Binary files a/doc/manual/images/adeptsense_tadoc.png and /dev/null differ diff --git a/doc/manual/images/bufferbrowser.png b/doc/manual/images/bufferbrowser.png deleted file mode 100644 index de7defe1..00000000 Binary files a/doc/manual/images/bufferbrowser.png and /dev/null differ diff --git a/doc/manual/images/bufferbrowserfiltered.png b/doc/manual/images/bufferbrowserfiltered.png deleted file mode 100644 index c4c01486..00000000 Binary files a/doc/manual/images/bufferbrowserfiltered.png and /dev/null differ diff --git a/doc/manual/images/commandentry.png b/doc/manual/images/commandentry.png deleted file mode 100644 index cbcd66a7..00000000 Binary files a/doc/manual/images/commandentry.png and /dev/null differ diff --git a/doc/manual/images/commandentrycompletion.png b/doc/manual/images/commandentrycompletion.png deleted file mode 100644 index a4b83059..00000000 Binary files a/doc/manual/images/commandentrycompletion.png and /dev/null differ diff --git a/doc/manual/images/darktheme.png b/doc/manual/images/darktheme.png deleted file mode 100644 index 0c683dc7..00000000 Binary files a/doc/manual/images/darktheme.png and /dev/null differ diff --git a/doc/manual/images/docstatusbar.png b/doc/manual/images/docstatusbar.png deleted file mode 100644 index 5e709ab2..00000000 Binary files a/doc/manual/images/docstatusbar.png and /dev/null differ diff --git a/doc/manual/images/findinfiles.png b/doc/manual/images/findinfiles.png deleted file mode 100644 index 2f8783aa..00000000 Binary files a/doc/manual/images/findinfiles.png and /dev/null differ diff --git a/doc/manual/images/icon.png b/doc/manual/images/icon.png deleted file mode 100644 index c9457dfe..00000000 Binary files a/doc/manual/images/icon.png and /dev/null differ diff --git a/doc/manual/images/lighttheme.png b/doc/manual/images/lighttheme.png deleted file mode 100644 index e5100912..00000000 Binary files a/doc/manual/images/lighttheme.png and /dev/null differ diff --git a/doc/manual/images/linux.png b/doc/manual/images/linux.png deleted file mode 100644 index a8640022..00000000 Binary files a/doc/manual/images/linux.png and /dev/null differ diff --git a/doc/manual/images/macosx.png b/doc/manual/images/macosx.png deleted file mode 100644 index 2035a95b..00000000 Binary files a/doc/manual/images/macosx.png and /dev/null differ diff --git a/doc/manual/images/matchingbrace.png b/doc/manual/images/matchingbrace.png deleted file mode 100644 index 22a99c19..00000000 Binary files a/doc/manual/images/matchingbrace.png and /dev/null differ diff --git a/doc/manual/images/rectangularselection.png b/doc/manual/images/rectangularselection.png deleted file mode 100644 index 3fe77a6a..00000000 Binary files a/doc/manual/images/rectangularselection.png and /dev/null differ diff --git a/doc/manual/images/rectangularselection2.png b/doc/manual/images/rectangularselection2.png deleted file mode 100644 index a4a84f61..00000000 Binary files a/doc/manual/images/rectangularselection2.png and /dev/null differ diff --git a/doc/manual/images/snapopen.png b/doc/manual/images/snapopen.png deleted file mode 100644 index 8ae1bb74..00000000 Binary files a/doc/manual/images/snapopen.png and /dev/null differ diff --git a/doc/manual/images/snippet.png b/doc/manual/images/snippet.png deleted file mode 100644 index d73c621a..00000000 Binary files a/doc/manual/images/snippet.png and /dev/null differ diff --git a/doc/manual/images/snippet2.png b/doc/manual/images/snippet2.png deleted file mode 100644 index cbafb98c..00000000 Binary files a/doc/manual/images/snippet2.png and /dev/null differ diff --git a/doc/manual/images/splitviews.png b/doc/manual/images/splitviews.png deleted file mode 100644 index bdb516ec..00000000 Binary files a/doc/manual/images/splitviews.png and /dev/null differ diff --git a/doc/manual/images/textadept.png b/doc/manual/images/textadept.png deleted file mode 100644 index 8731e5cc..00000000 Binary files a/doc/manual/images/textadept.png and /dev/null differ diff --git a/doc/manual/images/ui.png b/doc/manual/images/ui.png deleted file mode 100644 index e9c97f4c..00000000 Binary files a/doc/manual/images/ui.png and /dev/null differ diff --git a/doc/manual/images/win32.png b/doc/manual/images/win32.png deleted file mode 100644 index 996c2b5f..00000000 Binary files a/doc/manual/images/win32.png and /dev/null differ diff --git a/doc/manual/images/wordcompletion.png b/doc/manual/images/wordcompletion.png deleted file mode 100644 index e55280a9..00000000 Binary files a/doc/manual/images/wordcompletion.png and /dev/null differ diff --git a/doc/manual/images/wordhighlight.png b/doc/manual/images/wordhighlight.png deleted file mode 100644 index 61c8832b..00000000 Binary files a/doc/manual/images/wordhighlight.png and /dev/null differ -- cgit v1.2.3