diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/cheat-sheet.mm | 127 | ||||
| -rw-r--r-- | doc/sciteco.1.in | 52 | ||||
| -rw-r--r-- | doc/sciteco.7.template | 57 |
3 files changed, 164 insertions, 72 deletions
diff --git a/doc/cheat-sheet.mm b/doc/cheat-sheet.mm index 28ecad9..ab404e3 100644 --- a/doc/cheat-sheet.mm +++ b/doc/cheat-sheet.mm @@ -31,6 +31,9 @@ A full language description can be found in .\" The $ is added to standardize the height of all boxes .\" (as it stretches above and below the base line). .\" NOTE: This does not work in arguments to .TD! +.\" NOTE: It would ne nice to round the corners (as in Scintilla/Gtk's +.\" rendition of character representations), but there are no filled +.\" rounded polygons in Groff. .ds FILLSTR \ \R!@wd \w'\\$3$'-\w'$'!\ \h'.1m'\ @@ -102,7 +105,7 @@ They are case-insensitive. . I n . TD Some integer, often optional (1 or 0 by default). -You can write \fC-\fP instead of \fC-1\fP. +You can write \fC\-\fP instead of \fC\-1\fP. . TR bgc=grey90 . TD . I text @@ -126,7 +129,7 @@ Line Feed, i.e. Enter/Return key . TR bgc=grey90 . TD colspan=4 For instance: -\fC-C\fP \(== \fC-1C\fP \(== \fCR\fP \(DI +\fC\-C\fP \(== \fC\-1C\fP \(== \fCR\fP \(DI \fCQa\fP \(== \fCQ[A]\fP \(DI \fCQ#ab\fP \(== \fCQ[AB]\fP \(DI Ctrl+I \(== \*[CTRL ^I] \(== \*[CTRL TAB] \(DI @@ -155,7 +158,7 @@ Redo (Rubin): First \*[CTRL ^G], then Backspace, \*[CTRL ^W]... Exit, but only if no buffer is \(lqdirty\(rq (unsaved) . TRX . TD -\fC-EX\fP\*($$ +\fC\-EX\fP\*($$ . TD Exit even if buffer is \(lqdirty\(rq, i.e. discarding all unsaved changes. . TRX @@ -168,10 +171,10 @@ Exit, saving all \(lqdirty\(rq buffers. .TBLX "Files" width='30% 70%' . TRX . TD -\fCEB\fIfile\fR\*$ +\fCEB\fI\^file\^\fR\*$ . TD Edit buffer or open new \fIfile\fP (glob pattern). -Files, that did not exist on disk, will not be created until you save them. +\#Files, that did not exist on disk, will not be created until you save them. . TRX . TD \fCEB*.c\*$ @@ -187,7 +190,7 @@ Edit the unnamed buffer. . CI 0EB . TD Show buffer ring/list. -You can specify a filename afterwards to open a file. +You can type or click a filename afterwards. . TRX . TD \fIn\fCEB\fR\*$ @@ -202,9 +205,9 @@ Select \fIn\fP-th buffer in ring. Select next buffer in ring. . TRX . TD -\fC-%*\*$ +\fC\-%*\*$ . TD -Select pevious buffer in ring. +Select previous buffer in ring. . TRX . TD . CI EJU* @@ -218,7 +221,7 @@ Write (save) current buffer under its current name. Does not work on the unnamed buffer. . TRX . TD -\fCEW\fIfile\fR\*$ +\fCEW\fI\^file\^\*$ . TD Save current buffer under new name \fIfile\fP (Save As). . TRX @@ -228,12 +231,17 @@ Save current buffer under new name \fIfile\fP (Save As). Finish (close) current buffer. . TRX . TD -. CI -EF +. CI \-EF . TD Finish (close) current buffer, discarding all unsaved changes. . TRX . TD -\fCFG\fIpath\fR\*$ +. CI :EF +. TD +Finish (close) current buffer, saving it if it is \(lqdirty\(rq. +. TRX +. TD +\fCFG\fI\^path\^\fR\*$ . TD Go to folder \fIpath\fP, i.e. change working directory. . TRX @@ -243,7 +251,7 @@ Go to folder \fIpath\fP, i.e. change working directory. Set single byte ASCII mode. . TRX . TD colspan=2 -\fBTip:\fP You can use the Tab-key for autocompleting filenames and paths. +\fBTip:\fP You can use the Tab-key and mouse for autocompleting filenames and paths. .ETB . .NCOL @@ -251,7 +259,7 @@ Set single byte ASCII mode. .TBLX "Text Insertion" width='30% 70%' . TRX . TD -\fCI\fItext\*$ +\fCI\fItext\^\*$ . TD Insert \fItext\fP into buffer. . TRX @@ -266,11 +274,11 @@ Insert single caret (\fC^\fP). Insert \*$ (ASCII 27). . TRX . TD -\*[CTRL TAB]\fItext\*$ +\*[CTRL TAB]\fI\^text\^\*$ . TD Insert \fItext\fP with leading tab/indentation. See also -.pdfhref W -D https://github.com/rhaberkorn/sciteco/wiki/Useful-Macros#indent-code-block -A . \fIn\fCM#it\fP +.pdfhref W -D https://github.com/rhaberkorn/sciteco/wiki/Useful-Macros#indent-code-block -A . \fIn\^\fCM#it\fP .ETB . .TBLX "Text Deletion" width='30% 70%' @@ -353,7 +361,7 @@ Copy next \fIn\fP lines into Q-Register \fIq\fP. Append next \fIn\fP lines to Q-Register \fIq\fP. . TRX . TD -. CI "" n X q\|n K +. CI "" n @X q . TD Cut next \fIn\fP lines into Q-Register \fIq\fP. . TRX @@ -365,8 +373,14 @@ Copy whole buffer into Q-Register \fIq\fP. . TD . CI X\(ti . TD -Copy line into clipboard. See also -.pdfhref W -D https://github.com/rhaberkorn/sciteco/wiki/Useful-Macros#copypaste-from-clipboard -A . \fCM#xc\fP +Copy line into clipboard. +.ig END +. TRX +. TD +. CI G\(ti +. TD +Paste from clipboard. +.END . TRX . TD . CI G q @@ -374,19 +388,19 @@ Copy line into clipboard. See also Get (paste) Q-Register \fIq\fP at current position. . TRX . TD -\fCI\fI...\*[CTRL ^E]\fCQ\fIq +\fCI\fI...\*[CTRL ^E]\fCQ\fI\^q . TD Paste Q-Register \fIq\fP while inserting text. .ig END . TRX . TD -\fCE%\fIq\|file\*$ +\fCE%\fIq\|file\^\*$ . TD Save Q-Register \fIq\fP into \fIfile\fP. .END . TRX . TD -\fCEQ\fIq\*$ +\fCEQ\fI\^q\^\*$ . TD Edit Q-Register \fIq\fP as a text buffer. .ig END @@ -469,23 +483,23 @@ Jump to end of buffer. . TRX . TD colspan=2 \fBTip:\fP Enable the \fCfnkeys.tes\fP module in \fC.teco_ini\fP -to move around with cursor keys! +to move around with cursor keys and mouse! .ETB . .TBLX "External Programs" width='42% 58%' . TRX . TD -\fCEC\fIcommand\*$ +\fCEC\fI\^command\^\*$ . TD Insert output of \fIcommand\fP. . TRX . TD -\fIn\fCEC\fIcommand\*$ +\fIn\fCEC\fI\^command\^\*$ . TD Filter next \fIn\fP lines through \fIcommand\fP. . TRX . TD -\fCHEC\fIcommand\*$ +\fCHEC\fI\^command\^\*$ . TD Filter whole buffer through \fIcommand\fP. . TRX @@ -498,12 +512,12 @@ Sort next \fIn\fP lines (UNIX). .TBLX "Macros" width='42% 58%' . TRX . TD -\fC@\*[CTRL ^U]\fIq\fP{\fImacro\fP} +\fC@\*[CTRL ^U]\fI\^q\fP{\fImacro\fP} . TD Define \fImacro\fP in Q-Register \fIq\fP. . TRX . TD -. CI M q +. CI M \^q . TD Call macro in Q-Register \fIq\fP. . TRX @@ -520,20 +534,25 @@ Discard command-line, storing it in \fIq\fP. . .MC (u;(\nW-0.5c)/3) 0.25c \" 3 columns . -.TBLX "Search & Replace" width='45% 55%' +.TBLX "Search & Replace" width='47% 53%' . TRX . TD -\fCS\fItext\*$ +\fCS\fItext\^\*$ . TD Search for next occurrence of \fItext\fP. . TRX . TD -\fC-S\fItext\*$ +\fCS\fItext\^\*[CTRL $^S]\fCC +. TD +Search for beginning of \fItext\fP. +. TRX +. TD +\fC\-S\fItext\^\*$ . TD Search for previous occurrence of \fItext\fP. . TRX . TD -\fIn\fCS\fItext\*$ +\fIn\fCS\fItext\^\*$ . TD Search for \fIn\fP-th occurrence of \fItext\fP. . TRX @@ -543,37 +562,37 @@ Search for \fIn\fP-th occurrence of \fItext\fP. Repeat last search (pattern from Q-Register \fC_\fP). . TRX . TD -\fCN\fItext\*$ +\fCN\fItext\^\*$ . TD Search for next occurrence of \fItext\fP across all buffers. . TRX . TD -\fCFR\fIfrom\*$\fIto\*$ +\fCFR\fI\^from\^\*$\fI\^to\^\*$ . TD Find next occurrence of \fIfrom\fP and replace it with \fIto\fP. . TRX . TD \fCFR\*($$ . TD -Repeat the last search-replace operation (\fC_\fP and \fC-\fP). +Repeat the last search-replace operation (\fC_\fP and \fC\-\fP). . TRX . TD -\fC<FR\fIfrom\*$\fIto\*$\fC;>\fP +\fC<FR\fI\^from\^\*$\fI\^to\^\*$\fC;>\fP . TD Find and replace all occurrences in buffer beginning at current position. . TRX . TD -\fCFK\fItext\*$ +\fCFK\fItext\^\*$ . TD Find and kill (delete) up to first occurrence of \fItext\fP. . TRX . TD -\fCFD\fItext\*$ +\fCFD\fItext\^\*$ . TD Find and delete first occurrence of \fItext\fP. .ETB . -.TBLX "Control Flow" width='45% 55%' +.TBLX "Control Flow" width='47% 53%' . TRX . TD . CI < commands > @@ -595,10 +614,10 @@ For instance, to add \fC#\fP in front of the next 10 lines: \fC0L10<I#\*$L>\fP .ETB . -.TBLX "Help" width='45% 55%' +.TBLX "Help" width='47% 53%' . TRX . TD -\fC?\fItopic\*$ +\fC?\fItopic\^\*$ . TD Search help for \fItopic\fP (may be command). .ig END \" not yet supported @@ -610,7 +629,7 @@ Search help by word at current position in buffer. .END . TRX . TD colspan=2 -\fBTip:\fP You can use the Tab-key for autocompleting topics. +\fBTip:\fP You can use the Tab-key and mouse for autocompleting topics. .ETB . .NCOL @@ -638,17 +657,17 @@ Matches any alphabetic characters. Matches any digit. . TRX . TD -\*[CTRL ^N]\fIclass\fP +\*[CTRL ^N]\fI\^class\fP . TD Matches any character not in \fIclass\fP. . TRX . TD -\*[CTRL ^E]\fCM\fIpattern\fP +\*[CTRL ^E]\fCM\fI\^pattern\fP . TD Matches many occurrences of \fIpattern\fP. . TRX . TD -\*[CTRL ^E]\fCG\fIq\fP +\*[CTRL ^E]\fCG\fI\^q\fP . TD Matches any character in Q-Register \fIq\fP. . TRX @@ -660,13 +679,13 @@ Matches \fIp\*<1\*>\fP or \fIp\*<2\*>\fP. . TD colspan=2 To remove all trailing whitespace characters, you could type: .br -\fCJ<FR\*[CTRL LF^E]M\*[CTRL ^E][\0,\*[CTRL TAB]]\*[CTRL $LF$];> +\fCJ<FR\*[CTRL ^E]M\*[CTRL ^E][\0,\*[CTRL TAB]]\*[CTRL LF$LF$];> .ETB . .TBLX "String Building" width='40% 60%' . TRX . TD -\*[CTRL ^E]\fCQ\fIq +\*[CTRL ^E]\fCQ\fI\^q . TD Expand to string contents of Q-Register \fIq\fP. . TRX @@ -681,7 +700,7 @@ Expand to integer contents of Q-Register \fIq\fP. Expand to character represented by codepoint in Q-Register \fIq\fP. . TRX . TD -\*[CTRL ^Q]\fIx +\*[CTRL ^Q]\fI\^x . TD Quote (escape) the following character \fIx\fP. . TRX @@ -742,12 +761,12 @@ Also try Shift+Delete if \fCfnkeys.tes\fP is loaded. Assign number \fIn\fP to Q-Register \fIq\fP. . TRX . TD -. CI -U q +. CI \-U q . TD Assign -1 to Q-Register \fIq\fP. . TRX . TD -. CI Q q +. CI Q \^q . TD Query (get) integer from Q-Register \fIq\fP. . TRX @@ -762,12 +781,12 @@ Add \fIn\fP to Q-Register \fIq\fP and return new value. Increase Q-Register \fIq\fP and return new value. . TRX . TD -. CI -% q +. CI \-% q . TD Decrease Q-Register \fIq\fP and return new value. . TRX . TD -\*[CTRL ^^]\fIx +\*[CTRL ^^]\fI\^x . TD Codepoint of character \fIx\fP. . TRX @@ -792,7 +811,7 @@ Insert integer \fIn\fP into buffer at current position. Add \fIn\fP to number at current position in buffer. . TRX . TD -\fIn\*[CTRL ^_] +\fIn\^\*[CTRL ^_] . TD Binary negate \fIn\fP \(em negate TECO boolean. . TRX @@ -807,7 +826,7 @@ These are independent. Setting a number does not change the string part! .ETB . -.TBLX "Syntax Highlighting (lexers.tes)" width='60% 40%' +.TBLX "Syntax Highlighting (lexers.tes)" width='61% 39%' . TRX . TD . CI M[lexer.set. name ] @@ -815,7 +834,7 @@ Setting a number does not change the string part! Set lexer (syntax highlighting) for language \fIname\fP. . TRX . TD colspan=2 -\fBTip:\fP You can use the Tab-key for autocompleting long Q-Register +\fBTip:\fP You can use the Tab-key and mouse for autocompleting long Q-Register names (and therefore Lexer names). .ETB \# EOF
\ No newline at end of file diff --git a/doc/sciteco.1.in b/doc/sciteco.1.in index 2b3d3bf..b7084c5 100644 --- a/doc/sciteco.1.in +++ b/doc/sciteco.1.in @@ -21,7 +21,7 @@ Scintilla-based \fBT\fPext \fBE\fPditor and \fBCO\fPrrector .OP "--no-profile" .OP "-8|--8bit" .RI [ "UI option .\|.\|." ] -.OP "--" +.OP "--|-S" .RI [ script ] .RI [ "argument .\|.\|." ] .YS @@ -86,7 +86,9 @@ In any case the current buffer position (called .IR dot ) is left at the beginning of the buffer. Optionally \(lq\-\-\(rq might be used to explicitly separate \*(ST options and -macro arguments. +macro arguments, but is never passed down as a macro argument. +Since it's sometimes useful to pass down \(rq\-\-\(rq to the profile macro, +you can use \(lq\-S\(rq, which is equivalent to \(lq\-\- \-\-\(rq. . .LP If the munged macro does not request program termination using the @@ -155,7 +157,14 @@ the first non-option argument. The profile will usually set up various Scintilla and \*(ST options, configure syntax highlighting, define commonly used macros and open files specified as arguments to \*(ST. -It will usually leave the editor in interactive mode. +The recommended command-line processor from \(lqopener.tes\(rq allows +opening files on specific lines or lines and columns +(\fB+\fIline\fR[\fB,\fIcolumn\fR] \fIfilename\fP or +\fIfilename\fB:\fIline\fR[\fB:\fIcolumn\fR][\fB:\fR]). +This special syntax can be inhibited by prefixing the files names with the +special \(lq\-S\(rq separator. +.LP +The profile macro will usually leave the editor in interactive mode. Profile execution can be suppressed with the .B \-\-no\-profile option. @@ -289,12 +298,6 @@ on Windows. On all other platforms (including UNIX/Linux) this variable defaults to the standard library installation path at .BR "@scitecolibdir@" . -.TP -.SCITECO_TOPIC "$SCITECO_SCINTILLUA_LEXERS" -.B SCITECO_SCINTILLUA_LEXERS -The Scintillua \(lqlexers/\(rq directory. -This is passed as the \(lqscintillua.lexers\(rq library property when -loading a Scintillua lexer via the \fBSCI_SETILEXER\fP Scintilla message. . .LP The \fBHOME\fP, \fBSCITECOCONFIG\fP and \fBSCITECOPATH\fP environment @@ -321,9 +324,40 @@ environment before initializing Curses, so these variables can be modified in the profile macro. . .LP +.SCITECO_TOPIC "$SCITECO_CLIPBOARD_SET" "$SCITECO_CLIPBOARD_GET" +On ncurses, in addition to the OSC-52 protocol, you can use external +processes to drive the built-in clipboard Q-Registers (\(lq~\(rq and so on). +For that you can set the \fBSCITECO_CLIPBOARD_SET\fP and \fBSCITECO_CLIPBOARD_GET\fP +environment variables or their corresponding Q-Registers to shell commands, +that receive the clipboard contents on stdin or output the requested clipboard on stdout. +In the configured commands, the string \(lq{}\(rq is replaced with a single +letter code of the clipboard to set: +\(lqc\(rq, \(lqp\(rq or \(lqs\(rq as in the clipboard register names. +The given commands will always be executed by \fB/bin/sh\fP, regardless of +the \fBSHELL\fP environment variable or +the value of bit 8 (128) in the \fBED\fP flags. +The spawned processes also do not currently inherit the environment from the +Q-Register environment variables, i.e. you cannot change the process environment +via \*(ST code. +\# That would only be possible by rewriting everything with GSpawn. +.SCITECO_TOPIC xclip +See +.B @scitecodatadir@/sample.teco_ini +for an example of how to integrate the X11 clipboard via +.BR xclip (1). +Integrating with Wayland and the Mac OS clipboards is of course also possible. +. +.LP +.SCITECO_TOPIC "$GTK_CSD" On GTK+, you may turn off the infamous client-side window decorations by setting the environment variable \fBGTK_CSD\fP to \(lq0\(rq. . +.LP +.SCITECO_TOPIC "$SCITECO_SCINTILLUA_LEXERS" +The \fBSCITECO_SCINTILLUA_LEXERS\fP environment variable specifies +the Scintillua \(lqlexers/\(rq directory. +This is passed as the \(lqscintillua.lexers\(rq library property when +loading a Scintillua lexer via the \fBSCI_SETILEXER\fP Scintilla message. . .SH SIGNALS . diff --git a/doc/sciteco.7.template b/doc/sciteco.7.template index f9cad80..b274715 100644 --- a/doc/sciteco.7.template +++ b/doc/sciteco.7.template @@ -300,6 +300,15 @@ The default action is \fBnot\fP performed when \(lq^KCLOSE\(rq has merely been masked out in the current parser state (see below). .TP +.SCITECO_TOPIC ^KMOUSE +.B ^KMOUSE +Mouse event occurred. +This will not be delivered on Curses unless bit 7 (64) is set in the +\fBED\fP flags. +You can use \fBEJ\fP with negative keys to retrieve +the event type, mouse coordinates and other information +about the last mouse event. +.TP .BI ^K x Any other key with printable representation and all control codes are looked up with a \(lq^K\(rq prefix. @@ -746,10 +755,12 @@ Global and local Q-Registers are not affected by command line termination. .SS Auto Completion . .SCITECO_TOPIC autocomplete -The immediate editing commands that perform auto-completions, do +The immediate editing commands, that perform auto-completions, do so in a manner similar to Posix shells. Upon first invocation they try to fully or partially complete the file name (or token). +If the token can be fully completed, the current command or Q-Register +specification will also usually be terminated automatically. If no completion can be performed, the invocation will display a list of file names (or tokens) that begin with the token to complete in \*(ST's popup area. @@ -761,6 +772,15 @@ of file names or tokens is displayed in the popup area. I.e. it is possible to cycle through long lists of possible auto-completions. .LP +You can also scroll through the popup area with the mouse wheel. +Furthermore, you can click on entries in the popup area with the +mouse in order to fully complete them. +Often this will also automatically terminate the current command or +Q-Register specification, just like an unambiguous completion via +immediate editing commands. +On Curses, mouse events are not processed unless bit 7 (64) is set +in the \fBED\fP flags. +.LP When completing file names, hidden files are not considered for completion unless a prefix of the hidden file's name has already been typed. @@ -780,6 +800,13 @@ file names with \(lq./\(rq. This is useful for writing cross-platform \*(ST macros (see .BR "FILE NAMES AND DIRECTORIES" ). .LP +File name completions are case-sensitive or insensitive depending +on operating system defaults. +On some operating systems \*(ST can determine the case-sensitivity +of individual directories as well. +\# Should be supported on Mac OS and newer versions of Windows, +\# but it's still untested. +.LP Note that completions take place after string building and tilde-expansion is also performed by file name completions, so for instance both \(lq~/foo\(rq and \(lq^EQ[$HOME]/foo\(rq @@ -1553,10 +1580,10 @@ 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 +\*(ST supports two ways of driving the clipboard on ncurses. .SCITECO_TOPIC OSC-52 xterm -\*(ST does \fBnot\fP generally support clipboards on ncurses, -but has special support for OSC-52 escape sequences, as were -introduced by sufficiently recent versions of +First of all, there is built-in 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 @@ -1566,6 +1593,7 @@ configured. .BR xterm (1) for instance must be configured for allowing the \fISetSelection\fP and \fIGetSelection\fP window operations. +It is nevertheless observed to be a very buggy and unreliable feature. If running under .BR xterm (1), \*(ST will still check whether the XTerm version is sufficient. @@ -1574,10 +1602,16 @@ 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) -with the \fBEC\fP command. +.br +Alternatively, if OSC-52 clipboards are disabled, you can set the +\fB$SCITECO_CLIPBOARD_SET\fP and \fB$SCITECO_CLIPBOARD_GET\fP +environment variables (or corresponding Q-Registers) to shell +commands, that receive the clipboard +contents on stdin and output the requested clipboard on stdout. +This allows integrating with various windowing environments. +See \fBENVIRONMENT\fP in +.BR sciteco (1) +for more details. .br Setting the string part of a clipboard register will set that clipboard. \*(ST will perform automatic EOL-translation according @@ -2078,7 +2112,7 @@ The most basic flow control command in \*(ST is the Go-to command. Since it is really an ordinary command, exceptional only in setting the program counter and influencing parsing, it is described in this document's command reference. -\*(ST may do simple unconditional and computed gotos. +\*(ST can perform simple unconditional and computed gotos. .LP .SCITECO_TOPIC label Labels are symbolic and are defined with the following syntax: @@ -2093,9 +2127,14 @@ When a label is encountered, it is cached in a macro-invocation level specific goto table if it is not in there already. Therefore every macro invocation has its own label namespace and gotos to a label have constant complexity once a label has been parsed. +\# The table lookup is not constant of course. Terminating a macro execution (or command line) fails if a label that is jumped to has not been defined. Labels are also historically used as comments in TECO code. +That's why \*(ST allows several identical labels in the same scope \(em +goto commands will always jump to the first occurrance of the label. +In case of label redefinition, a warning will be printed, so you are +encouraged to use \(lqtrue\(rq comments as described below. . .SS Comments .SCITECO_TOPIC comment |