diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/04_WorkingWithFiles.md | 6 | ||||
| -rw-r--r-- | doc/06_AdeptEditing.md | 4 | ||||
| -rw-r--r-- | doc/08_Preferences.md | 78 | ||||
| -rw-r--r-- | doc/09_Themes.md | 66 |
4 files changed, 71 insertions, 83 deletions
diff --git a/doc/04_WorkingWithFiles.md b/doc/04_WorkingWithFiles.md index 373b7851..ff8ce0fa 100644 --- a/doc/04_WorkingWithFiles.md +++ b/doc/04_WorkingWithFiles.md @@ -36,8 +36,8 @@ settings in the buffer status statusbar. #### Indentation -Indentation is usually set by a [language-specific module][] or the current -[theme][]. By default, indentation is 2 spaces. You can toggle between using +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` @@ -47,7 +47,7 @@ are converted to spaces.) Similarly, you can set indentation size manually using the "Buffer -> Indentation" menu. [language-specific module]: 07_Modules.html#Buffer.Properties -[theme]: 09_Themes.html#Buffer +[settings]: 08_Preferences.html#Buffer.Settings #### Line Endings diff --git a/doc/06_AdeptEditing.md b/doc/06_AdeptEditing.md index 5cfd231e..86a3901e 100644 --- a/doc/06_AdeptEditing.md +++ b/doc/06_AdeptEditing.md @@ -74,7 +74,7 @@ and dragging the mouse to create rectangular selections. 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 [theme][]. The +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. @@ -82,7 +82,7 @@ Creating rectangular selections with the mouse is currently unavailable in curses. [`buffer.rectangular_selection_modifier`]: api/buffer.html#rectangular_selection_modifier -[theme]: 09_Themes.html#View +[settings]: 08_Preferences.html#Buffer.Settings ### Select to Matching Brace diff --git a/doc/08_Preferences.md b/doc/08_Preferences.md index a3cbe3d8..d1acabc5 100644 --- a/doc/08_Preferences.md +++ b/doc/08_Preferences.md @@ -10,39 +10,38 @@ At this point it is assumed you are at least familiar with the basics of 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 to indicate what you want Textadept to do when the application starts, such as -loading additional modules. However, you are not restricted to just loading -modules. You can run any Lua code you desire. +changing the settings of existing modules, loading new ones, and/or running +plain Lua code. -## Modules +### 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 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. To -load your own module, simply place it appropriately in *~/.textadept/modules/*. -To run your module code after a default generic module loads, put your code in -*~/.textadept/init.lua*. To run your module code after a default -language-specific module loads, create a *post_init.lua* Lua script in the -appropriate *~/.textadept/modules/* module folder. These methods are discussed -below. +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. -### Generic +#### 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* might -look like: +typeover and stripping whitespace on save, your *~/.textadept/init.lua* would +contain: _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 -menu. Copy the `textadept` module's *init.lua* (located in the -*modules/textadept/* directory) to *~/.textadept/modules/textadept/* and change +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) +to *~/.textadept/modules/textadept/* and change M.menu = require 'textadept.menu' @@ -51,27 +50,27 @@ to --M.menu = require 'textadept.menu' Now when Textadept looks for *modules/textadept/init.lua*, it will load yours -instead of its own, and load everything but the menu. If instead you wanted to +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* instead of its own. +your *menu.lua* rather than its own. [LuaDoc]: api/index.html -### Language-Specific +#### Language-Specific 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 instead of the default one. If you make custom changes to -these kinds of copies of language-specific modules, you will likely want to -update them with each new Textadept release. Instead of potentially wasting time -merging your changes, you can 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*: +for editing Lua code in place of the default one. 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*: events.connect(events.LANGUAGE_MODULE_LOADED, function(lang) if lang == 'lua' then buffer.use_tabs = true end @@ -133,6 +132,35 @@ You can learn 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 +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: + + buffer.tab_width = 4 + buffer.use_tabs = true + +(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][]. + +[language-specific module]: 07_Modules.html#Buffer.Properties +[Adeptsense]: 06_AdeptEditing.html#Adeptsense +[LuaDoc]: api/buffer.html + ## Locale Textadept attempts to auto-detect your locale settings using the "$LANG" diff --git a/doc/09_Themes.md b/doc/09_Themes.md index 3c1de645..73f4c612 100644 --- a/doc/09_Themes.md +++ b/doc/09_Themes.md @@ -12,21 +12,17 @@ for the GUI version and "term" for the terminal version.  -## Structure - -Each theme is a single folder composed of three files: *lexer.lua*, -*buffer.lua*, and *view.lua*. It is recommended to put custom or downloaded +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 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. -### Lexer - -*lexer.lua* contains definitions for how to "style" syntactic elements like -comments, strings, and keywords in programming languages. [Styles][] are -composed of fonts and colors and apply universally to all programming language -elements, resulting in a single, unified theme. +Themes contain color definitions and definitions for how to highlight (or +"style") syntactic elements like comments, strings, and keywords in programming +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 @@ -35,54 +31,18 @@ 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. -[Styles]: api/lexer.html#Styles.and.Styling - -### Buffer - -*buffer.lua* contains [buffer-specific properties][] like the indentation -character and indentation size. For example, to use tabs instead of spaces and -have a tab size of 4 spaces by default: - - buffer.tab_width = 4 - buffer.use_tabs = true - -You can use [Adeptsense][] to view a property's documentation or read the -[buffer LuaDoc][]. +[definitions]: api/lexer.html#Styles.and.Styling -[buffer-specific properties]: 04_WorkingWithFiles.html#Settings -[Adeptsense]: 06_AdeptEditing.html#Adeptsense -[buffer LuaDoc]: api/buffer.html +## Switch Themes -### View +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 -*view.lua* contains view-specific properties which apply to all buffers. These -properties are numerous and control many aspects of how buffers are displayed, -from caret and selection colors to margin configurations to marker definitions. -View properties also control editor behaviors like scrolling and autocompletion. -Existing themes have various properties commented out. Uncomment a property to -turn it on or change its value. You can use [Adeptsense][] to view a property's -documentation or read the [LuaDoc][]. + gui.set_theme('name') -[Adeptsense]: 06_AdeptEditing.html#Adeptsense -[LuaDoc]: api/buffer.html +somewhere in your [*~/.textadept/init.lua*][]. -## Switch Themes - -You can switch between or reload themes using `Ctrl+Shift+T` (`⌘⇧T` on Mac OSX | -none in curses). However, be aware that the views do not reset themselves. Any -properties set explicitly in the previous theme's *view.lua* file that are not -set explicitly in the new theme will carry over. Restarting Textadept will fix -this. Also, be aware that themes apply to all buffers. You cannot assign a theme -to a particular file or file type. (You can change things like tab and indent -settings per filetype, however, by creating a [language-specific module][].) -Behind the scenes, Textadept is setting the theme name in a *~/.textadept/theme* -or *~/.textadept/theme_term* file. To use a theme not listed, specify an -absolute path to the theme's folder in your *~/.textadept/theme* or -*~/.textadept/theme_term* file. When testing themes, any errors that occur are -printed to standard error. Running Textadept from a terminal is the easiest way -to see errors as they occur. - -[language-specific module]: 07_Modules.html#Buffer.Properties +[*~/.textadept/init.lua*]: 08_Preferences.html#User.Init ## GUI Theme |