From c7b543e79b41d9a983cc89e264acd0472d09dc92 Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Tue, 30 Nov 2010 19:55:39 -0500 Subject: New manual. --- core/._G.luadoc | 9 ++--- core/._m.luadoc | 92 +++++++++++++++++++++++++++------------------- core/.command_entry.luadoc | 27 -------------- core/.find.luadoc | 31 +--------------- core/args.lua | 1 - core/file_io.lua | 12 ------ core/locale.lua | 9 ----- 7 files changed, 59 insertions(+), 122 deletions(-) mode change 100644 => 100755 core/._m.luadoc (limited to 'core') diff --git a/core/._G.luadoc b/core/._G.luadoc index 94c6dfa4..a0c0fb03 100644 --- a/core/._G.luadoc +++ b/core/._G.luadoc @@ -12,19 +12,16 @@ module('_G') -- * `_LEXERPATH`: Paths to lexers, formatted like -- [`package.path`][package_path]. -- * `_RELEASE`: The Textadept release version. --- * `_THEME`: The [theme][theme] file to use. +-- * `_THEME`: The [theme](../manual/8_Themes.lua) file to use. -- * `_USERHOME`: Path to the user's `~/.textadept/`. -- * `_CHARSET`: The character set encoding of the filesystem. This is used in --- [File I/O][file_io]. --- * `RESETTING`: If [`reset()`][reset] has been called, +-- [File I/O](../modules/io.html). +-- * `RESETTING`: If [`reset()`](../modules/_G.html#reset) has been called, -- this flag is `true` while the Lua state is being re-initialized. -- * `WIN32`: If Textadept is running on Windows, this flag is `true`. -- * `OSX`: If Textadept is running on Mac OSX, this flag is `true`. -- -- [package_path]: http://www.lua.org/manual/5.1/manual.html#pdf-package.path --- [theme]: ../manual/6_Startup.html --- [file_io]: ../modules/io.html --- [reset]: ../modules/_G.html#reset --- -- Command line parameters. diff --git a/core/._m.luadoc b/core/._m.luadoc old mode 100644 new mode 100755 index c8665fad..6f34dcba --- a/core/._m.luadoc +++ b/core/._m.luadoc @@ -9,59 +9,75 @@ module('_m') -- Markdown: -- ## Overview -- --- Modules utilize the Lua 5.1 package model. It is recommended to put all --- modules in your `~/.textadept/modules/` directory. A module consists of a --- single directory with an `init.lua` script to load any additional Lua files --- (typically in the same location). Essentially there are two classes of --- modules: generic and language-specific. +-- Note that while language-specific modules can only be used by files of that +-- language, they persist in Textadept's Lua state. Because of this, it is not +-- recommended to set global functions or variables and depend on them, as they +-- may be inadvertantly overwritten. Keep these inside the module. -- --- ## Generic Modules +-- ## Structure -- --- This class of modules is usually available globally for programming in all --- languages. An example is the [`_m.textadept`][m_textadept] module which adds --- a wide variety of text editing capabilities to Textadept. +-- Each module should have an `init.lua` that `require`s all submodules it +-- needs. For an example, see `modules/textadept/init.lua`. -- --- [m_textadept]: ../modules/_m.textadept.html +-- ## Recommended Features for Language-Specific Modules -- --- ## Language-specific Modules +-- #### Snippets -- --- Each module of this class of modules is named after a language lexer in --- `lexers/` and is usually available only for editing code in that particular --- programming language. Examples are the [`_m.cpp`][m_cpp] and --- [`_m.lua`][m_lua] modules which provide special editing features for the --- C/C++ and Lua languages respectively. +-- [Snippets](../modules/_m.textadept.snippets.html) for common code constructs. -- --- [m_cpp]: ../modules/_m.cpp.html --- [m_lua]: ../modules/_m.lua.html +-- #### Commands -- --- For language modules that have a `set_buffer_properties` function, that --- function is called each time a file with that language is opened. This is --- useful for setting `buffer.use_tabs`, `buffer.tab_width`, etc. for different --- languages. +-- ##### Run -- --- Note: While language-specific modules can only be used by files of that --- language, they persist in Textadept's Lua state. Because of this, it is not --- recommended to set global functions or variables and depend on them, as they --- may be inadvertantly overwritten. Keep these inside the module. +-- If the code can be run by an interpreter or other executable, create a [run +-- command](../modules/_m.textadept.run.html#run_command) for it as well as an +-- [error format](../modules/_m.textadept.run.html#error_detail) for the ability +-- to jump to the position in a file where the error occured. -- --- ## Loading Modules +-- For example: -- --- Generic modules can be loaded using `require`: +-- _m.textadept.run.run_command.lua = 'lua %(filename)' -- --- require 'module_name' +-- ##### Compile -- --- Language-specific modules are automatically loaded when a file of that --- language is loaded or a buffer's lexer is set to that language. +-- If the code can be compiled by an executable, create a [compile +-- command](../modules/_m.textadept.run.html#compile_command) for it. -- --- ## Modules and Key Commands +-- For example: +-- +-- _m.textadept.run.compile_command.lua = 'luac %(filename)' +-- +-- ##### Block Comment -- --- When assigning [key commands][key_commands] to module functions, do not --- forget to do so AFTER the function has been defined. Typically key commands --- are placed at the end of files, like `commands.lua` in language-specific --- modules. +-- Create a [comment +-- prefix](../modules/_m.textadept.editing.html#comment_string) for it so code +-- can be easily commented and uncommented. +-- +-- For example: +-- +-- _m.textadept.editing.comment_string.lua = '--' +-- +-- #### Buffer Properties +-- +-- Add a `set_buffer_properties` function with default buffer properties for +-- code like tab and indentation settings. +-- +-- For example: +-- +-- function set_buffer_properties() +-- local buffer = buffer +-- buffer.use_tabs = false +-- buffer.tab_width = 2 +-- buffer.indent = 2 +-- end +-- +-- ## Modules and Key Commands -- --- [key_commands]: ../modules/_m.textadept.keys.html +-- When assigning [key commands](../modules/_m.textadept.keys.html) to module +-- functions, do not forget to do so AFTER the function has been defined. +-- Typically key commands are placed at the end of files, like `init.lua` in +-- the `textadept` module. --- -- This module contains no functions. -function no_functions() end +function no_functions() end no_functions = nil diff --git a/core/.command_entry.luadoc b/core/.command_entry.luadoc index e474fa13..377fa0a8 100644 --- a/core/.command_entry.luadoc +++ b/core/.command_entry.luadoc @@ -11,33 +11,6 @@ module('gui.command_entry') -- -- * `entry_text`: The text in the entry. -- --- ## Overview --- --- Access to the Lua state is available through this command entry. It is useful --- for debugging, inspecting, and entering buffer or view commands. If you try --- cause instability in Textadept's Lua state, you might very well succeed. Be --- careful. --- --- Tab-completion for functions, variables, tables, etc. is available. Press the --- `Tab` key to display a list of available completions. Use the arrow keys to --- make a selection and press `Enter` to insert it. --- --- Abbreviated commands for the `buffer`, `view` and `gui` are available. So --- `buffer:append_text('textadept')` can be shortened to --- `append_text('textadept')`. Please note `print()` calls --- [`gui.print()`][gui_print] and not Lua's `print()`. The latter can be --- accessed with `_G.print()`. --- --- [gui_print]: ../modules/gui.html#print --- --- ## Extending --- --- You can extend the command entry to do more than enter Lua commands. An --- example of this is [incremental search][inc_search]. See --- `modules/textadept/find.lua` for the implementation. --- --- [inc_search]: ../modules/gui.find.html#incremental --- -- ## Events -- -- The following is a list of all command entry events generated in diff --git a/core/.find.luadoc b/core/.find.luadoc index 038d3943..e1251c02 100644 --- a/core/.find.luadoc +++ b/core/.find.luadoc @@ -20,34 +20,6 @@ module('gui.find') -- * `in_files`: Flag indicating whether or not to search for the text in a list -- of files. -- --- ## Overview --- --- In addition to offering standard find and replace, Textadept allows you to --- find with [Lua patterns][lua_patterns] and replace with Lua captures and even --- Lua code! Lua captures (`%n`) are only available from a Lua pattern search, --- but embedded Lua code enclosed in `%()` is always available. --- --- [lua_patterns]: http://www.lua.org/manual/5.1/manual.html#5.4.1 --- --- If any block of text is selected for 'Replace All', only matches found in --- that block are replaced. --- --- Find in Files will prompt for a directory to recursively search and display --- the results in a new buffer. Double-clicking a search result will jump to it --- in the file. Replace in Files is not supported. You will have to Find in --- Files first, and then 'Replace All' for each file a result is found in. --- The 'Match Case', 'Whole Word', and 'Lua pattern' flags still apply. --- --- Incremental search uses the Command Entry. --- --- ## Customizing Look and Feel --- --- There is no way to theme the dialog from within Textadept. Instead you can --- use [GTK Resource files][gtkrc]. The find and replace entries have widget --- names of `textadept-find-entry` and `textadept-replace-entry` respectively. --- --- [gtkrc]: http://library.gnome.org/devel/gtk/unstable/gtk-Resource-Files.html. --- -- ## Events -- -- The following is a list of all find events generated in @@ -65,7 +37,8 @@ module('gui.find') -- - find\_text: the text to search for. -- - repl\_text: the text to replace found text with. ---- Displays and focuses the find/replace dialog. +--- +-- Displays and focuses the find/replace dialog. function focus() end --- diff --git a/core/args.lua b/core/args.lua index 9535fa63..3c0277f6 100644 --- a/core/args.lua +++ b/core/args.lua @@ -4,7 +4,6 @@ module('args', package.seeall) -- Markdown: --- -- ## Events -- -- The following is a list of all arg events generated in diff --git a/core/file_io.lua b/core/file_io.lua index fded1499..574ea6a2 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -8,18 +8,6 @@ local events = _G.events module('io', package.seeall) -- Markdown: --- ## Overview --- --- 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. Problems may arise for files with more exotic --- encodings that may not be detected properly, if at all. When opening a file, --- the list of encodings tried before throwing a `conversion failed` error is in --- `core/file_io.lua`'s [`try_encodings`](#try_encodings). Textadept respects --- the detected encoding when saving the file. --- --- New files are saved as UTF-8 by default. --- -- ## Converting Filenames to and from UTF-8 -- -- If your filesystem does not use UTF-8 encoded filenames, conversions to and diff --git a/core/locale.lua b/core/locale.lua index 5b14a254..0b148e68 100644 --- a/core/locale.lua +++ b/core/locale.lua @@ -5,15 +5,6 @@ module('locale', package.seeall) -- Markdown: --- ## Overview --- --- All Textadept messages displayed are located in `core/locale.conf`. To change --- the language, simply put a similar file containing the translated messages in --- your `~/.textadept/` folder. See `core/locale.conf` for more information. --- --- Feel free to translate Textadept and send your modified `locale.conf` files --- to me. I will put them up on the site where they can be accessed. --- -- ## Fields -- -- Each message ID in `core/locale.conf` is accessible as a field in this -- cgit v1.2.3