From fa38d2306fadc99bb1403433517ecf45a24062eb Mon Sep 17 00:00:00 2001 From: mitchell <70453897+667e-11@users.noreply.github.com> Date: Mon, 29 Oct 2012 20:45:58 -0400 Subject: Updated documentation formatting. Pathnames and filenames are italic and be more consistent with constant width text. --- core/._M.luadoc | 6 ++--- core/.buffer.luadoc | 70 ++++++++++++++++++++++++++--------------------------- core/file_io.lua | 2 +- core/gui.lua | 15 ++++++------ core/iface.lua | 2 +- core/init.lua | 14 +++++------ core/keys.lua | 20 +++++++-------- 7 files changed, 65 insertions(+), 64 deletions(-) (limited to 'core') diff --git a/core/._M.luadoc b/core/._M.luadoc index ea969647..ca2c6952 100644 --- a/core/._M.luadoc +++ b/core/._M.luadoc @@ -8,9 +8,9 @@ -- -- ## Module Guidelines -- --- At the very least, modules consist of a single directory with an `init.lua` +-- At the very least, modules consist of a single directory with an *init.lua* -- script. However, the script can load additional Lua files present in the --- directory. (For an example, see `modules/textadept/init.lua`.) +-- directory. (For an example, see *modules/textadept/init.lua*.) -- -- Once modules are loaded, regardless of whether they are generic or -- language-specific, they persist in Textadept's Lua State; they are never @@ -105,7 +105,7 @@ -- -- Additional editing features for the language can be useful. For example, the -- [Lua][] module has a feature to autocomplete the `end` keyword in a control --- structure and the [C/C++][] module has a feature to add a `;` to the end of +-- structure and the [C/C++][] module has a feature to add a ';' to the end of -- the current line and insert a new line. Both are bound to the `Shift+Enter` -- (`⇧↩` on Mac OSX | `S-Enter` in ncurses) key for easy access. -- diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc index c224cac5..8d01f584 100644 --- a/core/.buffer.luadoc +++ b/core/.buffer.luadoc @@ -10,7 +10,7 @@ -- -- [buffer]: _G.html#buffer -- @field additional_caret_fore (number) --- The foreground color of additional carets in `0xBBGGRR` format. +-- The foreground color of additional carets in "0xBBGGRR" format. -- @field additional_carets_blink (bool) -- Whether additional carets will blink. -- @field additional_carets_visible (bool) @@ -19,11 +19,11 @@ -- The alpha of additional selections. Alpha ranges from `0` (transparent) to -- `255` (opaque) or `256` for no alpha. -- @field additional_sel_back (number) --- The background color of additional selections in `0xBBGGRR` format. +-- The background color of additional selections in "0xBBGGRR" format. -- `buffer:set_sel_back(true, ...)` must have been called previously for this -- to have an effect. -- @field additional_sel_fore (number) --- The foreground color of additional selections in `0xBBGGRR` format. +-- The foreground color of additional selections in "0xBBGGRR" format. -- `buffer:set_sel_fore(true, ...)` must have been called previously for this -- to have an effect. -- @field additional_selection_typing (bool) @@ -106,7 +106,7 @@ -- The auto-completion list type-separator character byte. -- The default is `'?'`. Autocompletion list items may display an image as -- well as text. Each image is first registered with an integer type. Then --- this integer is included in the text of the list separated by a `?` from +-- this integer is included in the text of the list separated by a '?' from -- the text. -- @field back_space_un_indents (bool) -- Whether a backspace pressed when caret is within indentation unindents. @@ -116,11 +116,11 @@ -- before drawing it to the screen to avoid flicker. The default is for -- drawing to be buffered. first or directly onto the screen. -- @field call_tip_back (number, Write-only) --- The background color for the call tip in `0xBBGGRR` format. +-- The background color for the call tip in "0xBBGGRR" format. -- @field call_tip_fore (number, Write-only) --- The foreground color for the call tip in `0xBBGGRR` format. +-- The foreground color for the call tip in "0xBBGGRR" format. -- @field call_tip_fore_hlt (number, Write-only) --- The foreground color for the highlighted part of the call tip in `0xBBGGRR` +-- The foreground color for the highlighted part of the call tip in "0xBBGGRR" -- format. -- @field call_tip_position (boolean) -- The position of calltip, above or below text. @@ -131,9 +131,9 @@ -- size in pixels. -- If the tab size is less than `1`, Tab characters are not treated specially. -- @field caret_fore (number) --- The foreground color of the caret in `0xBBGGRR` format. +-- The foreground color of the caret in "0xBBGGRR" format. -- @field caret_line_back (number) --- The color of the background of the line containing the caret in `0xBBGGRR` +-- The color of the background of the line containing the caret in "0xBBGGRR" -- format. -- @field caret_line_back_alpha (number) -- The background alpha of the caret line. @@ -210,13 +210,13 @@ -- The current end of line mode. -- -- * `_SCINTILLA.constants.SC_EOL_CRLF` (0) --- `CRLF`. +-- "CR+LF" ("\r\n"). -- * `_SCINTILLA.constants.SC_EOL_CR` (1) --- `CR`. +-- "CR" ("\r"). -- * `_SCINTILLA.constants.SC_EOL_LF` (2) --- `LF`. +-- "LF" ("\n"). -- @field edge_colour (number) --- The color used in edge indication in `0xBBGGRR` format. +-- The color used in edge indication in "0xBBGGRR" format. -- @field edge_column (number) -- The column number which text should be kept within. -- @field edge_mode (number) @@ -335,7 +335,7 @@ -- Used for drawing the fill color of the `INDIC_ROUNDBOX` and -- `INDIC_STRAIGHTBOX` rectangle. -- @field indic_fore (table) --- Table of foreground colors in `0xBBGGRR` format for indicators from `0` to +-- Table of foreground colors in "0xBBGGRR" format for indicators from `0` to -- `31`. -- @field indic_outline_alpha (table) -- Table of alpha transparency values ranging from `0` (transparent) to `255` @@ -479,7 +479,7 @@ -- The default is to one pixel. -- @field margin_sensitive_n (table) -- Table of mouse click sensitivity booleans for margins from zero to four. --- A click in a sensitive margin emits a `margin_click` event. By default, all +-- A click in a sensitive margin emits a `MARGIN_CLICK` event. By default, all -- margins are insensitive. -- @field margin_style (table) -- Table of style numbers for text margin lines starting from zero. @@ -520,16 +520,16 @@ -- `0` (transparent) and `255` (opaque), or `256` for no alpha. -- @field marker_back (table, Write-only) -- Table of the background colors used for particular marker numbers. --- Marker numbers are in the range of `0` to `31`. Colors are in `0xBBGGRR` +-- Marker numbers are in the range of `0` to `31`. Colors are in "0xBBGGRR" -- format. -- @field marker_back_selected (table, Write-only) -- Table of the background colors used for particular marker numbers when -- their folding blocks are selected. --- Marker numbers are in the range of `0` to `31`. Colors are in `0xBBGGRR` --- format. The default color is `#FF0000`. +-- Marker numbers are in the range of `0` to `31`. Colors are in "0xBBGGRR" +-- format. The default color is `0x0000FF`. -- @field marker_fore (table, Write-only) -- Table of the foreground colors used for particular marker numbers. --- Marker numbers are in the range of `0` to `31`. Colors are in `0xBBGGRR` +-- Marker numbers are in the range of `0` to `31`. Colors are in "0xBBGGRR" -- format. -- @field max_line_state (number, Read-only) -- The last line number that has line state. @@ -653,8 +653,8 @@ -- The search string should be interpreted as a regular expression. -- * `_SCINTILLA.constants.SCFIND_POSIX` (0x00400000) -- Treat regular expression in a more POSIX compatible manner by --- interpreting bare `(` and `)` for tagged sections rather than `\(` and --- `\)`. +-- interpreting bare '(' and ')' for tagged sections rather than "\(" and +-- "\)". -- @field sel_alpha (number) -- The alpha of the selection, between `0` (transparent) and `255` (opaque), -- or `256` for no alpha. @@ -716,7 +716,7 @@ -- @field style_at (table, Read-only) -- Table of style bytes at positions in the document starting at zero. -- @field style_back (table) --- Table of background colors in `0xBBGGRR` format for styles from `0` to +-- Table of background colors in "0xBBGGRR" format for styles from `0` to -- `255`. -- @field style_bits (number) -- The number of bits in style bytes used to hold the lexical state. @@ -743,7 +743,7 @@ -- @field style_font (table) -- Table of font faces for styles from `0` to `255`. -- @field style_fore (table) --- Table of foreground colors in `0xBBGGRR` format for styles from `0` to +-- Table of foreground colors in "0xBBGGRR" format for styles from `0` to -- `255`. -- @field style_hot_spot (table) -- Table of boolean hotspot styles from `0` to `255`. @@ -1020,7 +1020,7 @@ function brace_highlight_indicator(buffer, use_indicator, indic_num) end --- -- Find the position of a matching brace or `-1` if no match. --- The brace characters handled are `(`, `)`, `[`, `]`, `{`, `}`, `<`, and `>`. +-- The brace characters handled are '(', ')', '[', ']', '{', '}', '<', and '>'. -- The search is forwards from an opening brace and backwards from a closing -- brace. A match only occurs if the style of the matching brace is the same as -- the starting brace or the matching brace is beyond the end of styling. Nested @@ -1423,7 +1423,7 @@ function get_line_sel_start_position(buffer, line) end -- May move the gap so that the range is contiguous, but will only move up to -- range_length bytes. -- The gap is not moved unless it is within the requested range so this call can --- be faster than `SCI_GETCHARACTERPOINTER`. This can be used by application +-- be faster than `buffer.character_pointer`. This can be used by application -- code that is able to act on blocks of text or ranges of lines. function get_range_pointer(buffer, position, range_length) end @@ -2030,7 +2030,7 @@ function replace_sel(buffer, text) end function replace_target(buffer, text) end --- --- Replace the target text with the argument text after `\d` processing. +-- Replace the target text with the argument text after \d` processing. -- Looks for `\d` where `d` is between `1` and `9` and replaces these with the -- strings matched in the last search operation which were surrounded by `\(` -- and `\)`. Returns the length of the replacement text including any change @@ -2115,7 +2115,7 @@ function selection_duplicate(buffer) end -- Reset the set of characters for whitespace and word characters to the -- defaults. -- This sets whitespace to space, tab and other characters with codes less than --- `0x20`, with word characters set to alphanumeric and `'_'`. +-- 0x20, with word characters set to alphanumeric and `'_'`. -- @param buffer The global buffer. function set_chars_default(buffer) end @@ -2130,28 +2130,28 @@ function set_empty_selection(buffer, pos) end -- Set the colors used as a chequerboard pattern in the fold margin. -- @param buffer The global buffer. -- @param use_setting Enable color change. --- @param color A color in `0xBBGGRR` format. +-- @param color A color in "0xBBGGRR" format. function set_fold_margin_colour(buffer, use_setting, color) end --- -- Set the colors used as a checkerboard pattern in the fold margin. -- @param buffer The global buffer. -- @param use_setting Enable color change. --- @param color A color in `0xBBGGRR` format. +-- @param color A color in "0xBBGGRR" format. function set_fold_margin_hi_colour(buffer, use_setting, color) end --- -- Set a back color for active hotspots. -- @param buffer The global buffer. -- @param use_setting Enable the color change. --- @param color A color in `0xBBGGRR` format. +-- @param color A color in "0xBBGGRR" format. function set_hotspot_active_back(buffer, use_setting, color) end --- -- Set a fore color for active hotspots. -- @param buffer The global buffer. -- @param use_setting Enable the color change. --- @param color A color in `0xBBGGRR` format. +-- @param color A color in "0xBBGGRR" format. function set_hotspot_active_fore(buffer, use_setting, color) end --- @@ -2181,7 +2181,7 @@ function set_sel(buffer, start_pos, end_pos) end -- use this setting. -- @param buffer The global buffer. -- @param use_setting Enable color change. --- @param color A color in `0xBBGGRR` format. +-- @param color A color in "0xBBGGRR" format. function set_sel_back(buffer, use_setting, color) end --- @@ -2189,7 +2189,7 @@ function set_sel_back(buffer, use_setting, color) end -- to use this setting. -- @param buffer The global buffer. -- @param use_setting Enable color change. --- @param color A color in `0xBBGGRR` format. +-- @param color A color in "0xBBGGRR" format. function set_sel_fore(buffer, use_setting, color) end --- @@ -2227,14 +2227,14 @@ function set_visible_policy(buffer, visible_policy, visible_slop) end -- Set the background color of all whitespace and whether to use this setting. -- @param buffer The global buffer. -- @param use_setting Enable color change. --- @param color A color in `0xBBGGRR` format. +-- @param color A color in "0xBBGGRR" format. function set_whitespace_back(buffer, use_setting, color) end --- -- Set the foreground color of all whitespace and whether to use this setting. -- @param buffer The global buffer. -- @param use_setting Enable color change. --- @param color A color in `0xBBGGRR` format. +-- @param color A color in "0xBBGGRR" format. function set_whitespace_fore(buffer, use_setting, color) end --- diff --git a/core/file_io.lua b/core/file_io.lua index 0cd9314a..cbd93b22 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -119,7 +119,7 @@ io.try_encodings = { 'UTF-8', 'ASCII', 'ISO-8859-1', 'MacRoman' } --- -- Opens a list of files. -- Emits a `FILE_OPENED` event. --- @param utf8_filenames A `\n` separated list of UTF-8-encoded filenames to +-- @param utf8_filenames A "\n" separated list of UTF-8-encoded filenames to -- open. If `nil`, the user is prompted with a fileselect dialog. -- @usage io.open_file(utf8_encoded_filename) -- @see _G.events diff --git a/core/gui.lua b/core/gui.lua index 8ea4162f..4bc3da8c 100644 --- a/core/gui.lua +++ b/core/gui.lua @@ -153,11 +153,11 @@ local theme_file = not NCURSES and 'theme' or 'theme_term' local THEME --- -- Sets the editor theme from the given name. --- Themes with the given name in the `_USERHOME/themes/` directory override --- themes of the same name in `_HOME/themes/`. If the name contains slashes (`\` --- on Windows, `/` otherwise), it is assumed to be an absolute path to a theme --- instead of a theme name. An error is thrown if the theme is not found. Any --- errors in the theme are printed to `io.stderr`. +-- Themes with the given name in the *`_USERHOME`/themes/* directory override +-- themes of the same name in *`_HOME`/themes/*. If the name contains slashes +-- ('\' on Windows, '/' otherwise), it is assumed to be an absolute path to a +-- theme instead of a theme name. An error is thrown if the theme is not found. +-- Any errors in the theme are printed to `io.stderr`. -- @param name The name or absolute path of a theme. If nil, sets the default -- theme. -- @name set_theme @@ -213,7 +213,8 @@ end --- -- Prompts the user to select an editor theme from a filtered list dialog. --- Themes in the `_HOME/themes/` and `_USERHOME/themes/` directories are listed. +-- Themes in the *`_HOME`/themes/* and *`_USERHOME`/themes/* directories are +-- listed. -- @name select_theme function gui.select_theme() local themes, themes_found = {}, {} @@ -489,7 +490,7 @@ local goto_view -- @param menu_table A table defining the menu. It is an ordered list of tables -- with a string menu item, integer menu ID, and optional GDK keycode and -- modifier mask. The latter two are used to display key shortcuts in the --- menu. `_` characters are treated as a menu mnemonics. If the menu item is +-- menu. '_' characters are treated as a menu mnemonics. If the menu item is -- empty, a menu separator item is created. Submenus are just nested -- menu-structure tables. Their title text is defined with a `title` key. -- @usage gui.menu{ { '_New', 1 }, { '_Open', 2 }, { '' }, { '_Quit', 4 } } diff --git a/core/iface.lua b/core/iface.lua index 19af0ea8..d71f7db7 100644 --- a/core/iface.lua +++ b/core/iface.lua @@ -25,7 +25,7 @@ M.constants = {ANNOTATION_BOXED=2,ANNOTATION_HIDDEN=0,ANNOTATION_STANDARD=1,CARE -- + `1`: Integer. -- + `2`: Length of the given lParam string. -- + `3`: Integer position. --- + `4`: Colour in `0xBBGGRR` format. +-- + `4`: Colour in "0xBBGGRR" format. -- + `5`: Boolean `true` or `false`. -- + `6`: Bitmask of Scintilla key modifiers and a key value. -- + `7`: String parameter. diff --git a/core/init.lua b/core/init.lua index a0da9f94..a8cd48d6 100644 --- a/core/init.lua +++ b/core/init.lua @@ -31,13 +31,13 @@ _M = {} -- modules table -- @field _RELEASE (string) -- The Textadept release version. -- @field _USERHOME (string) --- Path to the user's `~/.textadept/`, where all preferences and user-data is +-- Path to the user's *~/.textadept/*, where all preferences and user-data is -- stored. --- On Windows machines `~/` is the value of the `USERHOME` environment --- variable, typically `C:\Users\\` or --- `C:\Documents and Settings\\`. On Linux, BSD, and Mac OSX --- machines `~/` is the value of `HOME`, typically `/home//` and --- `/Users//` respectively. +-- On Windows machines *~/* 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 *~/* is the value of "$HOME", typically */home/username/* and +-- */Users/username/* respectively. -- @field _CHARSET (string) -- The character set encoding of the filesystem. -- This is used when [working with files](io.html). @@ -115,7 +115,7 @@ local quit -- Language-specific modules for opened files are NOT reloaded. Re-opening the -- files that use them will reload those modules instead. -- This function is useful for modifying user scripts (such as --- `~/.textadept/init.lua` and `~/.textadept/modules/textadept/keys.lua`) on +-- *~/.textadept/init.lua* and *~/.textadept/modules/textadept/keys.lua*) on -- the fly without having to restart Textadept. `_G.RESETTING` is set to `true` -- when re-initing the Lua State. Any scripts that need to differentiate between -- startup and reset can utilize this variable. diff --git a/core/keys.lua b/core/keys.lua index 19b07e99..6d5efa93 100644 --- a/core/keys.lua +++ b/core/keys.lua @@ -10,7 +10,7 @@ local M = {} -- -- Key bindings are defined in the global table `keys`. Each key-value pair in -- `keys` consists of either a string key sequence and its associated command, --- a string lexer language (from the `lexers/` directory) with a table of key +-- a string lexer language (from the *lexers/* directory) with a table of key -- sequences and commands, or a key sequence with a table of more sequences and -- commands. The latter is part of what is called a "key chain". When searching -- for a command to run based on a key sequence, key bindings in the current @@ -25,9 +25,9 @@ local M = {} -- ## Key Sequences -- -- Key sequences are strings built from a combination of modifier keys and the --- key itself. Modifier keys are `Control`, `Shift`, and `Alt` on Windows, --- Linux, BSD, and in ncurses. On Mac OSX they are `Command` (`⌘`), `Alt/Option` --- (`⌥`), `Control` (`^`), and `Shift` (`⇧`). These modifiers have the following +-- key itself. Modifier keys are "Control", "Shift", and "Alt" on Windows, +-- Linux, BSD, and in ncurses. On Mac OSX they are "Command" (`⌘`), "Alt/Option" +-- (`⌥`), "Control" (`^`), and "Shift" (`⇧`). These modifiers have the following -- string representations: -- -- Modifier | Linux / Win32 | Mac OSX | Terminal | @@ -38,16 +38,16 @@ local M = {} -- Command | N/A | `'c'` | N/A | -- -- For key values less than 255, their string representation is the character --- that would normally be inserted if the `Ctrl`, `Alt`, and `Command` modifiers --- were not held down. Therefore, a combination of `Ctrl+Alt+Shift+A` has the --- key sequence `caA` on Windows and Linux, but a combination of +-- that would normally be inserted if the "Control", "Alt", and "Command" +-- modifiers were not held down. Therefore, a combination of `Ctrl+Alt+Shift+A` +-- has the key sequence `caA` on Windows and Linux, but a combination of -- `Ctrl+Shift+Tab` has the key sequence `cs\t`. On a United States English -- keyboard, since the combination of `Ctrl+Shift+,` has the key sequence `c<` -- (`Shift+,` inserts a `<`), the key binding is referred to as `Ctrl+<`. This -- allows key bindings to be language and layout agnostic. For key values -- greater than 255, the [`KEYSYMS`](#KEYSYMS) lookup table is used. Therefore, -- `Ctrl+Right Arrow` has the key sequence `cright`. Uncommenting the `print()` --- statements in `core/keys.lua` will print key sequences to standard out +-- statements in *core/keys.lua* will print key sequences to standard out -- (stdout) for inspection. -- -- ## Commands @@ -107,7 +107,7 @@ local error = function(e) events.emit(events.ERROR, e) end --- -- Lookup table for string representations of GDK key codes higher than 255. -- Key codes can be identified by temporarily uncommenting the `print()` --- statements in `core/keys.lua` +-- statements in *core/keys.lua* -- @class table -- @name KEYSYMS M.KEYSYMS = { @@ -160,7 +160,7 @@ local function clear_key_sequence() end -- Runs a given command. --- This is also used by `modules/textadept/menu.lua`. +-- This is also used by *modules/textadept/menu.lua*. -- @param command A function or table as described above. -- @param command_type Equivalent to `type(command)`. -- @return the value the command returns. -- cgit v1.2.3