diff options
Diffstat (limited to 'doc/08_Preferences.md')
| -rw-r--r-- | doc/08_Preferences.md | 192 |
1 files changed, 0 insertions, 192 deletions
diff --git a/doc/08_Preferences.md b/doc/08_Preferences.md deleted file mode 100644 index 80fe37ed..00000000 --- a/doc/08_Preferences.md +++ /dev/null @@ -1,192 +0,0 @@ -# Preferences - -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 - -## 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. This file allows you -to indicate what you want Textadept to do when the application starts. Examples -include changing the settings of existing modules, loading new modules, and -running arbitrary Lua code. - -### Modules - -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 module, edit file types, or add a small bit of 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 modules. - -#### Generic - -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 strip trailing whitespace on save, add the -following to your *~/.textadept/init.lua*: - - textadept.editing.AUTOPAIR = false - textadept.editing.TYPEOVER_CHARS = false - textadept.editing.STRIP_TRAILING_SPACES = true - -To always hide the tab bar: - - ui.tabs = false - -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) -to *~/.textadept/modules/textadept/* and change - - M.menu = require 'textadept.menu' - -to - - --M.menu = require 'textadept.menu' - -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 - -#### Language - -Similar to generic modules, putting your own language 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 module from *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, 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.LEXER_LOADED` event handler to use -tabs, simply put the event handler in *~/.textadept/modules/lua/post_init.lua*: - - events.connect(events.LEXER_LOADED, function(lang) - if lang == 'lua' then buffer.use_tabs = true end - end) - -Similarly, use *post_init.lua* to change the module's [compile and run][] -commands, load more Autocompletion tags, and add additional -[key bindings](#Key.Bindings) and [snippets](#Snippets) (instead of in -*~/.textadept/init.lua*). For example: - - textadept.run.run_commands.lua = 'lua5.2' - _M.lua.tags[#_M.lua.tags + 1] = '/path/to/my/projects/tags' - keys.lua['c\n'] = function() - buffer:line_end() buffer:add_text('end') buffer:new_line() - end - snippets.lua['ver'] = '%<_VERSION>' - -[compile and run]: 07_Modules.html#Compile.and.Run - -### Loading Modules - -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*: - - foo = require('foo') - -Textadept automatically loads language modules when opening a source file of -that language, so simply installing the language module is sufficient. - -### Key Bindings - -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 = buffer.new - keys.cn = nil - -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 - -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) inserts the snippet, regardless of the current programming language. -Learn more about snippet syntax in the [snippets LuaDoc][]. - -[snippets LuaDoc]: api/textadept.snippets.html - -### File Types - -Textadept recognizes a wide range of programming language files either by file -extension, by a keyword in the shebang ("#!/path/to/exe") line, or by a -[Lua pattern][] that matches the text of the first line. The editor does this by -consulting a set of tables in [`textadept.file_types`][] that are modifiable -from *~/.textadept/init.lua*. For example: - - -- Recognize .luadoc files as Lua code. - textadept.file_types.extensions.luadoc = 'lua' - -- Change .html files to be recognized as XML files. - textadept.file_types.extensions.html = 'xml' - -- Recognize a shebang line like "#!/usr/bin/zsh" as shell code. - textadept.file_types.shebangs.zsh = 'bash' - -[Lua pattern]: 14_Appendix.html#Lua.Patterns -[`textadept.file_types`]: api/textadept.file_types.html - -## Buffer Properties - -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/properties.lua* file which runs after creating a new buffer or -split view. Any settings there override Textadept's default *properties.lua* -settings. For example, to use tabs rather than spaces and have a tab size of 4 -spaces by default, your *~/.textadept/properties.lua* would contain: - - buffer.use_tabs = true - buffer.tab_width = 4 - -(Remember that in order to have per-filetype properties, you need to have a -[language module][].) - -Textadept's *properties.lua* is a good "quick reference" for configurable -properties. It also has many commented out properties that you can copy to your -*~/.textadept/properties.lua* and uncomment to turn on or change the value of. -You can view a property's documentation by pressing `Ctrl+H` (`^H` on Mac OSX | -`M-H` or `M-S-H` in curses) or by reading the [LuaDoc][]. - -[language module]: 07_Modules.html#Buffer.Properties -[LuaDoc]: api/buffer.html - -## Locale - -Textadept attempts to auto-detect your locale settings using the "$LANG" -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 |