From cbe7f531f956573cf55efba417965976672e6c63 Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Wed, 7 Mar 2012 09:31:09 -0500 Subject: Renamed manual pages 1-9 to preserve sort order. --- 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/1_Introduction.md | 63 ------------- doc/manual/2_Installation.md | 119 ------------------------- doc/manual/3_UserInterface.md | 37 -------- doc/manual/4_WorkingWithFiles.md | 69 -------------- doc/manual/5_FileNavigation.md | 25 ------ doc/manual/6_AdeptEditing.md | 183 -------------------------------------- doc/manual/7_Modules.md | 158 -------------------------------- doc/manual/8_Themes.md | 88 ------------------ doc/manual/9_Preferences.md | 143 ----------------------------- 18 files changed, 885 insertions(+), 885 deletions(-) create mode 100644 doc/manual/01_Introduction.md create mode 100644 doc/manual/02_Installation.md create mode 100644 doc/manual/03_UserInterface.md create mode 100644 doc/manual/04_WorkingWithFiles.md create mode 100644 doc/manual/05_FileNavigation.md create mode 100644 doc/manual/06_AdeptEditing.md create mode 100644 doc/manual/07_Modules.md create mode 100644 doc/manual/08_Themes.md create mode 100644 doc/manual/09_Preferences.md delete mode 100644 doc/manual/1_Introduction.md delete mode 100644 doc/manual/2_Installation.md delete mode 100644 doc/manual/3_UserInterface.md delete mode 100644 doc/manual/4_WorkingWithFiles.md delete mode 100644 doc/manual/5_FileNavigation.md delete mode 100644 doc/manual/6_AdeptEditing.md delete mode 100644 doc/manual/7_Modules.md delete mode 100644 doc/manual/8_Themes.md delete mode 100644 doc/manual/9_Preferences.md (limited to 'doc/manual') diff --git a/doc/manual/01_Introduction.md b/doc/manual/01_Introduction.md new file mode 100644 index 00000000..0bdf97e2 --- /dev/null +++ b/doc/manual/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/manual/02_Installation.md b/doc/manual/02_Installation.md new file mode 100644 index 00000000..ffc8b938 --- /dev/null +++ b/doc/manual/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/manual/03_UserInterface.md b/doc/manual/03_UserInterface.md new file mode 100644 index 00000000..bda4d1fe --- /dev/null +++ b/doc/manual/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/manual/04_WorkingWithFiles.md b/doc/manual/04_WorkingWithFiles.md new file mode 100644 index 00000000..201e46cf --- /dev/null +++ b/doc/manual/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/manual/05_FileNavigation.md b/doc/manual/05_FileNavigation.md new file mode 100644 index 00000000..953464a7 --- /dev/null +++ b/doc/manual/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/manual/06_AdeptEditing.md b/doc/manual/06_AdeptEditing.md new file mode 100644 index 00000000..9dee1183 --- /dev/null +++ b/doc/manual/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/manual/07_Modules.md b/doc/manual/07_Modules.md new file mode 100644 index 00000000..1b915c85 --- /dev/null +++ b/doc/manual/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/manual/08_Themes.md b/doc/manual/08_Themes.md new file mode 100644 index 00000000..b40135e2 --- /dev/null +++ b/doc/manual/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/manual/09_Preferences.md b/doc/manual/09_Preferences.md new file mode 100644 index 00000000..abceaa97 --- /dev/null +++ b/doc/manual/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/manual/1_Introduction.md b/doc/manual/1_Introduction.md deleted file mode 100644 index 0bdf97e2..00000000 --- a/doc/manual/1_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/2_Installation.md b/doc/manual/2_Installation.md deleted file mode 100644 index ffc8b938..00000000 --- a/doc/manual/2_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/3_UserInterface.md b/doc/manual/3_UserInterface.md deleted file mode 100644 index bda4d1fe..00000000 --- a/doc/manual/3_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/4_WorkingWithFiles.md b/doc/manual/4_WorkingWithFiles.md deleted file mode 100644 index 201e46cf..00000000 --- a/doc/manual/4_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/5_FileNavigation.md b/doc/manual/5_FileNavigation.md deleted file mode 100644 index 953464a7..00000000 --- a/doc/manual/5_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/6_AdeptEditing.md b/doc/manual/6_AdeptEditing.md deleted file mode 100644 index 9dee1183..00000000 --- a/doc/manual/6_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/7_Modules.md b/doc/manual/7_Modules.md deleted file mode 100644 index 1b915c85..00000000 --- a/doc/manual/7_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/8_Themes.md b/doc/manual/8_Themes.md deleted file mode 100644 index b40135e2..00000000 --- a/doc/manual/8_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/9_Preferences.md b/doc/manual/9_Preferences.md deleted file mode 100644 index abceaa97..00000000 --- a/doc/manual/9_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 -- cgit v1.2.3