NAME

sciteco -- Scintilla-based Text Editor and COrrector

SYNOPSIS

sciteco [-h|--help] [-e|--eval macro] [-m|--mung] [--no-profile] [-8|--8bit] [UI option ...] [--] [script] [argument ...]

DESCRIPTION

SciTECO is an interactive TECO dialect, similar to Video TECO. It also adds features from classic Standard TECO-11, and incorporates many unique new ideas. It is geared towards UNIX-like operating systems but also natively supports Microsoft Windows NT(Tm).

When executed, SciTECO mungs (executes) the TECO macro stored in the file specified in the script argument if --mung is given or the macro specified via --eval respectively. Munged files and macros are executed in non-interactive (batch) mode, allowing the user to write stand-alone TECO scripts. Only when munging files as opposed to other means of executing macros, the first line is ignored if it begins with a “#” (hash sign). Therefore under UNIX-like operating systems, TECO macro files may be invoked as scripts by using a Hash-Bang line like

#!/usr/local/bin/sciteco -m

Note that UNIX Hash-Bang lines will only pass a single argument to the interpreter before the script's file name, so all required SciTECO options must be mangled into a single argument with their single-letter names. Passing option-like arguments (beginning with a dash) to scripts may cause problems because SciTECO might try to interpret these options. SciTECO thus stops parsing at the first non-option argument (which will always be the munged file name in a script invocation).

Upon startup SciTECO's buffer ring contains only one unnamed empty buffer. All command line arguments after the SciTECO options are passed as arguments to the munged macro by placing each argument on its own line in the buffer. The script file name expected when “--mung” is given is currently not considered a macro argument. In any case the current buffer position (called dot) is left at the beginning of the buffer. Optionally “--” might be used to explicitly separate SciTECO options and macro arguments.

If the munged macro does not request program termination using the EX command or exits using ^C, SciTECO will automatically switch into its graphical interactive mode. SciTECO may be built with different graphical user interfaces, including Curses and GTK+ based ones. Eventually when the user terminates interactive mode by calling EX, SciTECO will return to its batch mode before exiting. SciTECO macros may still execute in batch mode after leaving interactive mode and shutting down any GUI if the user has configured ED hooks (see sciteco(7)).

The differences between batch and interactive mode are outlined below:

In batch mode, no terminal interaction takes place beyond writing plain-text messages to the stdout and stderr file descriptors. stdin is currently not read in batch mode. It is therefore safe to redirect SciTECO's stdout or stderr into files or pipes. On most UIs, it is even safe to redirect stdout or stderr if SciTECO enters interactive mode. Depending on the GUI compiled into SciTECO, either nothing is written to these streams while in interactive mode, or messages are continued to be written to these streams (in addition to being displayed in the GUI).
Messages logged to stdout or stderr — except for messages written explicitly via some SciTECO command — are prefixed with a string signifying the message's severity. In interactive mode, messages are also shown in a GUI-dependant manner.
In batch mode, any SciTECO command failure will terminate the program. A full stack trace of SciTECO macro invocations will be printed to stderr and the process' return code will signify failure. In interactive mode, SciTECO will “rub out” any character resulting in a command failure.
The interactive mode enables character rub-out and thus undoing of command side-effects. Therefore code runs significantly slower in interactive mode and all algorithms have non-constant memory requirements as they will constantly accumulate “undo tokens”. Batch mode does not have these restrictions.
A few commands that modify the command line are only available in interactive mode.

If the --mung option is absent, SciTECO will mung $SCITECOCONFIG/.teco_ini (if existing) which is called the profile. On UNIX/Linux, the default profile is at ~/.teco_ini (see ENVIRONMENT). It will consequently not expect a script file name as the first non-option argument. The profile will usually set up various Scintilla and SciTECO options, configure syntax highlighting, define commonly used macros and open files specified as arguments to SciTECO. It will usually leave the editor in interactive mode. Profile execution can be suppressed with the --no-profile option.

OPTIONS

-h, --help: Display a short help text on the console.
-e, --eval macro: Evaluate (execute) macro specified as a command-line option. Similar to munging but always exits afterwards. If the option is specified, the --mung option has no effect.
-m, --mung: Mung script. The script file name is expected as the first non-option argument, so it does not necessarily have to follow the --mung option. Default is $SCITECOCONFIG/.teco_ini.
--no-profile: Do not mung any profile. This leaves the editor in interactive mode with default settings just as if no profile existed or like when munging an empty file. This is useful to fix up a broken profile script. This option has no effect when a file is explicitly munged with --mung.
-8, --8bit: Use raw single-byte ANSI encoding by default and disable automatic EOL conversion, which optimizes SciTECO for 8-bit cleanliness. It is equivalent to executing “16,4ED”, but since it is executed very early at startup, all Q-Registers and the unnamed buffer will already be in ANSI encoding. This option is also useful when munging the profile macro.
UI options ...: Some graphical user interfaces, notably GTK+, provide additional command line options. Execute “sciteco --help” for more details.

EXIT STATUS

SciTECO will return a non-null exit code if an error occurred during batch mode processing.

ENVIRONMENT

Before SciTECO executes any macro, all of the variables in the process environment are inserted into the global Q-Register table. A dollar sign is prepended before each variable name, so that for instance the variable “HOME” can be examined by macros by reading the string-content of Q-Register “$HOME”.

Changes to these environment registers are not applied to the process environment for technical reasons. Nevertheless, SciTECO will always access the environment registers instead of the process environment when it needs to evaluate an environment variable internally. Furthermore, when spawning subprocesses, SciTECO will export all Q-Registers beginning with “$” that do not have a “=” in their name into the subprocess environment. Therefore, the subset of Q-Registers whose name begins with “$” can be considered practically identical to the process environment and SciTECO macros can access, modify and extend the environment using these registers.

The following environment variables and registers are initialized with default values by SciTECO if they are unset:

HOME: Home directory of the current user. This may be used e.g. by the FG command and for tilde-expansions. If unset, it defaults to the current user's home directory as set by passwd(5) or as determined by other platform-dependent means. Initialization of this variable ensures that the “$HOME” Q-Register is available even on Windows and the home directory can always be re-configured.
SHELL or COMSPEC: Path of the command interpreter used by EG and EC commands if UNIX98 shell emulation is disabled. SHELL is used on UNIX-like systems, while COMSPEC is used on DOS-like systems (like Windows). Both variables are usually already set in the process environment but are initialized to “/bin/sh” or “cmd.exe” should they nevertheless be unset. Since environment variables are case-insensitive on DOS-like systems and different spellings exist for COMSPEC, the name of the variable is always normalized to all-upper-case by SciTECO.
SCITECOCONFIG: Path where SciTECO looks for configuration files. For instance, this is the path of the default profile. If unset, this variable defaults to the HOME environment variable on Unix. On Windows, this variable defaults to the location of the SciTECO program executable, so that SciTECO is self-contained on Windows. On other platforms, this variable defaults to some other user-specific configuration directory.
SCITECOPATH: Standard library macro path. Macros can expect to find standard library macros in this directory. On Windows, this variable defaults to the “lib” subdirectory of the directory containing the SciTECO program executable, so that SciTECO is self-contained on Windows. On all other platforms (including UNIX/Linux) this variable defaults to the standard library installation path at /usr/local/share/sciteco/lib.

The HOME, SCITECOCONFIG and SCITECOPATH environment variables and registers are canonicalized to absolute paths. Therefore it is possible to define them relative to the working directory of SciTECO when it starts up while macros can work with the corresponding registers to locate files even when the working directory of SciTECO is changed later on.

Additionally SciTECO may be influenced by the environment variables accessed by glib. On a Curses UI, there are other important environment variables like TERM, LINES, COLUMNS and ESCDELAY that may be accessed when SciTECO enters interactive mode. For ncurses, see section ENVIRONMENT in ncurses(3NCURSES) for details. SciTECO exports the environment registers into the process environment before initializing Curses, so these variables can be modified in the profile macro.

On GTK+, you may turn off the infamous client-side window decorations by setting the environment variable GTK_CSD to “0”.

SIGNALS

SciTECO currently reacts to the following signals or uses them internally:

SIGINT: Interrupts the currently running macro. The character resulting in the macro execution will fail causing SciTECO to exit in batch mode, or reject the character resulting in the execution when in interactive mode. For instance, this signal will interrupt long-running loops. If the GUI is waiting on user input, this signal is effectively ignored. Some GUIs may depend on delivery of SIGINT when ^C is pressed in order to interrupt macros interactively. Others will poll for keypresses. Note that this signal can usually also be generated when pressing ^C on the process' associated console (also if there is a graphical window).
SIGTERM: Try to gracefully shut down SciTECO. In batch mode this only interrupts the currently running macro similar to SIGINT causing SciTECO to exit. If technically possible, user interfaces will additionally process SIGTERM in interactive mode as if the CLOSE function key has been pressed, which will result in unconditional program termination or user-programmed behaviour.

FILES

$SCITECOCONFIG/.teco_ini: Default profile macro.
/usr/local/share/sciteco/sample.teco_ini: Sample profile macro configuring commonly used run-time options, syntax highlighting, session handling and opening files specified on the command line.
$SCITECOPATH/*.tes: Standard library macros.
.teco-n-filename~: Save point files created by SciTECO when saving files during interactive execution have this format. On Windows, these files have the hidden attribute set. Savepoint files are temporary and should be ignored by version control systems, etc.
$SCITECOCONFIG/.teco_session: Macro storing the default buffer session. This is not written by SciTECO itself, but by the standard library session.tes macros. When the “session.vcs” macro is used, these files will also be created in the roots of Git, Mercurial and Subversion repositories or working copies.
$SCITECOCONFIG/.teco_css: When using the Gtk UI, this will be the location of a CSS file that can be used to apply SciTECO color schemes to the entire UI and to do other style customizations.
/usr/local/share/sciteco/fallback.css: When using the Gtk UI, this is a fallback stylesheet in case $SCITECOCONFIG/.teco_css does not exist. It may also be used as a template for $SCITECOCONFIG/.teco_css.

AUTHOR

This manpage and the SciTECO program was written by Robin Haberkorn.