diff options
Diffstat (limited to 'doc/sciteco.7.template')
| -rw-r--r-- | doc/sciteco.7.template | 365 |
1 files changed, 234 insertions, 131 deletions
diff --git a/doc/sciteco.7.template b/doc/sciteco.7.template index 2ad16d3..81deac0 100644 --- a/doc/sciteco.7.template +++ b/doc/sciteco.7.template @@ -86,17 +86,17 @@ regular commands for command-line editing. .SH KEY TRANSLATION . When the user presses a key or key-combination it is first translated -to an ASCII character. -All immediate editing commands and regular \*(ST commands operate on -a language based solely on -.B ASCII -characters. +to an UTF-8 string. The rules for translating keys are as follows: .RS .IP 1. 4 Keys with a printable representation (letters, digits and special -characters) are translated to their printable representation. -Shift-combinations automatically result in upper-case letters. +characters) are translated to their printable representation +according to the current keyboard layout and modifier keys. +On the Gtk UI, \*(ST tries to automatically take ANSI letter +values in situations where the parser accepts only ANSI +characters. +On Curses, you might need key macros to achieve the same. .IP 2. .SCITECO_TOPIC ctrl Control-combinations (e.g. CTRL+A) are translated to control @@ -104,7 +104,9 @@ codes, that is a code smaller than 32. The control code can be calculated by stripping the seventh bit from the upper-case letter's ASCII code. So for instance, the upper or lower case A (65) will be translated -to code 1, B to code 2, ecetera. +to code 1, B (66) to code 2, ecetera. +\*(ST will always use latin letters regardless of the current +keyboard layout. \*(ST echos control codes as Caret followed by the corresponding upper case letter, so you seldomly need to know a control codes actual numeric code. @@ -126,138 +128,164 @@ there is often an equivalent typed with the caret character (e.g. \(lq^I\(rq). .IP 4. A selection of other keys without printable representation (called -function keys) are translated to user-definable character sequences. -This feature is called function key macros and explained in the -next subsection. +function keys) are looked up as key macros, allowing user-definable character +sequences to be inserted, including immediate editing commands. +If there is no matching key macro, nothing is inserted. +The key macro feature is explained in the next subsection. +.IP 5. +All keys with printable representations are also looked up +as key macros, allowing them to be remapped just like function keys. +Otherwise the corresponding UTF-8 strings are inserted into the command stream. +.IP 6. +The result of key macro lookups or the default printable representations +are processed as immediate editing commands in a context-sensitive manner +(see section +.BR "COMMANDLINE EDITING" ). +By default they are inserted into the command line macro and are +immediately executed. .RE . -.SS Function Key Macros -. -.SCITECO_TOPIC "function key" +.LP +While \*(ST handles keys with arbitrary Unicode representations, +all immediate editing commands and regular \*(ST commands operate on +a language based solely on +.B ASCII +codes, which is a subset of Unicode. +\# This is because we cannot assume the presence of any particular non-ANSI +\# symbol on a user's keyboard. +\# Immediate editing commands do not operate directly on function keys +\# because we didn't want to introduce an UI-independent representation +\# of function keys - it would also complicate insertion of immediate +\# editing commands from key macros. +Since the \*(ST parser is Unicode-aware, this does not exclude +using Unicode glyphs wherever a single character is expected, +ie. \fB^^\fIx\fR and \fBU\fIq\fR works with arbitrary Unicode glyphs. +All \*(ST macros must be in valid UTF-8. +. +.SS Key Macros +. +.SCITECO_TOPIC "key macro" ^K By default function keys except Escape, Backspace and Return are ignored by \*(ST. -By setting bit 6 of the \fBED\fP flag variable, function key handling -is enabled: -.SCITECO_TT -.EX -0,64ED -.SCITECO_TT_END -.EE -This is usually performed in the editor profile. -With certain interfaces (curses) after enabling function keys, -the Escape key might only be handled after a short delay. +With certain interfaces (curses) the Escape key might only be handled +after a short delay. This is because it might be used by the terminal to transmit Escape Sequences. This delay is minimized by \*(ST, so using the escape key should not be a problem even on ncurses/UNIX. +If the default delay is too small, it can be tweaked with the +.B ESCDELAY +environment variable and if necessary a key macro can be +defined as an escape surrogate as described in this section +.RB ( fnkeys.tes +defines the delete key as an escape surrogate for instance). .LP -Enabling function keys also enables Function Key Macros. -These are Q-Register strings inserted into the command stream -(before immediate editing command handling) when certain function -keys (or combinations) are pressed. -The following list of Function Key Macro registers are supported: +To make use of function keys or to remap all other keys, +special Q-Register strings can be defined that are inserted into the command stream +before immediate editing command handling. +The following list of key macro registers are supported: +. .TP 9 -.SCITECO_TOPIC ^FDOWN -.B ^FDOWN +.SCITECO_TOPIC ^KDOWN +.B ^KDOWN .TQ -.SCITECO_TOPIC ^FUP -.B ^FUP +.SCITECO_TOPIC ^KUP +.B ^KUP Inserted when the down/up cursor keys are pressed. .TP -.SCITECO_TOPIC ^FLEFT -.B ^FLEFT +.SCITECO_TOPIC ^KLEFT +.B ^KLEFT .TQ -.SCITECO_TOPIC ^FSLEFT -.B ^FSLEFT +.SCITECO_TOPIC ^KSLEFT +.B ^KSLEFT Inserted when the left or shift-left cursor keys are pressed. .TP -.SCITECO_TOPIC ^FRIGHT -.B ^FRIGHT +.SCITECO_TOPIC ^KRIGHT +.B ^KRIGHT .TQ -.SCITECO_TOPIC ^FSRIGHT -.B ^FSRIGHT +.SCITECO_TOPIC ^KSRIGHT +.B ^KSRIGHT Inserted when the right or shift-right cursor keys are pressed. .TP -.SCITECO_TOPIC ^FHOME -.B ^FHOME +.SCITECO_TOPIC ^KHOME +.B ^KHOME .TQ -.SCITECO_TOPIC ^FSHOME -.B ^FSHOME +.SCITECO_TOPIC ^KSHOME +.B ^KSHOME Inserted when the Home or shift-Home keys are pressed. .TP -.SCITECO_TOPIC ^FF -.BI ^FF x -Inserted when the Fx-key is pressed +.SCITECO_TOPIC ^KF +.BI ^KF x +Inserted when the F\fIx\fP-key is pressed .RI ( x is a number between 0 and 63). .TP -.SCITECO_TOPIC ^FDC -.B ^FDC +.SCITECO_TOPIC ^KDC +.B ^KDC .TQ -.SCITECO_TOPIC ^FSDC -.B ^FSDC +.SCITECO_TOPIC ^KSDC +.B ^KSDC Inserted when the Delete or shift-Delete key is pressed. .TP -.SCITECO_TOPIC ^FIC -.B ^FIC +.SCITECO_TOPIC ^KIC +.B ^KIC .TQ -.SCITECO_TOPIC ^FSIC -.B ^FSIC +.SCITECO_TOPIC ^KSIC +.B ^KSIC Inserted when the Insert or shift-Insert key is pressed. .TP -.SCITECO_TOPIC ^FPPAGE -.B ^FPPAGE +.SCITECO_TOPIC ^KPPAGE +.B ^KPPAGE .TQ -.SCITECO_TOPIC ^FNPAGE -.B ^FNPAGE +.SCITECO_TOPIC ^KNPAGE +.B ^KNPAGE Inserted when the Page-Up or Page-Down key is pressed. .TP -.SCITECO_TOPIC ^FPRINT -.B ^FPRINT +.SCITECO_TOPIC ^KPRINT +.B ^KPRINT .TQ -.SCITECO_TOPIC ^FSPRINT -.B ^FSPRINT +.SCITECO_TOPIC ^KSPRINT +.B ^KSPRINT Inserted when the Print or shift-Print key is pressed. .TP -.SCITECO_TOPIC ^FA1 -.B ^FA1 +.SCITECO_TOPIC ^KA1 +.B ^KA1 .TQ -.SCITECO_TOPIC ^FA3 -.B ^FA3 +.SCITECO_TOPIC ^KA3 +.B ^KA3 .TQ -.SCITECO_TOPIC ^FB2 -.B ^FB2 +.SCITECO_TOPIC ^KB2 +.B ^KB2 .TQ -.SCITECO_TOPIC ^FC1 -.B ^FC1 +.SCITECO_TOPIC ^KC1 +.B ^KC1 .TQ -.SCITECO_TOPIC ^FC3 -.B ^FC3 +.SCITECO_TOPIC ^KC3 +.B ^KC3 Inserted when the numeric key pad's upper left key (7), upper right key (9), central key (5), lower left key (1), or lower right key (3) is pressed and num-lock is disabled. The key-pad's cursor keys are handled like the regular cursor keys. .TP -.SCITECO_TOPIC ^FEND -.B ^FEND +.SCITECO_TOPIC ^KEND +.B ^KEND .TQ -.SCITECO_TOPIC ^FSEND -.B ^FSEND +.SCITECO_TOPIC ^KSEND +.B ^KSEND Inserted when the End or shift-End key is pressed. .TP -.SCITECO_TOPIC ^FHELP -.B ^FHELP +.SCITECO_TOPIC ^KHELP +.B ^KHELP .TQ -.SCITECO_TOPIC ^FSHELP -.B ^FSHELP +.SCITECO_TOPIC ^KSHELP +.B ^KSHELP Inserted when the Help or shift-Help key is pressed. .TQ -.SCITECO_TOPIC ^FCLOSE -.B ^FCLOSE -ISCITECO_TOPIC when the Close key has been pressed. +.SCITECO_TOPIC ^KCLOSE +.B ^KCLOSE Inserted when the Close key has been pressed. More importantly, this key is emulated in some GUIs (notably GTK+) when the user tries to close \*(ST's @@ -266,34 +294,50 @@ This allows customizing \*(ST's behaviour when program termination is requested (e.g. only quit if there are no unsaved buffers). The close key is also special because -it has a default action if function key macros are -disabled or the \(lq^FCLOSE\(rq macro is undefined: +it has a default action if the \(lq^KCLOSE\(rq macro is undefined: It unconditionally quits \*(ST. The default action is \fBnot\fP performed when -\(lq^FCLOSE\(rq has merely been masked out in the +\(lq^KCLOSE\(rq has merely been masked out in the current parser state (see below). +.TP +.BI ^K x +Any other key with printable representation and all control codes +are looked up with a \(lq^K\(rq prefix. +\fIx\fP can usually only be a single Unicode glyph. +\# Although the result of IMEs is looked up in Gtk, which I suppose +\# can be multiple codepoints. +If undefined, \fIx\fP is inserted unmodified. +\# NOTE: Since all function key macros are longer than 2 +\# characters, there shouldn't be any namespace collisions. . .LP -\(lq^F\(rq corresponds to CTRL+F in the above list but +\(lq^K\(rq corresponds to CTRL+K (ASCII code 11) in the above list but might be typed with a caret due to string building characters in long Q-Register names. The names are all derived from key definitions of the curses library \(em not all of them may be supported on any particular user interface. .LP -By default function key macros are effective everywhere \(em -pressing a function key has the same effect as processing -the characters of the corresponding function key macro as +The result of key macro expansion differs from +consecutive key presses in that they are considered an unity. +If insertion of a single character fails (raises an error), +the entire macro expansion is automatically rubbed out. +.LP +By default key macros are effective everywhere \(em +pressing a key has the same effect as processing +the characters of the corresponding key macro as immediate editing commands (or self-inserting characters). -However function key macros that rewrite the current command line +However key macros that rewrite the current command line will only work correctly from specific \*(ST parser states. -\*(ST therefore allows you to mask function key macros in +Another common use of key macros would be to define +aliases of \*(ST commands for non-latin keys on Curses. +\*(ST therefore allows you to mask key macros in specific parser states by evaluating the Q-Register's numeric -part, thus allowing you to control \fIwhere\fP a function key +part, thus allowing you to control \fIwhere\fP a key macro is effective. The numeric part represents a bitmask of states where -function keys are \fIdisabled\fP (so the default value 0 -enables that function key everywhere). +keys macros are \fIdisabled\fP (so the default value 0 +enables that key macro everywhere). \*(ST defines the following state flags: .IP 1 4 Bit 0 represents the \(lqstart\(rq state where \*(ST accepts the @@ -302,23 +346,27 @@ This is the state you will want command line editing macros to be enabled in. .IP 2 Bit 1 represents any string argument. +.IP 4 +Bit 2 represents any case insensitive syntactic character. +This is the state you might want to use for translating +non-latin characters to their latin equivalent. .LP All other bits/flags represent any other parser state. Consequently, setting the register to the inverse of a bitmask of state flags enables the corresponding macro only for the specified states. -For instance, to enable the \(lq^FRIGHT\(rq function key macro +For instance, to enable the \(lq^KRIGHT\(rq key macro only in the \(lqstart\(rq state, you could set: .SCITECO_TT .EX -1^_U[^FRIGHT] +1^_U[^KRIGHT] .SCITECO_TT_END .EE .LP -A set of useful Function Key Macros are provided in the +A set of useful key macros for function keys is provided in the standard library .BR fnkeys.tes . -It demonstrates how Function Key Macros may be used to define +It demonstrates how key macros may be used to define alternate Escape keys (so the delay issue is not experienced), or do insertion and command-line editing using function keys. . @@ -1069,11 +1117,27 @@ Every document has a current position called dot (after the \(lq.\(rq command that returns it). A document may contain any sequence of bytes but positions refer to characters that might not correspond to individual -bytes depending on the document's encoding. +bytes depending on the document's encoding (see \fBEE\fP command). +The \fB^E\fP command can be used to translate between byte +and character/glyph positions. Consequently when querying the code at a character position or inserting characters by code, the code may be an Unicode codepoint instead of byte-sized integer. -Currently however, \*(ST will only handle ASCII files. +.LP +Currently, \*(ST supports buffers in UTF-8 and single-byte +ANSI encodings, that can also be used for editing raw binary files. +\# You can configure other single-byte code pages with EE, +\# but there isn't yet any way to insert characters. +UTF-8 is the default codepage for new buffers and Q-Registers +unless the 2nd \fBED\fP flag bit is set. +You can also specify \fB--8bit\fP to optimize \*(ST for +8-bit cleanliness. +While navigation in documents with single-byte encodings +takes place in constant time, \*(ST uses heuristics in +UTF-8 documents for translating between byte and character +offsets which are slower especially when \(lqjumping\(rq +into very large lines. +\# But there are optimizations for R, C and A... .LP .SCITECO_TOPIC "EOL translation" To simplify working with files using different end of line @@ -1461,16 +1525,27 @@ The existence of a clipboard register can thus be checked in macros to determine whether getting and modifying that particular clipboard is supported natively. .br -.SCITECO_TOPIC xterm +.SCITECO_TOPIC OSC-52 xterm \*(ST does \fBnot\fP generally support clipboards on ncurses, -but has special support when used with a sufficiently recent version -of \fBxterm\fP(1). -Since the operability of XTerm clipboards cannot be tested +but has special support for OSC-52 escape sequences, as were +introduced by sufficiently recent versions of +.BR xterm (1) +and have since been adopted by several other terminal emulators. +Since the operability of OSC-52 clipboards cannot be tested automatically, users will have to set the flag 256 of the -\fBED\fP flags if and only if their XTerm is configured for allowing +\fBED\fP flags if and only if their terminal emulator is properly +configured. +.BR xterm (1) +for instance must be configured for allowing the \fISetSelection\fP and \fIGetSelection\fP window operations. -\*(ST will still check whether XTerm is actually used in -a particular session. +If running under +.BR xterm (1), +\*(ST will still check whether the XTerm version is sufficient. +.SCITECO_TOPIC Kitty +Other terminal emulators like Kitty may ask for permission to read the +clipboard (\fBread-clipboard-ask\fP). +This is not supported by \*(ST and must be disabled +(use \fBread-clipboard\fP instead). .SCITECO_TOPIC xclip If native clipboard support is unavailable, users may still fall back to using external tools like \fBxclip\fP(1) @@ -1493,11 +1568,11 @@ the original clipboard contents, though. The numeric parts of the clipboard registers are currently not used by \*(ST. .TP -.BI ^F key -Function key registers as documented in section -\fBKEY TRANSLATION\fP. -Their string-content represents a function key macro -and their numeric part is a function key mask. +.BI ^K key +Key macro registers as documented in section +.BR "KEY TRANSLATION" . +Their string-content represents a key macro +and their numeric part is a key macro mask. None of those registers are automatically initialized on startup. .TP @@ -1571,7 +1646,8 @@ contents of the search register you could write: [_ Sfoo$ ]_ .SCITECO_TT_END .EE -. +To copy the string and numeric contents of register \(lqA\(rq to \(lqB\(rq, +you could write \(lq[a ]b\(rq. . .SH STRING-BUILDING CHARACTERS .SCITECO_TOPIC "string building" @@ -1588,7 +1664,9 @@ stages: .IP 1. 4 Carets followed by characters are translated to control codes, so \(lq^a\(rq and \(lq^A\(rq are equivalent to CTRL+A (code 1). -A double caret \(lq^^\(rq is translated to a single caret. +\# FIXME: Should we change the double-caret behavior? +A double caret \(lq^^\(rq is translated to a single caret, +but Ctrl+caret (code 30) is not translated at all. This caret-handling is independent of the caret-handling in command names. .IP 2. @@ -1616,22 +1694,29 @@ thus refers to the corresponding control code: Escape character \fIc\fP. The character is not handled as a string building or string termination character, so for instance \(lq^Q^Q\(rq translates to \(lq^Q\(rq. +Furthermore, some immediate editing commands are inhibited right after \fB^Q\fR, +so you can type \(lq^Q^U\(rq and \(lq^Q^W\(rq, which translate to control codes +21 and 23. .TP .SCITECO_TOPIC ^V^V ^Vc lower .B ^V^V .TQ .BI ^V c -Translates all following characters into lower case. +Translates all following characters, including the expansions of \fB^EQ\fP, +\fB^EU\fP etc., into lower case. When \fB^V\fP is not followed by \fB^V\fP, a single character \fIc\fP is lower-cased. +\# Which is pretty pointless nowadays. .TP .SCITECO_TOPIC ^W^W ^Wc .B ^W^W .TQ .BI ^W c Analogous to \fB^V\fP, but upper-cases characters. +Since \fB^W\fP is an immediate editing command, this can practically be typed +only with upcarets in interactive mode. .TP -.SCITECO_TOPIC ^E\\ ^E\\q +.SCITECO_TOPIC ^E\[rs] ^E\[rs]q .BI ^E\(rs q Expands to the formatted number stored in the numeric part of Q-Register \fIq\fP. @@ -1648,6 +1733,12 @@ Expands to the character whose code is stored in the numeric part of Q-Register \fIq\fP. For instance if register \(lqA\(rq contains the code 66, \(lq^EUa\(rq expands to the character \(lqB\(rq. +The interpretation of this code depends on the context. +Within inserts and searches (\fBI\fP, \fBS\fP, etc.) bytes or Unicode codepoints +are expected depending on the buffer's encoding. +Operations on registers (\fBEU\fP) similarily consult the +register's encoding. +Everything else expects Unicode codepoints. .TP .SCITECO_TOPIC ^EQ ^EQq .BI ^EQ q @@ -1698,6 +1789,14 @@ The following pattern match constructs are supported for matching one character in different character classes (caret-notations refer to the corresponding control characters): .TP +.BI ^Q c +.TQ +.BI ^R c +Escape character \fIc\fP. +Since these are interpreted as string building characters as well, +you may have to type two or three \fB^Q\fP in a row to escape a +pattern match character. +.TP .SCITECO_TOPIC ^S ^EB .B ^S .TQ @@ -2067,17 +2166,17 @@ For instance the following macro inserts \fIn\fP tab characters .TP .SCITECO_TOPIC """A" .IB n \(dqA -Applies if \fIn\fP is the code of an alphabetic character. +Applies if \fIn\fP is the Unicode codepoint of an alphabetic character. .TP .SCITECO_TOPIC """C" .IB n \(dqC -Applies if \fIn\fP is the code of a symbol constituent. +Applies if \fIn\fP is the Unicode codepoint of a symbol constituent. Like in pattern matching, a symbol constituent is defined as an alpha-numeric character, dot, dollar or underscore. .TP .SCITECO_TOPIC """D" .IB n \(dqD -Applies if \fIn\fP is the code of a digit character (0 to 9). +Applies if \fIn\fP is the Unicode codepoint of a digit character. The current radix is insignificant. .TP .SCITECO_TOPIC """I" @@ -2150,16 +2249,16 @@ will commonly write: .TP .SCITECO_TOPIC """R" .IB n \(dqR -Applies if \fIn\fP is the code of an alpha-numeric character. +Applies if \fIn\fP is the Unicode codepoint of an alpha-numeric character. .TP .SCITECO_TOPIC """V" .IB n \(dqV -Applies if \fIn\fP is the code of a lower-case alphabetic +Applies if \fIn\fP is the Unicode codepoint of a lower-case alphabetic character. .TP .SCITECO_TOPIC """W" .IB n \(dqW -Applies if \fIn\fP is the code of a upper-case alphabetic +Applies if \fIn\fP is the Unicode codepoint of an upper-case alphabetic character. .LP There are also a number of flow-control commands like @@ -2219,6 +2318,7 @@ This manual mentions differences on several occasions. . .SH SEE ALSO . +.\" FIXME: The URLs do not format in FreeBSD's man or in woman pages. .TP Program invocation and options: .BR sciteco (1) @@ -2228,16 +2328,19 @@ Scintilla messages and other documentation: Scintilla .UE .TP -Scinterm manual, documenting the mapping of -\(lqRGB\(rq values to terminal colors on curses user interfaces: +Scinterm manual, documenting the mapping of \(lqRGB\(rq values to terminal colors on curses user interfaces: .UR http://foicica.com/scinterm/manual.html Scinterm manual .UE .TP -Gtk+ 3 documentation, containg details about -its CSS support and syntax: -.UR https://developer.gnome.org/gtk3/stable/GtkCssProvider.html -GtkCssProvider +Suitable terminal fonts for icon support in Curses (see \fBED\fP flags): +.UR https://www.nerdfonts.com/ +Nerd Fonts +.UE +.TP +Gtk+ 3 documentation, containg details about its CSS support and syntax: +.UR https://docs.gtk.org/gtk3/css-overview.html +Overview of CSS in GTK .UE . . |