diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/01_Introduction.md | 75 | ||||
| -rw-r--r-- | doc/02_Installation.md | 134 | ||||
| -rw-r--r-- | doc/03_UserInterface.md | 35 | ||||
| -rw-r--r-- | doc/04_WorkingWithFiles.md | 153 | ||||
| -rw-r--r-- | doc/05_FileNavigation.md | 27 | ||||
| -rw-r--r-- | doc/06_AdeptEditing.md | 254 | ||||
| -rw-r--r-- | doc/07_Modules.md | 74 | ||||
| -rw-r--r-- | doc/08_Preferences.md | 131 | ||||
| -rw-r--r-- | doc/09_Themes.md | 36 | ||||
| -rw-r--r-- | doc/10_Advanced.md | 59 | ||||
| -rw-r--r-- | doc/11_Scripting.md | 76 | ||||
| -rw-r--r-- | doc/12_Compiling.md | 119 | ||||
| -rw-r--r-- | doc/13_Help.md | 6 |
13 files changed, 577 insertions, 602 deletions
diff --git a/doc/01_Introduction.md b/doc/01_Introduction.md index ac577111..f3256c68 100644 --- a/doc/01_Introduction.md +++ b/doc/01_Introduction.md @@ -15,55 +15,54 @@ speed or succumbing to code bloat and featuritis. ### Fast Textadept is _fast_. It starts up instantly and has a very responsive user -interface. Even though the editor is mostly written in Lua, Lua is one of the +interface. Even though the editor consists primarily of Lua, Lua is one of the fastest scripting languages available. With the optional [LuaJIT][] version, -Textadept is faster than ever before. +Textadept runs faster than ever before. [LuaJIT]: http://luajit.org ### Minimalist -Textadept is minimalist. Not only is this apparent in its appearance, but the -editor's C core was designed to never exceed 2000 lines of code and its Lua -extension code is capped at 4000 lines. After more than 5 years of development, -Textadept has maintained the same amount of code since its inception while -evolving into a vastly superior editor. +Textadept is minimalist. Not only does its appearance exhibit this, but the +editor's C core pledges to never exceed 2000 lines of code and its Lua extension +code avoids going beyond 4000 lines. After more than 5 years of development, +Textadept contains the same amount of code since its inception while evolving +into a vastly superior editor. ### Ridiculously Extensible -Textadept is ridiculously extensible. It was designed to be that way from the -very beginning. The features came later. Most of Textadept's internals use 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 core events. The possibilities are limitless. +Textadept is ridiculously extensible. Designed to be that way from the very +beginning, the editor's features came later. Most of Textadept's internals use +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. Everything from moving the caret to changing menus and +key commands on-the-fly to handling core events is possible. Its potential is +vast.  ## Manual Notation -This manual uses notation that is worth clarifying. - -Directories and file paths are represented like this: */path/to/dir/* and -*/path/to/file*. (On Windows machines, '/' and '\' can be used interchangeably -as directory separators.) Any relative paths, paths that do not begin with '/' -or "C:\", are relative to the location of Textadept. *~/* is denoted as the -user's home directory. On Windows machines this is the value of the "USERHOME" -environment variable, typically *C:\Users\username\\* or -*C:\Documents and Settings\username\\*. On Linux, BSD, and Mac OSX machines -it is the value of "$HOME", typically */home/username/* and */Users/username/* -respectively. - -Key bindings are represented like this: `Ctrl+N`. They are not case sensitive. -`Ctrl+N` means the "N" key is pressed with only the "Control" modifier key being -held down, not the "Shift" modifier key. `Ctrl+Shift+N` means the "N" key is -pressed with both "Control" and "Shift" modifiers 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 key bindings are mentioned, the Mac OSX and curses equivalents are often -shown in parenthesis. It may be tempting to assume that some Windows/Linux keys -map to Mac OSX's (e.g. `Ctrl` to `⌘`) or curses' (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. +The manual represents directories and file paths like this: */path/to/dir/* and +*/path/to/file*. (Windows machines use '/' and '\' interchangeably as directory +separators.) Paths that do not begin with '/' or "C:\", are relative to the +location of Textadept. *~/* denotes the user's home directory. On Windows +machines this is the value of the "USERHOME" environment variable, typically +*C:\Users\username\\* or *C:\Documents and Settings\username\\*. On Linux, BSD, +and Mac OSX machines it is the value of "$HOME", typically */home/username/* and +*/Users/username/*, respectively. + +The manual expresses key bindings like this: `Ctrl+N`. They are not case +sensitive. `Ctrl+N` stands for pressing the "N" key while only holding down the +"Control" modifier key, not the "Shift" modifier key. `Ctrl+Shift+N` stands for +pressing the "N" key while holding down both the "Control" and "Shift" +modifiers. The same notation applies to key chains like `Ctrl+N, N` and +`Ctrl+N, Shift+N`. The first key chain represents pressing "Control" and "N" +followed by "N" with no modifiers. The second represents pressing "Control" and +"N" followed by "Shift" and "N". + +When mentioning key bindings, the manual often shows the Mac OSX and curses +equivalents in parenthesis. It may be tempting to assume that some Windows/Linux +keys map to Mac OSX's (e.g. `Ctrl` to `⌘`) or curses' (e.g. `Ctrl` to `^`), but +this is not always the case. To minimize confusion, view key equivalents as +separate entities, not as translations of one another. diff --git a/doc/02_Installation.md b/doc/02_Installation.md index 81980721..c098ca63 100644 --- a/doc/02_Installation.md +++ b/doc/02_Installation.md @@ -2,36 +2,35 @@ ## Requirements -In its bid for minimalism, Textadept also needs very little to run. The GUI +In its bid for minimalism, Textadept also depends on very little to run. The GUI version needs only [GTK+][], a cross-platform GUI toolkit, version 2.18 or later -on Linux and BSD systems. A GTK+ runtime is already bundled into the Windows -and Mac OSX packages. Textadept also has its own [copy of Lua][]. The terminal -(curses) version of Textadept requires a curses implementation like [ncurses][], -but that dependency is only necessary if you wish to run the editor from a -terminal. +on Linux and BSD systems. The application already bundles a GTK+ runtime into +the Windows and Mac OSX packages. The terminal, or curses, version of Textadept +only depends on a curses implementation like [ncurses][] on Linux, Mac OSX, and +BSD systems. The Windows binary includes a precompiled version of [pdcurses][]. +Textadept also incorporates its own [copy of Lua][] on all platforms. [GTK+]: http://gtk.org [copy of Lua]: 11_Scripting.html#Lua.Configuration [ncurses]: http://invisible-island.net/ncurses/ncurses.html +[pdcurses]: http://pdcurses.sourceforge.net ### Linux and BSD -Most Linux and BSD systems already have GTK+ installed. If not, it is probably -available through your package manager. Otherwise, compile and install it from -the [GTK+ website][]. +Most Linux and BSD systems already have GTK+ installed. If not, your package +manager probably makes it available. Otherwise, compile and install GTK+from the +[GTK+ website][]. -The GUI versions of Textadept in the Linux binary downloads require GLib version -2.28 or later to support [single-instance](#Single.Instance) functionality. You -can compile Textadept with earlier versions of GLib down to 2.22. For reference, -Ubuntu 11.04, Debian Wheezy, Fedora 15, and openSUSE 11.4 support GLib 2.28 or -later. +The Linux binaries for the GUI versions of Textadept require GLib version 2.28 +or later to support [single-instance](#Single.Instance) functionality. However, +Textadept compiles with versions of GLib as early as 2.22. For reference, Ubuntu +11.04, Debian Wheezy, Fedora 15, and openSUSE 11.4 support GLib 2.28 or later. Most Linux and BSD systems already have a curses implementation like ncurses installed. If not, look for one in your package manager, or compile and install -ncurses from the [ncurses website][]. You need to have or compile the -wide-character version of ncurses, which handles multibyte characters. For -Debian-based distributions like Ubuntu, the package is typically called -"libncursesw5". +ncurses from the [ncurses website][]. Ensure it is the wide-character version of +ncurses, which handles multibyte characters. Debian-based distributions like +Ubuntu typically call the package "libncursesw5". [GTK+ website]: http://www.gtk.org/download-linux.html [ncurses website]: http://invisible-island.net/ncurses/#download_ncurses @@ -47,66 +46,64 @@ No requirements. ## Download Download Textadept from the project's [download page][] by selecting the -appropriate package for your platform. For Windows and Mac OSX, more than 3/4 of -the download and unpackaged application sizes are due to the bundled GTK+. -Textadept itself is much smaller. +appropriate package for your platform. For the Windows and Mac OSX packages, the +bundled GTK+ runtime accounts for more than 3/4 of the download and unpackaged +application sizes. Textadept itself is much smaller. -You can also download an official set of [language-specific modules][] from the -download page, but this is optional. The list of language modules in the package -is contained [here][]. Textadept includes C/C++ and Lua language modules by -default. +You also have the option of downloading an official set of +[language-specific modules][] from the download page. Textadept itself includes +C/C++ and Lua language modules by default. [download page]: http://foicica.com/textadept/download [language-specific modules]: 07_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. +Installing Textadept is simple and easy. You do not need administrator +privileges. ### Linux and BSD Unpack the archive anywhere. If you downloaded the set of language-specific modules, unpack it where you -unpacked the Textadept archive. The modules will be contained in the +unpacked the Textadept archive. The modules are located in the */path/to/textadept_x.x/modules/* directory. ### Mac OSX Unpack the archive and move *Textadept.app* to your user or system -*Applications/* directory like any other Mac OSX application. There is also a -*ta* script for launching Textadept from the command line that you can put in -a directory in your "$PATH" (e.g. */usr/local/bin/*), but this is optional. +*Applications/* directory like any other Mac OSX application. The package +contains an optional *ta* script for launching Textadept from the command line +that you can put in a directory in your "$PATH" (e.g. */usr/local/bin/*). 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. +*Contents/Resources/modules/*, and move the unpacked modules there. ### Windows Unpack the archive anywhere. If you downloaded the set of language-specific modules, unpack it where you -unpacked the Textadept archive. The modules will be contained in the +unpacked the Textadept archive. The modules are located in the *textadept_x.x\modules\\* directory. ## Running ### Linux and BSD -Run Textadept by running */path/to/textadept_x.x/textadept* from the terminal. +Run Textadept by running */path/to/textadept_x.x/textadept* from the terminal You can also create a symbolic link to the executable in a directory in your "$PATH" (e.g. */usr/local/bin/*) or make a GNOME, KDE, XFCE, etc. button or menu launcher. -There is also a *textadeptjit* executable for running Textadept with [LuaJIT][]. -Please note there may be [compatibility issues][]. The *textadept* executable is -recommended. +The package also contains a *textadeptjit* executable for running Textadept with +[LuaJIT][]. Due to potential [compatibility issues][], use the *textadept* +executable wherever possible. -The *textadept-curses* and *textadeptjit-curses* executables are versions of -Textadept for the terminal. Run them as you would run the *textadept* and +The *textadept-curses* and *textadeptjit-curses* executables are the terminal +versions of Textadept. Run them as you would run the *textadept* and *textadeptjit* executables, but from a terminal instead. [LuaJIT]: http://luajit.org @@ -114,7 +111,7 @@ Textadept for the terminal. Run them as you would run the *textadept* and #### Problems -It is difficult to provide a single binary that runs on all Linux platforms +Providing a single binary that runs on all Linux platforms proves challenging, 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: @@ -123,8 +120,8 @@ installed on your system, an error like: file: No such file or directory may occur when trying to run the program. The solution is actually quite -painless even though it requires recompiling Textadept. See the [compiling][] -page for more information. +painless even though it requires recompiling Textadept. The [compiling][] page +has more information. [compiling]: 12_Compiling.html @@ -134,23 +131,23 @@ Run Textadept by double-clicking *Textadept.app*. You can also pin it to your dock. *Textadept.app* also contains an executable for running Textadept with -[LuaJIT][]. You can enable it by setting a "TEXTADEPTJIT" -[environment variable](#Environment.Variables) or using `export TEXTADEPTJIT=1` -in the terminal. Please note there may be [compatibility issues][]. The -non-LuaJIT executable is recommended. +[LuaJIT][]. Enable it by setting a "TEXTADEPTJIT" +[environment variable](#Environment.Variables) or by typing +`export TEXTADEPTJIT=1` in the terminal. Due to potential +[compatibility issues][], use the non-LuaJIT executable wherever possible. [LuaJIT]: http://luajit.org [compatibility issues]: 11_Scripting.html#LuaJIT #### Environment Variables -By default, Mac OSX GUI apps like Textadept do not utilize environment variables -like "$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. +By default, Mac OSX GUI apps like Textadept do not see shell environment +variables like "$PATH". Consequently, any [modules][] that utilize programs +contained in "$PATH" (e.g. the progams in */usr/local/bin/*) for run and compile +commands will not find those programs. Follow [these instructions][] to export +the environment variables you need Textadept to see. At the very least, set +"PATH" to be "$PATH". You must logout and log back in before the changes take +effect. [modules]: 07_Modules.html [these instructions]: http://developer.apple.com/library/mac/#qa/qa1067/_index.html @@ -160,9 +157,9 @@ in for the changes to take effect. Run Textadept by double-clicking *textadept.exe*. You can also create shortcuts to the executable in your Start Menu, Quick Launch toolbar, Desktop, etc. -There is also a *textadeptjit.exe* executable for running Textadept with -[LuaJIT][]. Please note there may be [compatibility issues][]. The -*textadept.exe* executable is recommended. +The package also contains a *textadeptjit.exe* executable for running Textadept +with [LuaJIT][]. Due to potential [compatibility issues][], use the +*textadept.exe* executable wherever possible. [LuaJIT]: http://luajit.org [compatibility issues]: 11_Scripting.html#LuaJIT @@ -170,22 +167,21 @@ There is also a *textadeptjit.exe* executable for running Textadept with ### *~/.textadept* Textadept stores all of your preferences and user-data in your *~/.textadept/* -folder. If this folder does not exist, Textadept creates it on startup. You will -learn more about this folder later. +directory. If this directory does not exist, Textadept creates it on startup. +The manual gives more information on this folder later. ## Single Instance Textadept is a single-instance application on Linux, BSD, and Mac OSX. This -means that after Textadept is opened, running `textadept file.ext` -(`ta file.ext` on Mac OSX) from the command line or opening a file with -Textadept from a file manager will open *file.ext* in the existing instance of -Textadept. You can override this and open the file in a new instance by passing -a `-f` or `--force` switch to Textadept: `textadept -f file.ext` -(`ta -f file.ext`). When the force switch is not present, files will be opened -in the original Textadept instance, regardless of how many instances are open. - -Single instance is not supported on the Windows and terminal versions of -Textadept. +means that after starting Textadept, running `textadept file.ext` (`ta file.ext` +on Mac OSX) from the command line or opening a file with Textadept from a file +manager opens *file.ext* in the original Textadept instance. Passing a `-f` or +`--force` switch to Textadept overrides this behavior and opens the file in a +new instance: `textadept -f file.ext` (`ta -f file.ext`). Without the force +switch, the original Textadept instance opens files, regardless of the number of +instances open. + +The Windows and terminal versions of Textadept do not support single instance. <span style="display: block; text-align: right; margin-left: -10em;">  diff --git a/doc/03_UserInterface.md b/doc/03_UserInterface.md index e847ca70..0556f266 100644 --- a/doc/03_UserInterface.md +++ b/doc/03_UserInterface.md @@ -2,20 +2,19 @@  -Textadept's user interface was designed to be simple. It consists of a menu (GUI +Textadept's user interface is sleek and simple. It consists of a menu (GUI version only), editor view, and statusbar. There is also a find & replace pane -and a command entry, both of which are initially hidden. Below are brief -descriptions of these features. More in-depth discussion about some of them is -provided later in the manual. +and a command entry, but Textadept initially hides them both. The manual briefly +describes these features below, but provides more details later. ## Menu The completely customizable menu provides access to all of Textadept's features. -It is only available in the GUI version of Textadept. In the terminal version, -you can use the [command selection][] dialog instead. Textadept is very -keyboard-driven so most menu items have an assigned key shortcut. Key bindings -are changeable in your [key preferences][] and will reflect in the menu. Here is -a [complete list][] of default key bindings. +Only the GUI version implements it, though. The terminal version furnishes the +[command selection][] dialog instead. Textadept is very keyboard-driven and +assigns key shortcuts to most menu items. Your [key preferences][] can change +these shortcuts and reflect in the menu. Here is a [complete list][] of default +key bindings. [command selection]: 10_Advanced.html#Command.Selection [key preferences]: 08_Preferences.html#Key.Bindings @@ -23,26 +22,26 @@ a [complete list][] of default key bindings. ## Editor View -The editor view is where you will spend most of your time in Textadept. In the -GUI version, you can split this view into as many other views as you would like. -Each view is completely controllable by Lua. +Most of your time spent with Textadept is in the editor view. The GUI version +features unlimited view splitting both vertically and horizontally. Lua also has +complete control over all views. ## Find & Replace Pane This compact pane is a great way to slice and dice through your document or a -directory of files. You can even find and replace text using Lua patterns. It is -available only when you need it and quickly gets out of your way when you do -not, minimizing distractions. +directory of files. It even supports finding and replacing text using Lua +patterns and Lua code. The pane is available only 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, among other things, a place to execute Lua commands with Textadept's internal Lua state, find text incrementally, and -execute shell commands. You can extend it to do even more. Like the Find & +execute shell commands. Lua extensions allow it to do even more. Like the Find & Replace pane, the command entry pops in and out as you wish. ## Statusbar -The statusbar is actually composed to two statusbars. The one on the left-hand -side displays temporary status messages. The one on the right-hand side +The statusbar actually consists of two statusbars. The one on the left-hand +side displays temporary status messages while the one on the right-hand side persistently shows the current buffer status. diff --git a/doc/04_WorkingWithFiles.md b/doc/04_WorkingWithFiles.md index ff8ce0fa..029f2e0d 100644 --- a/doc/04_WorkingWithFiles.md +++ b/doc/04_WorkingWithFiles.md @@ -2,32 +2,33 @@ ## Buffers -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 because Textadept was built to support unlimited split views. Having a -single tab bar for multiple views would cause confusion and having one tab bar -per view would clutter the interface. +One of the first things notably absent when opening multiple files in Textadept +is the lack of a tab bar showing the open files. This design decision allowed +Textadept to support unlimited split views from the very beginning. Having a +single tab bar for multiple views causes confusion and having one tab bar per +view clutters the interface. Instead of having tabs, Textadept has the buffer browser. Press `Ctrl+B` (`⌘B` on Mac OSX | `M-B` or `M-S-B` in curses) to open it.  -The buffer browser shows you a list of currently open buffers, the most recent +The buffer browser displays 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 selecting -`OK` switches to the selected buffer. +wildcards. The arrow keys move the selection up and down. Pressing `Enter`, +selecting `OK`, or double-clicking a buffer in the list switches to the selected +buffer.  -You can see which buffer is active by looking at Textadept's titlebar. Pressing +Textadept shows the name of the active buffer in its titlebar. Pressing `Ctrl+Tab` (`^⇥` on Mac OSX | `M-N` in curses) cycles to the next buffer and `Ctrl+Shift+Tab` (`^⇧⇥` | `M-P`) cycles to the previous one. ### Settings Individual files have three configurable settings: indentation, line endings, -and encoding. Indentation is composed of an indentation character and an +and encoding. Indentation consists of an indentation character and an indentation size. Line endings are characters that separate lines. File encoding determines how text characters are displayed. Textadept shows these settings in the buffer status statusbar. @@ -36,45 +37,42 @@ settings in the buffer status statusbar. #### Indentation -Indentation is usually set by a [language-specific module][] or by the user's -[settings][]. By default, indentation is 2 spaces. You can toggle between using -tabs and spaces manually by pressing `Ctrl+Alt+Shift+T` (`^⇧T` on Mac OSX | -`M-T` or `M-S-T` in curses). Toggling between tabs and spaces only affects -future indentation; it does not convert existing indentation. `Ctrl+Alt+I` (`^I` -| `M-I`) performs the conversion. (If the buffer is using tabs, all indenting -spaces are converted to tabs. If the buffer is using spaces, all indenting tabs -are converted to spaces.) Similarly, you can set indentation size manually using -the "Buffer -> Indentation" menu. +Usually, [language-specific modules][] or [user settings][] dictate the +buffer's indentation setting. By default, indentation is 2 spaces. Pressing +`Ctrl+Alt+Shift+T` (`^⇧T` on Mac OSX | `M-T` or `M-S-T` in curses) manually +toggles between using tabs and spaces, although this only affects future +indentation. Existing indentation remains unchanged. `Ctrl+Alt+I` (`^I` | `M-I`) +performs the conversion. (If the buffer uses tabs, all indenting spaces convert +to tabs. If the buffer uses spaces, all indenting tabs convert to spaces.) +Similarly, the "Buffer -> Indentation" menu manually sets indentation size. -[language-specific module]: 07_Modules.html#Buffer.Properties -[settings]: 08_Preferences.html#Buffer.Settings +[language-specific modules]: 07_Modules.html#Buffer.Properties +[user settings]: 08_Preferences.html#Buffer.Settings #### Line Endings -Line endings, commonly known as end-of-line (EOL) markers, are set for new files -based on the current platform. On Windows, CRLF ("\r\n") is used. Otherwise, LF -("\n") is. This can be changed manually using the "Buffer -> EOL Mode" menu. -Unlike indentation settings, switching EOL modes converts all existing EOLs -automatically. Textadept attempts to auto-detect the EOL mode of opened files -regardless of the current platform, but falls back to the defaults mentioned -earlier when necessary. +The current platform determines which line endings, commonly known as +end-of-line (EOL) markers, to use by default. On Windows it is CRLF ("\r\n"). On +all other platforms it is LF ('\n'). Textadept first tries to auto-detect the +EOL mode of opened files before falling back on the platform default. The +"Buffer -> EOL Mode" menu manually changes line endings and, unlike indentation +settings, automatically converts all existing EOLs. #### Encodings -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.encodings`][]. +Textadept represents all characters and strings internally as UTF-8. UTF-8 is +compatible with ASCII so those files are always detected properly. Textadept +also recognizes ISO-8859-1 and MacRoman, two common encodings used on Windows +and Mac OSX respectively. If you work with files whose encodings Textadept does +not recognize, add the encodings to [`io.encodings`][] in your [preferences][]. -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 file -encoding via the "Buffer -> Encoding" menu. Conversion is immediate, requiring -no separate steps. Textadept saves new files as UTF-8 by default, but does not -alter the encoding of existing files. +UTF-8 is the recommended file encoding because of its wide support by other text +editors and operating systems. The "Buffer -> Encoding" menu changes the file +encoding and performs the conversion. Textadept saves new files as UTF-8 by +default, but does not alter the encoding of existing ones. [`io.encodings`]: api/io.html#encodings +[preferences]: 08_Preferences.html ### Recent Files @@ -84,25 +82,25 @@ files to reopen. ### Sessions -By default, Textadept saves its state on exit so it can be restored the next -time the editor starts up. You can disable this by passing the `-n` or -`--nosession` switch to Textadept on startup. Sessions can be manually saved and -opened via the "File -> Save Session..." and "File -> Load Session..." menus or -by using the `-s` and `--session` switches on startup. The switches accept the -path of a session file or the name of a session in *~/.textadept/*. Session -files store information such as open buffers, current split views, caret and -scroll positions in each buffer, Textadept's window size, and recently opened -files. Tampering with session files may have unintended consequences. +By default, Textadept saves its state when quitting in order to restore it the +next time the editor starts up. Passing the `-n` or `--nosession` switch to +Textadept on startup disables this feature. The "File -> Save Session..." and +"File -> Load Session..." menus manually save and open sessions while the `-s` +and `--session` switches load a session on startup. The switches accept the path +of a session file or the name of a session in *~/.textadept/*. Session files +store information such as open buffers, current split views, caret and scroll +positions in each buffer, Textadept's window size, and recently opened files. +Tampering with session files may have unintended consequences. ### Snapopen A quicker, though slightly more limited alternative to the standard file -selection dialog is snapopen. It behaves like the buffer browser, but displays a -list of files to open, including files in sub-directories. You can snapopen the -current file's directory with `Ctrl+Alt+Shift+O` (`^⌘⇧O` on Mac OSX | `M-S-O` in -curses) or from the "Tools -> Snapopen -> Current Directory" menu. Snapopen is -pretty limited from the menu, but more versatile in [scripts][]. `Ctrl+U` (`⌘U` -| `^U`) snaps open *~/.textadept/*. +selection dialog is snapopen. It too behaves like the buffer browser, but +displays a list of files to open, including files in sub-directories. Pressing +`Ctrl+Alt+Shift+O` (`^⌘⇧O` on Mac OSX | `M-S-O` in curses) snaps open the +current file's directory and `Ctrl+U` (`⌘U` | `^U`) snaps open *~/.textadept/*. +Snapopen is pretty limited from the "Tools -> Snapopen" menu, but more versatile +in [scripts][]. [scripts]: api/io.html#snapopen @@ -112,31 +110,31 @@ pretty limited from the menu, but more versatile in [scripts][]. `Ctrl+U` (`⌘U ### Split Views -Textadept allows you to split the editor window as many times as you like both -horizontally and vertically. `Ctrl+Alt+S` or `Ctrl+Alt+H` splits horizontally -into top and bottom views and `Ctrl+Alt+V` splits vertically (`^S` and `^V` -respectively on Mac OSX | N/A in curses) into side-by-side views. You can resize -the splitter bar by clicking and dragging with the mouse or using `Ctrl+Alt++` -and `Ctrl+Alt+-` (`^+` and `^-` | N/A). The same file can be opened in multiple -views. +Textadept allows you to split the editor window an unlimited number of times +both horizontally and vertically. `Ctrl+Alt+S` or `Ctrl+Alt+H` splits +horizontally into top and bottom views and `Ctrl+Alt+V` splits vertically (`^S` +and `^V` respectively on Mac OSX | N/A in curses) into side-by-side views. +Clicking and dragging on the splitter bar with the mouse or pressing +`Ctrl+Alt++` and `Ctrl+Alt+-` (`^+` and `^-` | N/A) resizes the split. Textadept +supports viewing a single buffer in two or more views. -Pressing `Ctrl+Alt+N` (`^⌥⇥` on Mac OSX | N/A in curses) goes to the next view -and `Ctrl+Alt+P` (`^⌥⇧⇥` | N/A) goes to the previous one. Note: depending on the -split sequence, the order when cycling between views may be unexpected. +Pressing `Ctrl+Alt+N` (`^⌥⇥` on Mac OSX | N/A in curses) jumps to the next view +and `Ctrl+Alt+P` (`^⌥⇧⇥` | N/A) jumps the previous one. However, depending on +the split sequence, the order when cycling between views may not be linear. To unsplit a view, enter the view to keep open and press `Ctrl+Alt+W` (`^W` on Mac OSX | N/A in curses). To unsplit all views, use `Ctrl+Alt+Shift+W` (`^⇧W` | N/A). -Split views are unavailable in curses. +Textadept curses does not support split views. ### Settings Individual views have many configurable settings. Among the more useful settings are viewing line endings, handling long lines, viewing indentation guides, and -viewing whitespace. These options change how buffers in the _current_ view are -displayed. Changing a setting in one view does not change that setting in -any other split view. It will have to be done manually. +viewing whitespace. These options change how to display buffers in the _current_ +view. Changing a setting in one view does not change that setting in +any other split view. You must do it manually. #### Line Endings @@ -145,28 +143,27 @@ Normally, EOL characters ("\r" and "\n") are invisible. Pressing #### Long Lines -By default, lines with more characters than the view can show are not wrapped -into view. `Ctrl+Alt+\` (`^\` on Mac OSX | none in curses) toggles line -wrapping. +By default, lines with more characters than the view can show do not wrap into +view. `Ctrl+Alt+\` (`^\` on Mac OSX | none in curses) toggles line wrapping. #### Indentation Guides -By default, small guiding lines are shown based on indentation level. -`Ctrl+Alt+Shift+I` (`^⇧I` on Mac OSX | N/A in curses) toggles showing these -guides. +Views show small guiding lines based on indentation level by default. +`Ctrl+Alt+Shift+I` (`^⇧I` on Mac OSX | N/A in curses) toggles the visibility of +these guides. -Indentation guides are unavailable in curses. +Textadept curses does not support indentation guides. #### Whitespace Normally, whitespace characters, tabs and spaces, are invisible. Pressing `Ctrl+Alt+Shift+S` (`^⇧S` on Mac OSX | none in curses) toggles their visibility. -Visible spaces are shown as dots and visible tabs are shown as arrows. +Visible spaces show up as dots and visible tabs show up as arrows. ### Zoom -You can temporarily increase or decrease the font size in a view with `Ctrl+=` +To temporarily increase or decrease the font size in a view, press `Ctrl+=` (`⌘=` on Mac OSX | N/A in curses) and `Ctrl+-` (`⌘-` | N/A) respectively. `Ctrl+0` (`⌘0` | N/A) resets the zoom. -Zooming is unavailable in curses. +Textadept curses does not support zooming. diff --git a/doc/05_FileNavigation.md b/doc/05_FileNavigation.md index 4c543e87..bd3084f3 100644 --- a/doc/05_FileNavigation.md +++ b/doc/05_FileNavigation.md @@ -2,28 +2,27 @@ ## Basic Movements -Textadept supports the key bindings you are accustomed to for navigating text -fields on your platform. The arrow keys move the caret in a particular -direction, `Ctrl+Left` and `Ctrl+Right` (`^⇠` and `^⇢` on Mac OSX | `^Left` and -`^Right` in curses) move by words, `PgUp` and `PgDn` (`⇞` and `⇟` | `PgUp` and -`PgDn`) move by pages, etc. Mac OSX and curses also support some Bash-style -bindings like `^B`, `^F`, `^P`, `^N`, `^A`, and `^E`. A complete list of -movement bindings is found in the "Movement" section of the -[key bindings list][]. +Textadept implements the customary key bindings for navigating text fields on +the current platform. The arrow keys move the caret in a particular direction, +`Ctrl+Left` and `Ctrl+Right` (`^⇠` and `^⇢` on Mac OSX | `^Left` and `^Right` in +curses) move by words, `PgUp` and `PgDn` (`⇞` and `⇟` | `PgUp` and `PgDn`) move +by pages, etc. Mac OSX and curses also handle some Bash-style bindings like +`^B`, `^F`, `^P`, `^N`, `^A`, and `^E`. The "Movement" section of the +[key bindings list][] lists all movement bindings. [key bindings list]: api/_M.textadept.keys.html#Key.Bindings ## Brace Match -By default, Textadept will highlight the matching brace characters under the -caret : '(', ')', '[', ']', '{', and '}'. Pressing `Ctrl+M` (`^M` on Mac OSX | -`M-M` in curses) moves the caret to that matching brace. +By default, Textadept highlights the matching brace characters under the caret: +'(', ')', '[', ']', '{', and '}'. Pressing `Ctrl+M` (`^M` on Mac OSX | `M-M` in +curses) moves the caret to the matching brace.  ## Bookmarks -You can place bookmarks on lines in buffers to jump back to them later. +Textadept supports bookmarking buffer lines to jump back to them later. `Ctrl+F2` (`⌘F2` on Mac OSX | `F1` in curses) toggles a bookmark on the current line, `F2` jumps to the next bookmarked line, `Shift+F2` (`⇧F2` | `F3`) jumps to the previously bookmarked line, `Alt+F2` (`⌥F2` | `F4`) jumps to the bookmark @@ -33,5 +32,5 @@ in the current buffer. ## Goto Line To jump to a specific line in a file, press `Ctrl+J` (`⌘J` on Mac OSX | `^J` in -curses) and specify the line number in the prompt and press `Enter` (`↩` | -`Enter`) or select `OK`. +curses), specify the line number in the prompt, and press `Enter` (`↩` | +`Enter`) or click `Ok`. diff --git a/doc/06_AdeptEditing.md b/doc/06_AdeptEditing.md index 86a3901e..518fc1bc 100644 --- a/doc/06_AdeptEditing.md +++ b/doc/06_AdeptEditing.md @@ -2,29 +2,28 @@ ## Basic Editing -Textadept has many basic editing features you are familiar with: basic text -entry, undo/redo, clipboard manipulation, deleting characters and words, -duplicating lines, joining lines, and transposing characters. These are -accessible from the top-level "Edit" menu and have associated key bindings. -Some of the basic editing features you may not be familiar with are discussed -below. +Textadept features many common, basic editing features: inserting text, +undo/redo, manipulating the clipboard, deleting characters and words, +duplicating lines, joining lines, and transposing characters. The top-level +"Edit" menu contains these actions and lists their associated key bindings. The +manual discusses more elaborate editing features below. ### Autopaired Characters 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 `Bksp` (`⌫` on Mac OSX | `Bksp` in curses) over the first. Typing over -complement characters is also supported. See the [preferences][] page if you -would like to disable these features. +together in pairs. By default, Textadept automatically inserts complement +characters and allows you to type over them. Similarly, the editor deletes the +complement when you press `Bksp` (`⌫` on Mac OSX | `Bksp` in curses) over the +first. The [preferences][] page details how to disable these features if you +find them unsuitable. [preferences]: 08_Preferences.html#Generic ### Word Completion -Textadept provides buffer-based word completion. Start typing a word, press -`Ctrl+Enter` (`^⎋` on Mac OSX | `M-Enter` in curses), and a list of suggested -completions based on words in the current buffer is provided. Continuing to type +Textadept provides buffer-based word completion. Start typing a word and press +`Ctrl+Enter` (`^⎋` on Mac OSX | `M-Enter` in curses) to display a list of +suggested completions based on words in the current buffer. Continuing to type changes the suggestion. Press `Enter` (`↩` | `Enter`) to complete the selected word. @@ -32,54 +31,55 @@ word. ### Virtual Space Mode -Virtual space (freehand) mode is enabled and disabled with `Ctrl+Alt+Shift+V` -(`^⇧V` in Mac OSX | none in curses). When enabled, caret movement is not -restricted by line endings. +Pressing `Ctrl+Alt+Shift+V` (`^⇧V` in Mac OSX | none in curses) enables and +disables Virtual space (freehand) mode. When enabled, line endings do not +restrict caret movement. ### Overwrite Mode -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. +Enable and disable overwrite mode with the `Insert` key. When enabled, typing +overwrites existing characters in the buffer rather than inserting the typed +characters. The caret also changes to an underline in overwrite mode. ## Selections -Textadept has many ways of creating and working with selections. Basic -selections are what you get when you do things like hold the "Shift" modifier -key while pressing the arrow keys, click and drag the mouse over a range of -text, or press `Ctrl+A` (`⌘A` | `M-A`) for "Select All". More advanced -selections like multiple and rectangular selections are more complicated to -create, but have powerful uses. +Textadept includes many ways of creating and working with selections. Creating +basic selections entails holding down the "Shift" modifier key while pressing +the arrow keys, clicking and dragging the mouse over a range of text, or +pressing `Ctrl+A` (`⌘A` | `M-A`) to select all text. Creating more advanced +selections like multiple and rectangular selections requires slightly more +effort, but has powerful uses. ### Multiple Selection Clicking the mouse at a point in the buffer while holding the "Control" modifier key places an additional caret at that point. Clicking and dragging while -holding the same modifier creates multiple selections. When you start typing, -the text is mirrored at each selection. +holding the same modifier creates multiple selections. Textadept will now mirror +typed text at each selection. -Creating multiple selections with the mouse is currently unavailable in curses. +Textadept curses does not support creating multiple selections with the mouse. ### Rectangular Selection Holding `Alt+Shift` (`⌥⇧` on Mac OSX | `M-S-` in curses) and pressing the arrow -keys enables rectangular selections to be made. Start typing to type on each -line. You can also hold the "Alt" modifier key ("Super" on Linux) while clicking -and dragging the mouse to create rectangular selections. +keys creates a rectangular selection. A rectangular selection spanning multiple +lines allows typing on each line. Holding the `Alt` modifier key (`Super` on +Linux) while clicking and dragging the mouse also creates a rectangular +selection.   -Note: In some Linux environments, the `Alt+Shift+Arrow` combinations are used by -the window manager and may need to be reconfigured. Also, `Super+Mouse` is used -because `Alt+Mouse` generally moves windows. If you prefer to use "Alt", you can -change [`buffer.rectangular_selection_modifier`][] in your [settings][]. The -"Super" modifier key is usually defined as the left "Windows" key, but may need -to be reconfigured too. +Note: In some Linux environments, the window manager consumes `Alt+Shift+Arrow` +combinations so Textadept may need reconfiguring. Also, Textadept uses +`Super+Mouse` because `Alt+Mouse` generally moves windows. (Your window manager +usually defines the `Super` modifier key as the left "Windows" key.) If you +prefer to use `Alt`, change [`buffer.rectangular_selection_modifier`][] in your +[settings][]. -Creating rectangular selections with the mouse is currently unavailable in -curses. +Textadept curses does not support creating rectangular selections with the +mouse. [`buffer.rectangular_selection_modifier`]: api/buffer.html#rectangular_selection_modifier [settings]: 08_Preferences.html#Buffer.Settings @@ -92,37 +92,35 @@ selection to the brace character's matching brace. ### Entity Selection -Textadept allows you to select many different entities from the caret. For +Textadept allows the selection of many different entities from the caret. For example, `Ctrl+"` (`^"` on Mac OSX | `M-"` in curses) selects all characters in -a double-quoted range. Typing `Ctrl++` (`^+` | `M-+`) as a follow-up selects the -double-quotes too. See the "Edit -> Select In..." menu for available entities -and their key bindings. +a double-quoted range. Typing it again selects the double-quotes too. The +"Edit -> Select In..." menu lists all selectable entities with their key +bindings. ### Marks In curses, since some terminals do not recognize certain key combinations like -`Shift+Arrow` for making selections, you can use marks to create selections. -Create a mark at the current caret position with `^^`. Then use regular movement -keys like the arrows, page up/down, and home/end to extend the selection in one -direction. Pressing `^]` swaps the current caret position with the original mark -position so you can extend the selection in the opposite direction. Any time you -type text, delete text, or run a command that does either, the mark is removed -and ordinary navigation is restored. You can also press `^^` again to stop -selecting text. +`Shift+Arrow` for making selections, marks can create selections. Create a mark +at the current caret position with `^^`. Then use regular movement keys like the +arrows, page up/down, and home/end to extend the selection in one direction. +Pressing `^]` swaps the current caret position with the original mark position +in order to extend the selection in the opposite direction. Typing text, +deleting text, or running a command that does either, removes the mark and +restores ordinary navigation. Pressing `^^` again also stops selecting text. -Marks are only supported in curses. +Only Textadept curses supports marks. ### Transforms #### Enclose Entities -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 bindings. - -If no text is selected, the word to the left of the caret is enclosed. For -example, pressing `Alt+<` (`^<` on Mac OSX | `M->` in curses) at the end of a -word encloses it in XML tags. +As a complement to selecting entities, Textadept allows the enclosure of text in +entities. The "Edit -> Selection -> Enclose In..." menu lists all enclosing +entities with their key bindings. Each action encloses either the currently +selected text or the word to the left of the caret. For example, pressing +`Alt+<` (`^<` on Mac OSX | `M->` in curses) at the end of a word encloses it in +XML tags. #### Change Case @@ -132,69 +130,69 @@ letters respectively. #### Change Indent Level -The amount of indentation for a selected set of lines is increased by pressing -`Tab` (`⇥` on Mac OSX | `Tab` in curses) and decreased by pressing `Shift+Tab` -(`⇧⇥` | `S-Tab`). Whole lines do not have to be selected. As long as any part of -a line is selected, the entire line is eligible for indenting/dedenting. Using -these key sequences when no selection is present does not have the same effect. +Increase the amount of indentation for a selected set of lines by pressing `Tab` +(`⇥` on Mac OSX | `Tab` in curses). `Shift+Tab` (`⇧⇥` | `S-Tab`) decreases it. +You do not have to select whole lines. Selecting any part of a line renders the +entire line eligible for indenting/dedenting. Using these key sequences when no +selection is present does not have the same effect. #### Move Lines -Selected lines are moved with the `Ctrl+Shift+Up` and `Ctrl+Shift+Down` (`^⇧⇡` -and `^⇧⇣` on Mac OSX | `S-^Up` and `S-^Down` in curses) keys. Like with changing -indent level, as long as any part of a line is selected, the entire line is -eligible for moving. +Move selected lines up and down with the `Ctrl+Shift+Up` and `Ctrl+Shift+Down` +(`^⇧⇡` and `^⇧⇣` on Mac OSX | `S-^Up` and `S-^Down` in curses) keys, +respectively. Like with changing indent level, selecting any part of a line +renders the entire line eligible for moving. ## Find & Replace `Ctrl+F` (`⌘F` on Mac OSX | `M-F` or `M-S-F` in curses) brings up the Find & Replace pane. In addition to offering the usual find and replace with "Match -Case" and "Whole Word" options and find/replace history, 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'))` upper cases 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. +Case" and "Whole Word" options and find/replace history, Textadept supports +finding with [Lua patterns][] and replacing with Lua captures and even Lua code! +For example: replacing all `(%w+)` with `%(string.upper('%1'))` upper cases all +words in the buffer. Replacement text only recognizes Lua captures (`%`_`n`_) +from a Lua pattern search, but always allows embedded Lua code enclosed in +`%()`. Note the `Ctrl+G`, `Ctrl+Shift+G`, `Ctrl+Alt+R`, `Ctrl+Alt+Shift+R` key bindings for find next, find previous, replace, and replace all (`⌘G`, `⌘⇧G`, `^R`, `^⇧R` respectively on Mac OSX | `M-G`, `M-S-G`, `M-R`, `M-S-R` in curses) only work -when the Find & Replace pane is hidden. When the pane is visible in the GUI +after hiding the Find & Replace pane. For at least the English locale in the GUI version, use the button mnemonics: `Alt+N`, `Alt+P`, `Alt+R`, and `Alt+A` (`⌘N`, -`⌘P`, `⌘R`, `⌘A` | N/A) for English locale. +`⌘P`, `⌘R`, `⌘A` | N/A) after bringing up the pane. In the curses version, `Tab` and `S-Tab` toggles between the find next, find previous, replace, and replace all buttons; `Up` and `Down` arrows switch between the find and replace text fields; `^P` and `^N` cycles through history; and `F1-F4` toggles find options. -Pressing `Esc` (`⎋` | `Esc`) hides the pane when you are finished. +Pressing `Esc` (`⎋` | `Esc`) hides the pane after you finish with it. [Lua patterns]: 14_Appendix.html#Lua.Patterns ### 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". +By default, "Replace All" replaces all text in the buffer. Selecting a block of +text and then "Replace All" replaces all text in the selection. ### Find in Files `Ctrl+Shift+F` brings up Find in Files (`⌘⇧F` on Mac OSX | none in curses) 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` | none) key -bindings. 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 +prompts for a directory to search. A new buffer lists the search results. +Double-clicking a search result jumps to it in the file, as do the the +`Ctrl+Alt+G` and `Ctrl+Alt+Shift+G` (`^⌘G` and `^⌘⇧G` | none) key bindings. +Textadept does not support replacing in files directly. You must "Find in Files" +first, and then "Replace All" for each file containing a result. The "Match Case", "Whole Word", and "Lua pattern" flags still apply. -_Warning_: currently, the only way to specify a file-type filter is through the -[find API][] and even though the default filter excludes common binary files +_Warning_: currently, the [find API][] provides the only means to specify a +file-type filter. While the default filter excludes many common binary files and version control folders from searches, Find in Files could still scan unrecognized binary files or large, unwanted sub-directories. Searches also block Textadept from receiving additional input, making the interface temporarily unresponsive. Searching large directories or projects can be very -time consuming and frustrating, so using a specialized, external tool such as -[ack][] is recommended. +time consuming and frustrating, so you may prefer to use a specialized, external +tool such as [ack][].  @@ -203,57 +201,55 @@ time consuming and frustrating, so using a specialized, external tool such as ### Incremental Find -You can start an incremental search by pressing `Ctrl+Alt+F` (`^⌘F` on Mac OSX | -`M-^F` in curses). Incremental search searches the buffer as you type. Only the -"Match Case" option is recognized. Pressing `Esc` (`⎋` | `Esc`) stops the +Start an incremental search by pressing `Ctrl+Alt+F` (`^⌘F` on Mac OSX | `M-^F` +in curses). Incremental search searches the buffer as you type, but only +recognizes the "Match Case" find option. Pressing `Esc` (`⎋` | `Esc`) stops the search. ## Source Code Editing -Textadept would not be a programmer's editor without some features for editing -source code. Textadept understands the syntax and structure of more than 80 -different programming languages and recognizes hundreds of file types. It uses -this knowledge to make viewing and editing code faster and easier. +Being a programmer's editor, Textadept excels at editing source code. It +understands the syntax and structure of more than 80 different programming +languages and recognizes hundreds of file types. Textadept uses this knowledge +to make viewing and editing code faster and easier. ### Lexers -When you open a file, chances are that Textadept will identify the programming -language associated with that file and set a "lexer" to highlight syntactic -elements of the code. You can set or change the lexer manually by pressing -`Ctrl+Shift+L` (`⌘⇧L` on Mac OSX | `M-S-L` in curses) and selecting a lexer from -the list. You can customize how Textadept recognizes files in your -[file type preferences][]. +Upon opening a file, Textadept attempts to identify the programming language +associated with it and set a "lexer" to highlight syntactic elements of the +code. Pressing `Ctrl+Shift+L` (`⌘⇧L` on Mac OSX | `M-S-L` in curses) and +selecting a lexer from the list manually sets the lexer instead. Your +[file type preferences][] customize how Textadept recognizes files. -Lexers can sometimes lose track of their context while you are editing and +Occasionally while you edit, lexers may lose track of their context and highlight syntax incorrectly. Pressing `F5` triggers a full redraw. [file type preferences]: 08_Preferences.html#File.Types ### Code Folding -Some lexers support "code folding", where blocks of code can be temporarily -hidden, making viewing easier. Fold points are denoted by arrows in the margin -to the left of the code. Clicking on one toggles the folding for that block of -code. You can also press `Ctrl+*` (`⌘*` on Mac OSX | `M-*` in curses) to toggle -the fold point on the current line. +Some lexers support "code folding", the act of temporarily hiding blocks of code +in order to make viewing easier. Arrows in the margin to the left of the code +denote fold points. Clicking on one toggles the folding for that block of code. +Pressing `Ctrl+*` (`⌘*` on Mac OSX | `M-*` in curses) also toggles the fold +point on the current line.  ### 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 | N/A in curses). This is -useful to show occurrences of a variable name, but is not limited to source -code. +To highlight all occurrences of a given word, such as a variable name, put the +caret over the word and press `Ctrl+Alt+Shift+H` (`⌘⇧H` on Mac OSX | N/A in +curses). This feature also works for plain text.  ### Adeptsense Textadept has the capability to autocomplete symbols for programming languages -and display API documentation. Symbol completion is available by pressing -`Ctrl+Space` (`⌥⎋` on Mac OSX | `^Space` in curses). Documentation for symbols -is available with `Ctrl+H` (`^H` | `M-H` or `M-S-H`). Note: In order for this +and display API documentation. Pressing `Ctrl+Space` (`⌥⎋` on Mac OSX | `^Space` +in curses) completes the current symbol and `Ctrl+H` (`^H` | `M-H` or `M-S-H`) +shows any known documentation on the current symbol. Note: In order for this feature to work, the language you are working with must have an [Adeptsense][] defined. [Language-specific modules][] usually [define Adeptsenses][]. All of the [official][] Textadept language-specific modules have Adeptsenses. @@ -271,36 +267,36 @@ the [official][] Textadept language-specific modules have Adeptsenses. ### Snippets -Snippets are essentially pieces of text inserted into a document. However, -snippets are not limited to static text. They can be dynamic templates which -contain placeholders for further user input, can mirror or transform those user -inputs, and/or execute arbitrary code. Snippets are useful for rapidly +Snippets are essentially pieces of text inserted into source code or plain text. +However, snippets are not bound to static text. They can be dynamic templates +which contain placeholders for further user input, can mirror or transform those +user inputs, and/or can execute arbitrary code. Snippets are useful for rapidly constructing blocks of code such as control structures, method calls, and function declarations. Press `Ctrl+K` (`⌥⇥` on Mac OSX | `M-K` in curses) for a -list of available snippets. Snippets are composed of trigger word and snippet -text. Instead of manually selecting a snippet, you can type its trigger word +list of available snippets. A snippet consists of a trigger word and snippet +text. Instead of manually selecting a snippet to insert, type its trigger word followed by the `Tab` (`⇥` | `Tab`) key. Subsequent presses of `Tab` (`⇥` | `Tab`) cause the caret to enter placeholders in sequential order, `Shift+Tab` (`⇧⇥` | `S-Tab`) goes back to the previous placeholder, and `Ctrl+Shift+K` -(`⌥⇧⇥` | `M-S-K`) cancels the current snippet. Snippets can be nested (inserted -from within another snippet) and are not limited to source code. -Language-specific modules usually [define snippets][], but you can create your -own custom snippets in your [snippet preferences][]. +(`⌥⇧⇥` | `M-S-K`) cancels the current snippet. Textadept supports nested +snippets, snippets inserted from within another snippet. Language-specific +modules usually define their [own set][] of snippets, but your +[snippet preferences][] can define some too.   -[define snippets]: api/_M.html#Snippets +[own set]: api/_M.html#Snippets [snippet preferences]: 08_Preferences.html#Snippets ### Toggle Comments Pressing `Ctrl+/` (`⌘/` on Mac OSX | `M-/` in curses) comments or uncomments the -code on the selected lines. As long as any part of a line is selected, the -entire line will be commented or uncommented. Note: In order for this feature to +code on the selected lines. Selecting any part of a line renders the entire line +eligible for commenting or uncommenting. Note: In order for this feature to work, the language you are working with must have its comment prefix defined. -Language-specific modules usually [define prefixes][], but it can also be done +Language-specific modules usually [define prefixes][], but you can do so [manually][] in your [user-init file][]. [define prefixes]: api/_M.html#Block.Comment diff --git a/doc/07_Modules.md b/doc/07_Modules.md index 62553287..297a0ba5 100644 --- a/doc/07_Modules.md +++ b/doc/07_Modules.md @@ -10,9 +10,9 @@ features for a specific programming language. Generic modules have a broad scope and are usually available 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 -bindings, 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. +bindings, menus, snippets, etc.). In general, Textadept should load these kinds +of modules on startup. See the [preferences][] page for instructions on how to +do this. [textadept module]: api/_M.textadept.html [preferences]: 08_Preferences.html#Loading.Modules @@ -20,26 +20,27 @@ modules when Textadept starts. ## Language-Specific Language-specific modules have a scope limited to a single programming language. -The name of the module is named after the language's lexer in the *lexers/* -directory and is automatically loaded when editing source code in that +The module's name matches the language's lexer in the *lexers/* directory. +Textadept automatically loads the module when editing source code in that particular language. In addition to the source code editing features discussed -previously, these kinds of modules typically also have shell commands for +previously, these kinds of modules typically also define shell commands for running and compiling code, indentation settings, custom key bindings, and -perhaps a custom context menu. These features are discussed below. +perhaps a custom context menu. The manual discusses these features below. ### Compile and Run -Most language-specific modules have a command that compiles and/or runs the code +Most language-specific modules specify commands that compile and/or run the code in the current file. Pressing `Ctrl+Shift+R` (`⌘⇧R` on Mac OSX | `M-^R` in curses) executes the command for compiling code and `Ctrl+R` (`⌘R` | `^R`) -executes the command for running code. Any recognized errors in the output are -marked. Pressing `Ctrl+Alt+E` (`^⌘E` | `M-X`) attempts to jump to the source of -the next recognized error and `Ctrl+Alt+Shift+E` (`^⌘⇧E` | `M-S-X`) attempts to -jump to the previous one. Double-clicking on errors will also jump to their -sources. Note: In order for these features to work, the language you are working -with must have its compile and run commands and error format defined. If the -language-specific module does not exist or does not [define][] commands or an -error format, it can be done [manually][] in your [user-init file][]. +executes the command for running code. A new buffer shows the output from the +command and marks any recognized errors. Pressing `Ctrl+Alt+E` (`^⌘E` | `M-X`) +attempts to jump to the source of the next recognized error and +`Ctrl+Alt+Shift+E` (`^⌘⇧E` | `M-S-X`) attempts to jump to the previous one. +Double-clicking on errors also jumps to their sources. Note: In order for these +features to work, the language you are working with must have its compile and +run commands and error format defined. If the language-specific module does not +exist or does not [define][] commands or an error format, you can do so +[manually][] in your [user-init file][].  @@ -51,18 +52,18 @@ error format, it can be done [manually][] in your [user-init file][]. Some programming languages have style guidelines for indentation and/or line endings which differ from Textadept's defaults. In this case, language-specific -modules [set][] these preferences. If you wish to change them or use your own -preferences, see the [language module preferences][] section. +modules [set][] these preferences. You can do so manually with your +[language module preferences][]. [set]: api/_M.html#Buffer.Properties [language module preferences]: 08_Preferences.html#Language-Specific ### Key Bindings -Most language-specific modules have a set of key bindings for -[custom commands][]. See the module's [LuaDoc][] or code to find out which key -bindings are assigned. They are typically stored in the `Ctrl+L` (`⌘L` on Mac -OSX | `M-L` in curses) key chain prefix. +Most language-specific modules assign a set of key bindings to +[custom commands][]. The module's [LuaDoc][] or code lists which key bindings +map to which commands. The `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in curses) key +chain prefix typically houses them. [custom commands]: api/_M.html#Commands [LuaDoc]: api/index.html @@ -74,13 +75,14 @@ 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. +Textadept has a set of officially supported language modules available as a +separate download from the Textadept downloads page with their sources hosted +[here][]. To upgrade to the most recent version of a module, 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. -For now, user-created modules are obtained from the [wiki][]. +For now, the [wiki][] hosts third-party, user-created modules. [here]: http://foicica.com/hg [Mercurial]: http://mercurial.selenic.com @@ -88,14 +90,14 @@ For now, user-created modules are obtained from the [wiki][]. ## Installing Modules -If you do not have write permissions for the directory Textadept is installed -in, place the module in your *~/.textadept/modules/* folder and replace all -instances of `_HOME` with `_USERHOME` in the module's *init.lua*. 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. +If you do not have write permissions in Textadept's installed location, place +the module in your *~/.textadept/modules/* folder and replace all instances of +`_HOME` with `_USERHOME` in the module's *init.lua*. Putting all custom or +user-created modules in your *~/.textadept/modules/* directory prevents the +possibility of overwriting them 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, Textadept loads that one instead of its +own. ## Developing Modules diff --git a/doc/08_Preferences.md b/doc/08_Preferences.md index d1acabc5..447d7ef9 100644 --- a/doc/08_Preferences.md +++ b/doc/08_Preferences.md @@ -1,6 +1,6 @@ # Preferences -At this point it is assumed you are at least familiar with the basics of +At this point the manual assumes 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 @@ -8,36 +8,36 @@ At this point it is assumed you are at least familiar with the basics of ## User Init Textadept executes a *~/.textadept/init.lua*, your user-init file, on startup. -If this file does not exist, Textadept creates it for you. You can use the file +If this file does not exist, Textadept creates it for you. This file allows you to indicate what you want Textadept to do when the application starts, such as -changing the settings of existing modules, loading new ones, and/or running -plain Lua code. +change the settings of existing modules, load new ones, and/or run plain Lua +code. ### Modules -It is never recommended to modify the default modules that come with Textadept, -even if you just want to change an option in a generic module, modify the buffer +Try to refrain from modifying the default modules that come with Textadept, even +if you just want to change an option in a generic module, modify the buffer settings for a language-specific module, edit file types, or add a small bit of -custom code. Those changes may be overwritten when you upgrade Textadept to a -newer version. Instead you have two options: load your own module instead of the -default one, or run your custom module code after the default module loads. For -the most part you will want to use the second option because it is simpler and -more compatible with future releases. Both options are discussed below in the -context of generic and language-specific modules. +custom code. Upgrading Textadept to a new version may overwrite those changes. +Instead you have two options: load your own module instead of the default one, +or run your custom module code after the default module loads. For the most +part, use the second option because it is simpler and more compatible with +future releases. The manual discusses both options below in the context of +generic and language-specific modules. #### Generic -Many of Textadept's generic modules have settings you can change from -*~/.textadept/init.lua* after the module is loaded. These settings are viewed -from module's [LuaDoc][]. For example, to disable character autopairing with -typeover and stripping whitespace on save, your *~/.textadept/init.lua* would -contain: +Many of Textadept's generic modules have configurable settings changeable from +*~/.textadept/init.lua* after Textadept loads the module. The module's +[LuaDoc][] lists these settings. For example, to disable character autopairing +with typeover and stripping whitespace on save, add the following to your +*~/.textadept/init.lua*: _M.textadept.editing.AUTOPAIR = false _M.textadept.editing.TYPEOVER_CHARS = false _M.textadept.editing.STRIP_WHITESPACE_ON_SAVE = false -Now suppose you wanted to load all of Textadept's default modules except for the +Now suppose you want to load all of Textadept's default modules except for the menu. You cannot do this after-the-fact from *~/.textadept/init.lua*. Instead you need Textadept to load your own module rather than the default one. Copy the `textadept` module's *init.lua* (located in the *modules/textadept/* directory) @@ -49,11 +49,11 @@ to --M.menu = require 'textadept.menu' -Now when Textadept looks for *modules/textadept/init.lua*, it will load yours -in place of its own, and load everything but the menu. If instead you wanted to -completely change the menu structure, you would first create a new *menu.lua* -and then put it in *~/.textadept/modules/textadept/*. Textadept will now load -your *menu.lua* rather than its own. +Now when Textadept looks for *modules/textadept/init.lua*, it loads yours in +place of its own, thus loading everything but the menu. If instead you want to +completely change the menu structure, first create a new *menu.lua* and then put +it in *~/.textadept/modules/textadept/*. Textadept now loads your *menu.lua* +rather than its own. [LuaDoc]: api/index.html @@ -63,21 +63,21 @@ Similar to generic modules, putting your own language-specific module in *~/.textadept/modules/* causes Textadept to load that module for editing the language's code instead of the default one in *modules/* (if the latter exists). For example, copying the default Lua language-specific module from -*modules/lua/* to *~/.textadept/modules/* causes Textadept to use that module -for editing Lua code in place of the default one. However, if you make custom +*modules/lua/* to *~/.textadept/modules/* results in Textadept loading that +module for editing Lua code in place of its own. However, if you make custom changes to that module and upgrade Textadept later, the module may no longer be -compatible. Rather than potentially wasting time merging changes, you can run -custom code independent of a module in the module's *post_init.lua* file. For -example, instead of copying the `lua` module and creating an -`events.LANGUAGE_MODULE_LOADED` event handler to use tabs, you can do this from -*~/.textadept/modules/lua/post_init.lua*: +compatible. Rather than potentially wasting time merging changes, run custom +code independent of a module in the module's *post_init.lua* file. In this case, +instead of copying the `lua` module and creating an +`events.LANGUAGE_MODULE_LOADED` event handler to use tabs, simply put the event +handler in *~/.textadept/modules/lua/post_init.lua*: events.connect(events.LANGUAGE_MODULE_LOADED, function(lang) if lang == 'lua' then buffer.use_tabs = true end end) -Similarly, you can use *post_init.lua* to change the module's -[compile and run][] commands, load more [Adeptsense tags][], and add additional +Similarly, use *post_init.lua* to change the module's [compile and run][] +commands, load more [Adeptsense tags][], and add additional [key bindings](#Key.Bindings) and [snippets](#Snippets) (instead of in *~/.textadept/init.lua*). For example: @@ -93,15 +93,15 @@ Similarly, you can use *post_init.lua* to change the module's ### Loading Modules -Suppose you created or downloaded a generic module called `foo` that you wanted -to load along with the default modules Your *~/.textadept/init.lua* would -contain the following: +After creating or downloading a generic module called `foo` that you want to +load along with the default modules, simply add the following to your +*~/.textadept/init.lua*: _M.foo = require 'foo' -Language-specific modules are loaded automatically by Textadept when a source -file of that language is opened. No additional action is required after -installing the module. +Textadept automatically loads language-specific modules when opening a source +file of that language, so simply installing the language-specific module is +sufficient. ### Key Bindings @@ -109,41 +109,41 @@ For simple changes to key bindings, *~/.textadept/init.lua* is a good place to put them. For example, maybe you want `Ctrl+Shift+C` to create a new buffer instead of `Ctrl+N`: - keys.cC = new_buffer + keys.cC = buffer.new keys.cn = nil -If you plan on redefining most key bindings, you would probably want to copy or -create a new *keys.lua* and then put it in *~/.textadept/modules/textadept/*. -You can learn more about key bindings and how to define them in the +If you plan on redefining most key bindings, copy or create a new *keys.lua* and +put it in *~/.textadept/modules/textadept/* to get Textadept to load your set +instead of its own. Learn more about key bindings and how to define them in the [key bindings LuaDoc][]. [key bindings LuaDoc]: api/keys.html ### Snippets -You can add global snippets in *~/.textadept/init.lua*, such as: +Define your own global snippets in *~/.textadept/init.lua*, such as: snippets['file'] = '%<buffer.filename>' snippets['path'] = "%<(buffer.filename or ''):match('^.+[/\\]')>" So typing `file` or `path` and then pressing `Tab` (`⇥` on Mac OSX | `Tab` in -curses) will insert the snippet, regardless of the current programming language. -You can learn about snippet syntax in the [snippets LuaDoc][]. +curses) inserts the snippet, regardless of the current programming language. +Learn more about snippet syntax in the [snippets LuaDoc][]. [snippets LuaDoc]: api/_M.textadept.snippets.html ## Buffer Settings -Since *~/.textadept/init.lua* is only run once on startup, it is not the +Since Textadept runs *~/.textadept/init.lua* only once on startup, it is not the appropriate place to set per-buffer properties like indentation size or view-related properties like the behaviors for scrolling and autocompletion. If you do set such properties in *~/.textadept/init.lua*, those settings only apply to the first buffer and view -- subsequent buffers and split views will not inherit those settings. Instead, put your settings in a -*~/.textadept/settings.lua* file which is run each time a new buffer or split -view is created. Any settings there override Textadept's default *settings.lua* -settings. For example, to use tabs rather than spaces and have a tab size of 4 -spaces by default your *~/.textadept/settings.lua* would contain: +*~/.textadept/settings.lua* file which runs after creating a new buffer or split +view. Any settings there override Textadept's default *settings.lua* settings. +For example, to use tabs rather than spaces and have a tab size of 4 spaces by +default, your *~/.textadept/settings.lua* would contain: buffer.tab_width = 4 buffer.use_tabs = true @@ -151,11 +151,10 @@ spaces by default your *~/.textadept/settings.lua* would contain: (Remember that in order to have per-filetype properties, you need to have a [language-specific module][].) -You can use Textadept's *settings.lua* as a reference to see what properties are -available. It also has many commented out properties that you can copy to your -*~/.textadept/settings.lua* and uncomment to turn on or change the value of. You -can use [Adeptsense][] to view a property's documentation or read the -[LuaDoc][]. +Textadept's *settings.lua* is a good reference to see available properties to +set. It also has many commented out properties that you can copy to your +*~/.textadept/settings.lua* and uncomment to turn on or change the value of. Use +[Adeptsense][] to view a property's documentation or read the [LuaDoc][]. [language-specific module]: 07_Modules.html#Buffer.Properties [Adeptsense]: 06_AdeptEditing.html#Adeptsense @@ -164,12 +163,12 @@ can use [Adeptsense][] to view a property's documentation or read the ## Locale Textadept attempts to auto-detect your locale settings using the "$LANG" -environment variable. If it is unsuccessful, the English locale is used by -default. To set the locale manually, copy the desired locale file from the -*core/locales/* folder to *~/.textadept/locale.conf*. If your language is not -yet supported by Textadept, please translate the English messages in -*core/locale.conf* to your language and send the modified *locale.conf* file to -[me][]. I will include it in a future release. +environment variable, falling back on the English locale. To set the locale +manually, copy the desired locale file from the *core/locales/* folder to +*~/.textadept/locale.conf*. If Textadept does not support your language yet, +please translate the English messages in *core/locale.conf* to your language and +send the modified *locale.conf* file to [me][]. I will include it in a future +release. [me]: README.html#Contact @@ -182,8 +181,8 @@ following: * Keywords in the file's shebang ("#!/path/to/exe") line. * A pattern that matches the text of the file's first line. -Built-in file types are located in *modules/textadept/mime_types.conf*. You -can override or add to them in your *~/.textadept/mime_types.conf*: +*modules/textadept/mime_types.conf* contains built-in file types. Override or +add to them in your *~/.textadept/mime_types.conf*: % Recognize .luadoc files as Lua code. luadoc lua @@ -216,8 +215,8 @@ lexer is: /pattern lexer -[Lua pattern syntax][] is used. Only the last space, the one separating the -pattern from the lexer, is significant. No spaces in the pattern need to be -escaped. +Patterns use [Lua pattern syntax][] with only the last space, the one separating +the pattern from the lexer, being significant. No spaces in the pattern need +escaping. [Lua pattern syntax]: 14_Appendix.html#Lua.Patterns diff --git a/doc/09_Themes.md b/doc/09_Themes.md index 73f4c612..7ea1eec6 100644 --- a/doc/09_Themes.md +++ b/doc/09_Themes.md @@ -1,8 +1,8 @@ # Themes -Textadept's look and feel is customized with themes. The themes that come with -Textadept are "light", "dark", and "term". By default the "light" theme is used -for the GUI version and "term" for the terminal version. +Themes customize Textadept's look and feel. The editor's built-in themes are +"light", "dark", and "term". The GUI version uses "light" as its default and the +terminal version uses "term". <span style="display: block; clear: right;"></span> @@ -12,11 +12,11 @@ for the GUI version and "term" for the terminal version.  -Each theme is a single Lua file. It is recommended to put custom or downloaded -themes in your *~/.textadept/themes/* directory so they will not be overwritten -when you update Textadept. Also, themes in that directory override any themes in +Each theme is a single Lua file. Putting custom or downloaded themes in your +*~/.textadept/themes/* directory prevents you from overwriting them when you +update Textadept. Also, 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. +theme, Textadept loads that one instead of its own. Themes contain color definitions and definitions for how to highlight (or "style") syntactic elements like comments, strings, and keywords in programming @@ -24,19 +24,17 @@ languages. These [definitions][] apply universally to all programming language elements, resulting in a single, unified theme. Themes also set view-related editor properties like caret and selection colors. -In the terminal version of Textadept, colors are determined by your terminal -emulator's settings. The only colors recognized by Textadept are the standard -black, red, green, yellow, blue, magenta, cyan, white, and bold variants of -those colors. How your terminal chooses to display these colors is up to your -terminal settings. However, you can still customize which colors are used for -particular styles. +Note: The only colors that the terminal version of Textadept recognizes are the +standard black, red, green, yellow, blue, magenta, cyan, white, and bold +variants of those colors. Your terminal emulator's settings determine how to +display these standard colors. [definitions]: api/lexer.html#Styles.and.Styling ## Switch Themes -You can switch between or reload themes using `Ctrl+Shift+T` (`⌘⇧T` on Mac OSX | -none in curses). You can set that theme to be the default one by putting +Switch between or reload themes using `Ctrl+Shift+T` (`⌘⇧T` on Mac OSX | none in +curses). Set that theme to be the default one by putting gui.set_theme('name') @@ -48,8 +46,8 @@ somewhere in your [*~/.textadept/init.lua*][]. 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: +"textadept". For example, style all text fields with a "textadept-entry-style" +like this: widget "textadept*GtkEntry*" style "textadept-entry-style" @@ -57,7 +55,7 @@ would be done like this: ## 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. +For now, the [wiki][] hosts third-party, user-created themes. The classic +"dark", "light", and "scite" themes prior to version 4.3 are there too. [wiki]: http://foicica.com/wiki/textadept diff --git a/doc/10_Advanced.md b/doc/10_Advanced.md index bc3a0ab7..9d921164 100644 --- a/doc/10_Advanced.md +++ b/doc/10_Advanced.md @@ -2,16 +2,16 @@ ## Command Entry -Access to the Lua state is available through the command entry. Press `Ctrl+E` -(`⌘E` on Mac OSX | `M-C` in curses) to access it. It is useful for debugging, +The command entry grants access to Textadept's Lua state. Press `Ctrl+E` (`⌘E` +on Mac OSX | `M-C` in curses) to display the entry. 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 available commands, see the [Lua API][]. Abbreviated commands for -[`buffer`][], [`view`][] and [`gui`][] are available: the command -`buffer:append_text('foo')` can be shortened to `append_text('foo')`. Therefore, -use `_G.print()` for Lua's `print()` since [`gui.print()`][] is shortened to -`print()`. You can also run commands on startup using the `-e` and `--execute` -command line switches. +instability in Textadept's Lua state, you will probably succeed so be careful. +The [Lua API][] lists available commands. The command entry provides abbreviated +commands for [`buffer`][], [`view`][] and [`gui`][]: you may reduce the +`buffer:append_text('foo')` command to `append_text('foo')`. Therefore, use +`_G.print()` for Lua's `print()` since `print()` expands to [`gui.print()`][]. +These commands are runnable on startup using the `-e` and `--execute` command +line switches.  @@ -23,18 +23,18 @@ command line switches. ### Tab Completion -Tab-completion for functions, variables, tables, etc. is available. Press the -`Tab` (`⇥` on Mac OSX | `Tab` in curses) key to display a list of available -completions. Use the arrow keys to make a selection and press `Enter` (`↩` | -`Enter`) to insert it. +The command entry also provides tab-completion for functions, variables, tables, +etc. Press the `Tab` (`⇥` on Mac OSX | `Tab` in curses) key to display a list of +available completions. Use the arrow keys to make a selection and press `Enter` +(`↩` | `Enter`) to insert it.  ### 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* and -*modules/textadept/keys.lua* for the implementation. +Executing Lua commands is just one of the many tools the command entry functions +as. For example, *modules/textadept/find.lua* and *modules/textadept/keys.lua* +extend it to implement [incremental search][]. [incremental search]: api/gui.find.html#find_incremental @@ -46,25 +46,26 @@ 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 bindings. It is also useful for looking up particular key bindings quickly. Note: the key bindings in the dialog do not -look like those in the menu. This different notation is how bindings are -represented internally. You can learn more about this in the [keys LuaDoc]. +look like those in the menu. Textadept uses this different notation internally. +Learn more about it in the [keys LuaDoc][]. [preferences]: 08_Preferences.html#User.Init [keys LuaDoc]: api/keys.html ## 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: +Sometimes using an existing shell command to manipulate text is easier than +using the command entry. An example would be sorting all text in a buffer (or a +selection). One way to do this from the command entry is: 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 | `^\` in curses), -enter the shell command `sort`, and hit `Enter` (`↩` | `Enter`). +A simpler way is pressing `Ctrl+|` (`⌘|` on Mac OSX | `^\` in curses), entering +the shell command `sort`, and pressing `Enter` (`↩` | `Enter`). -The standard input (stdin) for shell commands is determined as follows: +This feature determines the standard input (stdin) for shell commands 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 @@ -73,14 +74,14 @@ The standard input (stdin) for shell commands is determined as follows: * 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. +The standard output (stdout) of the command replaces the input text. ## Remote Control -Since Textadept can execute arbitrary Lua code passed via the `-e` and -`--execute` command line switches, a side-effect of [single instance][] -functionality on the platforms that support it is that you can remotely control -the original instance. For example: +Since Textadept executes arbitrary Lua code passed via the `-e` and `--execute` +command line switches, a side-effect of [single instance][] functionality on the +platforms that support it is that you can remotely control the original +instance. For example: ta ~/.textadept/init.lua & ta -e "events.emit(events.FIND, 'require')" diff --git a/doc/11_Scripting.md b/doc/11_Scripting.md index 537ca367..44a71db0 100644 --- a/doc/11_Scripting.md +++ b/doc/11_Scripting.md @@ -1,9 +1,8 @@ # Scripting -Textadept is entirely scriptable with Lua. In fact, the editor is mostly written -in Lua. As a result, Textadept has superb support for editing Lua code. Syntax -autocomplete and API documentation is available for many Textadept objects as -well as Lua's standard libraries. The [`lua` module][] also has more tools for +Since Textadept is entirely scriptable with Lua, the editor has superb support +for editing Lua code. Textadept provides syntax autocompletion and documentation +for the Lua and Textadept APIs. The [`lua` module][] also has more tools for working with Lua code.  @@ -16,55 +15,52 @@ working with Lua code. Textadept's API is heavily documented. The [API documentation][] is the ultimate resource on scripting Textadept. There are of course abundant scripting examples -since the editor is written primarily in Lua. +since the editor's internals consist primarily of Lua. [API documentation]: api/index.html ### Generating LuaDoc -You can generate Textadept-like API documentation for your own modules using the +Generate Textadept-like API documentation for your own modules using the *doc/markdowndoc.lua* [LuaDoc][] module (you must have [Discount][] installed): luadoc -d . [-t template_dir] --doclet _HOME/doc/markdowndoc [module(s)] -where `_HOME` is where Textadept is installed and `template_dir` is an optional -template directory that contains two Markdown files: *.header.md* and -*.footer.md*. (See *doc/.header.md* and *doc/.footer.md* for examples.) An -*api/* directory containing the API documentation HTML files is created in the -current directory. +where `_HOME` is the path where you installed Textadept and `template_dir` is an +optional template directory that contains two Markdown files: *.header.md* and +*.footer.md*. (See *doc/.header.md* and *doc/.footer.md* for examples.) LuaDoc +creates an *api/* directory in the current directory that contains the generated +API documentation HTML files. [LuaDoc]: http://keplerproject.github.com/luadoc/ [Discount]: http://www.pell.portland.or.us/~orc/Code/discount/ ## Lua Configuration -[Lua 5.2][] is built into Textadept. It has the same configuration (*luaconf.h*) -as vanilla Lua with the following exceptions: +Textadept contains its own copy of [Lua 5.2][] which 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`. +* `TA_LUA_PATH` and `TA_LUA_CPATH` replace the `LUA_PATH` and `LUA_CPATH` + environment variables. * `LUA_ROOT` is "/usr/" in Linux systems instead of "/usr/local/". * `LUA_PATH` and `LUA_CPATH` do not have "./?.lua" and "./?.so" in them. -* 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`.) +* No Lua 5.1 compatibility flags are set. [Lua 5.2]: http://www.lua.org/manual/5.2/ ### LuaJIT -Even though Textadept can be run with [LuaJIT][], LuaJIT is based on Lua 5.1 and -is not fully compatible with Lua 5.2. Therefore, modules and scripts should be -written to be compatible with both versions. For the most part, only Lua 5.2's -`_ENV` is not supported by LuaJIT. +Even though Textadept runs with [LuaJIT][], LuaJIT does not fully support +Lua 5.2. Therefore, try to write your modules and scripts to be compatible with +both versions. For the most part, LuaJIT only lacks Lua 5.2's new `_ENV`. [LuaJIT]: http://luajit.org ## 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. +Textadept uses the [Scintilla][] editing component. The [buffer][] part of +Textadept's API emulates the [Scintilla API][] so porting any C/C++ Scintilla +calls to Lua should not be difficult. [Scintilla]: http://scintilla.org [buffer]: api/buffer.html @@ -72,38 +68,36 @@ Scintilla calls can be ported to Lua without too much trouble. ## Textadept Structure -Because Textadept is mostly written in Lua, its Lua scripts have to be stored in +Because Textadept consists mainly of 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 interactions, and -localization. +The *core/* directory contains Textadept's core Lua modules. These modules are +essential for the application to run. They provide Textadept's Lua to C +interface, event structure, file interactions, and localization. ### Lexers -Lexer modules are responsible for the syntax highlighting of source code. They -are located in *lexers/*. +Lexer modules analyze source code for syntax highlighting. *lexers/* houses +them. ### Modules -Generic and language-specific modules for editing text and source code are -contained in *modules/*. +*modules/* contains generic and language-specific modules for editing text and +source code. ### Themes -Built-in themes to customize the look and behavior of Textadept are located in -*themes/*. +*themes/* has built-in themes that customize the look and feel of Textadept. ### User -User preferences, Lua modules, themes, and user-data are contained in the -*~/.textadept/* folder. This folder may contain *lexers/*, *modules/*, and -*themes/* sub-directories. +The *~/.textadept/* folder houses your preferences, Lua modules, themes, and +user-data. This folder may contain *lexers/*, *modules/*, and *themes/* +sub-directories. ### GTK+ -The *etc/*, *lib/*, and *share/* directories are used by GTK+ and only appear in -the Win32 and Mac OSX packages. +GTK+ uses the *etc/*, *lib/*, and *share/* directories, which only appear in the +Win32 and Mac OSX packages. diff --git a/doc/12_Compiling.md b/doc/12_Compiling.md index 2790856b..4a3dbd5e 100644 --- a/doc/12_Compiling.md +++ b/doc/12_Compiling.md @@ -7,44 +7,42 @@ as running it. ### Linux and BSD -First, Linux and BSD systems will need the [GNU C compiler][] (*gcc*) and -[GNU Make][] (*make*). Both should be available for your distribution through a -package manager. For example, Ubuntu includes these tools in the -"build-essential" package. - -Next, the GTK+ development libraries are necessary for compiling the GUI version -of Textadept. Your package manager should allow you to install them. For -Debian-based Linux distributions like Ubuntu, the package is typically called -"libgtk2.0-dev". Otherwise, compile and install GTK+ from the [GTK+ website][]. - -If you would like to compile the terminal version of Textadept, you will need -the development library for a curses implementation like ncurses. Similarly, one -should be available from your package manager. For Debian-based Linux -distributions like Ubuntu, the ncurses package is typically called -"libncurses5-dev". Otherwise, compile and install ncurses from the -[ncurses website][]. Note: you need to have the wide-character development -version of ncurses installed, which handles multibyte sequences. (Therefore, -Debian users will _also_ need "libncursesw5-dev".) - -In addition, BSD users will need to have [libiconv][] installed. +First, Linux and BSD systems need the [GNU C compiler][] (*gcc*) and +[GNU Make][] (*make*). BSD users additionally need to have [libiconv][] +installed. These should be available for your distribution through a package +manager. For example, Ubuntu includes these tools in the "build-essential" +package. + +Next, the GUI version of Textadept requires the GTK+ development libraries. +Again, your package manager should allow you to install them. Debian-based Linux +distributions like Ubuntu typically call the package "libgtk2.0-dev". Otherwise, +compile and install GTK+ from the [GTK+ website][]. + +The optional terminal version of Textadept depends on the development library +for a curses implementation like ncurses. Similarly, your package manager should +provide one. Debian-based Linux distributions like Ubuntu typically call the +ncurses package "libncurses5-dev". Otherwise, compile and install ncurses from +the [ncurses website][]. Note: you need the wide-character development version +of ncurses installed, which handles multibyte sequences. (Therefore, Debian +users _also_ need "libncursesw5-dev".) -[GTK+ website]: http://www.gtk.org/download/linux.html [GNU C compiler]: http://gcc.gnu.org [GNU Make]: http://www.gnu.org/software/make/ -[ncurses website]: http://invisible-island.net/ncurses/#download_ncurses [libiconv]: http://www.gnu.org/software/libiconv/ +[GTK+ website]: http://www.gtk.org/download/linux.html +[ncurses website]: http://invisible-island.net/ncurses/#download_ncurses ### 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, the -[GTK+ for Windows bundle][] (2.24 is recommended), and [libiconv for Windows][] -(the "Developer files" and "Binaries" zip files). To compile the terminal -(pdcurses) version, you will need my [win32curses bundle][] instead. +Compiling Textadept on Windows is no longer supported. Doing so requires a C +compiler that supports the C99 standard, the [GTK+ for Windows bundle][] +(2.24 is recommended), and [libiconv for Windows][] (the "Developer files" and +"Binaries" zip files). The terminal (pdcurses) version requires my +[win32curses bundle][] instead of GTK+ and libiconv. 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. +so, in addition to the GTK+ and/or curses bundles mentioned above, you need +[MinGW][] with the Windows header files. Your package manager should offer them. [GTK+ for Windows bundle]: http://www.gtk.org/download/win32.html [libiconv for Windows]: http://gnuwin32.sourceforge.net/packages/libiconv.htm @@ -54,8 +52,8 @@ Windows header files. They should be available from your package manager. ### Mac OSX Compiling Textadept on Mac OSX is no longer supported. The preferred way is -cross-compiling from Linux. To do so, you will need my [GTK+ for OSX bundle][] -and the [Apple Cross-compiler][] binaries. +cross-compiling from Linux. To do so, you need my [GTK+ for OSX bundle][] and +the [Apple Cross-compiler][] binaries. [GTK+ for OSX bundle]: download/gtkosx-2.24.16.zip [Apple Cross-compiler]: https://launchpad.net/~flosoft/+archive/cross-apple @@ -67,8 +65,8 @@ platform you are on, and not a platform-specific binary package. ### Linux and BSD -For Linux and BSD systems, simply run `make` in the *src/* directory. The -*textadept* and *textadeptjit* executables are created in the root directory. +For Linux and BSD systems, simply run `make` in the *src/* directory, which +creates the *textadept* and *textadeptjit* executables in the root directory. Make a symlink from them to */usr/bin/* or elsewhere in your `PATH`. Similarly, `make curses` builds *textadept-curses* and *textadeptjit-curses*. @@ -83,12 +81,12 @@ compiler flags do not include them by default. #### Installing -Textadept is self-contained, meaning it does not need to be installed and can be -run from wherever it is located. However, if you want to install Textadept like -a normal Linux application, run the usual `make` and then `make install` or -`sudo make install` depending on your privilages. The default prefix is -*/usr/local* but you can change this by setting `DESTDIR` (e.g. -`make install DESTDIR=/prefix/to/install/to`). +Textadept is self-contained, meaning you do not have to install it, and runs +from its current location. Should you choose to install Textadept like a normal +Linux application, run the usual `make` and then `make install` or +`sudo make install` commands depending on your privilages. The default prefix is +*/usr/local* but setting `DESTDIR` (e.g. +`make install DESTDIR=/prefix/to/install/to`) changes it. Similarly, `make curses` and `make curses install` installs the curses version. @@ -107,46 +105,45 @@ Similarly for the terminal version, unzip the win32curses bundle into a new suggested above to build *../textadept-curses.exe* and *../textadeptjit-curses.exe*. -Please note that a *lua51.dll* is produced for _only_ *textadeptjit.exe* and -*textadeptjit-curses.exe* because limitations on external Lua library loading do -not allow statically linking LuaJIT to Textadept. +Please note the build process produces a *lua51.dll* for _only_ +*textadeptjit.exe* and *textadeptjit-curses.exe* because limitations on external +Lua library loading do not allow statically linking LuaJIT to Textadept. ### Cross Compiling for Mac OSX When cross-compiling from within Linux, first unzip the GTK+ for OSX bundle into a new *src/gtkosx/* directory. Then run `make osx` to build *../textadept.osx* -and *../textadeptjit.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* and *Contents/MacOS/textadeptjit.osx* with your -own versions. +and *../textadeptjit.osx*. Build a new *Textadept.app* from an existing one by +downloading the most recent app and replacing *Contents/MacOS/textadept.osx* and +*Contents/MacOS/textadeptjit.osx* with your own versions. Similarly, `make osx-curses` builds *../textadept-curses.osx* and *../textadeptjit-curses.osx*. #### Compiling on OSX (Legacy) -[XCode][] is needed for Mac OSX as well as [jhbuild][] (for GTK+). 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. +Textadept requires [XCode][] as well as [jhbuild][] (for GTK+). After building +"meta-gtk-osx-bootstrap" and "meta-gtk-osx-core", 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. After using *jhbuild*, GTK+ is in *~/gtk/* so make a symlink from *~/gtk/inst* to *src/gtkosx* in Textadept. Then open *src/Makefile* and uncomment the "Darwin" block. Finally, run `make osx` to build *../textadept.osx* and *../textadeptjit.osx*. -Note: to build a GTK+ for OSX bundle, the following needs to be run from the -*src/* directory before zipping up *gtkosx/include/* and *gtkosx/lib/*: +Note: to build a GTK+ for OSX bundle, run the following from the *src/* +directory before zipping up *gtkosx/include/* and *gtkosx/lib/*: sed -i -e 's|libdir=/Users/username/gtk/inst/lib|libdir=${prefix}/lib|;' \ gtkosx/lib/pkgconfig/*.pc -where `username` is replaced with your username. +where `username` is your username. -Compiling the terminal version is not so expensive. After uncommenting the -"Darwin" block mentioned above, simply run `make osx-curses` to build -*../textadept-curses.osx* and *../textadeptjit-curses.osx*. No additional -libraries are needed. +Compiling the terminal version is not so expensive and requires no additional +libraries. After uncommenting the "Darwin" block mentioned above, simply run +`make osx-curses` to build *../textadept-curses.osx* and +*../textadeptjit-curses.osx*. [XCode]: http://developer.apple.com/TOOLS/xcode/ [jhbuild]: http://sourceforge.net/apps/trac/gtk-osx/wiki/Build @@ -171,7 +168,7 @@ non-Lua, libraries. includes a slightly modified, stripped down version of this library. The changes made to CDK are as follows: -* The following source files were removed: *alphalist.c*, *calendar.c*, +* Removed the following source files: *alphalist.c*, *calendar.c*, *cdk_compat.{c,h}*, *cdk_test.h*, *dialog.c*, *{d,f}scale.{c,h}*, *fslider.{c,h}*, *gen-{scale,slider}.{c,h}*, *get_index.c*, *get_string.c*, *graph.c*, *histogram.c*, *marquee.c*, *matrix.c*, *popup_dialog.c*, @@ -187,10 +184,10 @@ made to CDK are as follows: conditionally enables `HAVE_GRP_H`, `HAVE_LSTAT`, and `HAVE_PWD_H` definitions on \*nix platforms since Windows does not have them, and explicitly undefines `NCURSES_OPAQUE` since newer versions of ncurses on Mac OSX define it. -* *cdk_util.h* `#define`s `Beep` as `CDKBeep` on Windows platforms since Beep is - already defined. +* *cdk_util.h* `#define`s `Beep` as `CDKBeep` on Windows platforms since Windows + already defines Beep. * The `baseName` and `dirName` functions in *cdk.c* recognize Window's '\' directory separator. -* The `deleteFileCB` function in *fselect.c* has been deactivated. +* Deactivated the `deleteFileCB` function in *fselect.c*. [CDK]: http://invisible-island.net/cdk/ diff --git a/doc/13_Help.md b/doc/13_Help.md index e17008a1..8e75fff9 100644 --- a/doc/13_Help.md +++ b/doc/13_Help.md @@ -14,7 +14,7 @@ Switch |Arguments|Description `-s`, `--session` | 1 |Loads [session][] on startup. `-u`, `--userhome` | 1 |Sets alternate [`_USERHOME`][]. -The help switch is unavailable in curses. +Textadept curses does not support the help switch. [code]: 10_Advanced.html#Command.Entry [unique instance]: 02_Installation.html#Single.Instance @@ -23,9 +23,7 @@ The help switch is unavailable in curses. ## Online Help -Textadept has a [mailing list][] and a [wiki][]. You can also join us on IRC via -[freenode.net][] in "#textadept". +Textadept has a [mailing list][] and a [wiki][]. [mailing list]: http://foicica.com/lists [wiki]: http://foicica.com/wiki/textadept -[freenode.net]: http://freenode.net |