path: root/doc/sciteco.1.in

.ds ST \\fB@PACKAGE_NAME@\\fP
.
.
.TH "@PACKAGE@" 1 \
    "@DATE@" \
    "@PACKAGE_NAME@ Version @PACKAGE_VERSION@"
.
.
.SH NAME
@PACKAGE@ \-\-
Scintilla-based \fBT\fPext \fBE\fPditor and \fBCO\fPrrector
.
.
.SH SYNOPSIS
.
.SCITECO_TOPIC "sciteco"
.SY @PACKAGE@
.OP "-h|--help"
.OP "-e|--eval" macro
.OP "-m|--mung"
.OP "--no-profile"
.OP "-8|--8bit"
.RI [ "UI option .\|.\|." ]
.OP "--|-S"
.RI [ script ]
.RI [ "argument .\|.\|." ]
.YS
.
.
.SH DESCRIPTION
.
\*(ST is an interactive
.B TECO
dialect, similar to
.BR "Video TECO" .
It also adds features from classic
.BR "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.
.
.LP
.SCITECO_TOPIC mung
When executed, \*(ST mungs (executes) the TECO macro stored in the file
specified in the \fIscript\fP argument if
.B "--mung"
is given or the macro specified via
.B "--eval"
respectively.
Munged files and macros are executed in non-interactive (\fIbatch\fP)
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 \(lq#\(rq (hash sign).
Therefore under UNIX-like operating systems, TECO macro files may be
invoked as scripts by using a Hash-Bang line like
.\" FIXME: We'd like to include #! as a topic, but ! character are currently
.\" not allowed since they are not escaped correctly.
.SCITECO_TOPIC scripting
.RS
.SCITECO_TT
.EX
#!@bindir@/sciteco -m
.SCITECO_TT_END
.EE
.RE
.
.LP
Note that UNIX Hash-Bang lines will only pass a \fBsingle\fP argument to the
interpreter before the script's file name, so all required \*(ST 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 \*(ST might try to interpret these options.
\*(ST thus stops parsing at the first non-option
argument (which will always be the munged file name in a script invocation).
.
.LP
.SCITECO_TOPIC argv arguments
Upon startup \*(ST's buffer ring contains only one unnamed empty buffer.
All command line arguments after the \*(ST options are passed as
.I arguments
to the munged macro by placing each argument on its own line in
the buffer.
The \fIscript\fP file name expected when \(lq--mung\(rq is given
is currently \fBnot\fP considered a macro argument.
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, 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
\fBEX\fP command or exits using \fB^C\fP, \*(ST will automatically
switch into its graphical \fIinteractive\fP mode.
\*(ST may be built with different graphical user interfaces,
including Curses and GTK+ based ones.
Eventually when the user terminates interactive mode by calling
\fBEX\fP, \*(ST will return to its batch mode before exiting.
\*(ST macros may still execute in batch mode after leaving
interactive mode and shutting down any GUI if the user has configured
\fBED\fP hooks (see \fBsciteco\fP(7)).
.
.LP
The differences between \fIbatch\fP and \fIinteractive\fP mode
are outlined below:
.RS
.IP \(bu
In batch mode, no terminal interaction takes place beyond writing
plain-text messages to the \fIstdout\fP and \fIstderr\fP file descriptors.
\fIstdin\fP is currently not read in batch mode.
It is therefore safe to redirect \*(ST's \fIstdout\fP or \fIstderr\fP
into files or pipes.
On most UIs, it is even safe to redirect \fIstdout\fP or \fIstderr\fP
if \*(ST enters interactive mode.
Depending on the GUI compiled into \*(ST, 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).
.IP \(bu
Messages logged to \fIstdout\fP or \fIstderr\fP \(em except
for messages written explicitly via some \*(ST command \(em
are prefixed with a string signifying the message's severity.
In interactive mode, messages are also shown in a GUI-dependant
manner.
.IP \(bu
.SCITECO_TOPIC batch
In batch mode, any \*(ST command failure will terminate the program.
A full stack trace of \*(ST macro invocations will be printed to
\fIstderr\fP and the process' return code will signify failure.
In interactive mode, \*(ST will \(lqrub out\(rq any character
resulting in a command failure.
.IP \(bu
.SCITECO_TOPIC interactive
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 \(lqundo tokens\(rq.
Batch mode does not have these restrictions.
.IP \(bu
A few commands that modify the command line are only available
in interactive mode.
.RE
.
.LP
If the
.B \-\-mung
option is absent, \*(ST will mung
.I $SCITECOCONFIG/.teco_ini
(if existing) which is called the profile.
On UNIX/Linux, the default profile is at
.I ~/.teco_ini
(see \fBENVIRONMENT\fP).
If the per-user profile is missing, \*(ST falls back to
.IR @scitecodatadir@/fallback.teco_ini .
Without
.BR \-\-mung ,
a \fIscript\fP file name will consequently not be expected as
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.
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.
.
.
.SH OPTIONS
.
.IP "\fB-h\fR, \fB--help\fR"
.SCITECO_TOPIC "-h" "--help"
Display a short help text on the console.
.IP "\fB-e\fR, \fB--eval\fR \fImacro"
.SCITECO_TOPIC "-e" "--eval"
Evaluate (execute)
.I macro
specified as a command-line option.
Similar to munging but always exits afterwards.
If the option is specified, the
.B \-\-mung
option has no effect.
.IP "\fB-m\fR, \fB--mung\fR"
.SCITECO_TOPIC "-m" "--mung"
Mung \fIscript\fP.
The script file name is expected as the first non-option
argument, so it does not necessarily have to follow the
\fB--mung\fP option.
Default is
.IR $SCITECOCONFIG/.teco_ini .
.IP "\fB--no-profile\fP"
.SCITECO_TOPIC "--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
.BR \-\-mung .
.IP "\fB-8\fR, \fB--8bit\fR"
.SCITECO_TOPIC "-8" "--8-bit"
Use raw single-byte ANSI encoding by default and disable automatic EOL conversion,
which optimizes \*(ST for 8-bit cleanliness.
It is equivalent to executing \(lq16,4ED\(rq, 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.
.IP "\fIUI options .\|.\|.\fP"
Some graphical user interfaces, notably GTK+, provide
additional command line options.
Execute \(lqsciteco --help\(rq for more details.
.
.
.SH EXIT STATUS
.SCITECO_TOPIC status
.
\*(ST will return a non-null exit code if an error occurred during
batch mode processing \(em usually 1 on UNIX.
Otherwise the top value on the numeric stack will determine
the process' exit code as if passed to libc's
.BR exit (3)
function.
On UNIX systems only numbers between 0 and 255 may be meaningfull.
.
.
.SH ENVIRONMENT
.SCITECO_TOPIC environment
.
Before \*(ST 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 \(lqHOME\(rq can be examined by macros by
reading the string-content of Q-Register \(lq$HOME\(rq.
.LP
Changes to these environment registers are not applied to
the process environment for technical reasons.
Nevertheless, \*(ST will always access the environment registers
instead of the process environment when it needs to evaluate
an environment variable internally.
Furthermore, when spawning subprocesses, \*(ST will export
all Q-Registers beginning with \(lq$\(rq that do not have
a \(lq=\(rq in their name into the subprocess environment.
Therefore, the subset of Q-Registers whose name begins with \(lq$\(rq
can be considered practically identical to the process environment
and \*(ST macros can access, modify and extend the environment using
these registers.
.LP
The following environment variables and registers are initialized with
default values by \*(ST if they are unset:
.TP
.SCITECO_TOPIC "$HOME" "HOME"
.B HOME
Home directory of the current user.
This may be used e.g. by the \fBFG\fP command and for
tilde-expansions.
If unset, it defaults to the current user's home directory
as set by
.BR passwd (5)
or as determined by other platform-dependent means.
Initialization of this variable ensures that the
\(lq$HOME\(rq Q-Register is available even on Windows
and the home directory can always be re-configured.
.TP
.SCITECO_TOPIC "$SHELL" "SHELL" "$COMSPEC" "COMSPEC"
.BR SHELL " or " COMSPEC
Path of the command interpreter used by \fBEG\fP and \fBEC\fP
commands if UNIX98 shell emulation is \fIdisabled\fP.
\fBSHELL\fP is used on UNIX-like systems, while \fBCOMSPEC\fP
is used on DOS-like systems (like Windows).
Both variables are usually already set in the process environment
but are initialized to \(lq/bin/sh\(rq or \(lqcmd.exe\(rq
should they nevertheless be unset.
Since environment variables are case-insensitive on
DOS-like systems and different spellings exist for \fBCOMSPEC\fP,
the name of the variable is always normalized to all-upper-case
by \*(ST.
.TP
.SCITECO_TOPIC "$SCITECOCONFIG" "SCITECOCONFIG"
.B SCITECOCONFIG
Path where \*(ST looks for configuration files.
For instance, this is the path of the default profile.
If unset, this variable defaults to the \fBHOME\fP
environment variable on Unix.
On Windows, this variable defaults to the location of the
\*(ST program executable, so that \*(ST is self-contained
on Windows.
On other platforms, this variable defaults to some other
user-specific configuration directory.
.TP
.SCITECO_TOPIC "$SCITECOPATH" "SCITECOPATH"
.B SCITECOPATH
Standard library macro path.
Macros can expect to find standard library macros in this
directory.
On Windows, this variable defaults to the \(lqlib\(rq
subdirectory of the directory containing
the \*(ST program executable, so that \*(ST is self-contained
on Windows.
On all other platforms (including UNIX/Linux) this variable
defaults to the standard library installation path at
.BR "@scitecolibdir@" .
.
.LP
The \fBHOME\fP, \fBSCITECOCONFIG\fP and \fBSCITECOPATH\fP environment
variables and registers are canonicalized to absolute paths.
Therefore it is possible to define them relative to the
working directory of \*(ST when it starts up while macros
can work with the corresponding registers to locate files
even when the working directory of \*(ST is changed later on.
.
.LP
Additionally \*(ST may be influenced by the
.UR https://developer.gnome.org/glib/stable/glib-running.html
environment variables accessed by glib
.UE .
.SCITECO_TOPIC "$TERM" "TERM"
On a Curses UI, there are other important environment variables
like \fBTERM\fP, \fBLINES\fP, \fBCOLUMNS\fP and \fBESCDELAY\fP
that may be accessed when \*(ST enters interactive mode.
For ncurses, see section \fBENVIRONMENT\fP in
.BR ncurses (3NCURSES)
for details.
\*(ST exports the environment registers into the process
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@/fallback.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
.
\*(ST currently reacts to the following signals or uses them
internally:
.TP
.SCITECO_TOPIC "SIGINT"
.B SIGINT
Interrupts the currently running macro.
The character resulting in the macro execution will fail
causing \*(ST 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 \fBSIGINT\fP when \fB^C\fP
is pressed in order to interrupt macros interactively.
Others will poll for keypresses.
Note that this signal can usually also be generated when pressing
\fB^C\fP on the process' associated console
(also if there is a graphical window).
.TP
.SCITECO_TOPIC "SIGTERM"
.B SIGTERM
Try to gracefully shut down \*(ST.
In batch mode this only interrupts the currently running macro
similar to \fBSIGINT\fP causing \*(ST to exit.
If technically possible, user interfaces will additionally
process \fBSIGTERM\fP in interactive mode as if the \fICLOSE\fP
function key has been pressed, which will result in unconditional
program termination or user-programmed behaviour.
.
.
.SH FILES
.
.TP
.SCITECO_TOPIC ".teco_ini" "profile"
.B $SCITECOCONFIG/.teco_ini
Default profile macro.
.TP
.SCITECO_TOPIC "fallback.teco_ini"
.B @scitecodatadir@/fallback.teco_ini
Fallback profile macro configuring commonly used run-time options,
syntax highlighting, session handling
and opening files specified on the command line.
.TP
.B $SCITECOPATH/*.tes
Standard library macros.
.TP
.SCITECO_TOPIC savepoint
.BI .teco- n - filename ~
Save point files created by \*(ST 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.
.TP
.SCITECO_TOPIC ".teco_session" session
.B $SCITECOCONFIG/.teco_session
Macro storing the default buffer session.
This is not written by \*(ST itself, but by the
standard library \fBsession.tes\fP macros.
When the \(lqsession.vcs\(rq macro is used, these files
will also be created in the roots of Git, Mercurial and
Subversion repositories or working copies.
.TP
.SCITECO_TOPIC ".teco_css"
.B $SCITECOCONFIG/.teco_css
When using the Gtk UI, this will be the location of a
CSS file that can be used to apply \*(ST color schemes
to the entire UI and to do other style customizations.
.TP
.SCITECO_TOPIC "fallback.css"
.B @scitecodatadir@/fallback.css
When using the Gtk UI, this is a fallback stylesheet
in case
.B $SCITECOCONFIG/.teco_css
does not exist.
It may also be used as a template for
.BR $SCITECOCONFIG/.teco_css .
.
.
.SH EXAMPLES
.
.LP
Without any argument, \*(ST will open the last editor session
(see \(lqsession.tes\(rq).
To edit one or more files, just specify them on the command line:
.RS
.SCITECO_TT
.EX
@PACKAGE@ main.c
.SCITECO_TT_END
.EE
.RE
.
.LP
You can specify which line to open either before or after the file name:
.RS
.SCITECO_TT
.EX
@PACKAGE@ +70 main.c error.c:23
.SCITECO_TT_END
.EE
.RE
.
.LP
If the program fails to start up after editing 
.B $SCITECOCONFIG/.teco_ini
or after upgrading \*(ST, you can prevent loading the profile macro:
.RS
.SCITECO_TT
.EX
@PACKAGE@ --no-profile
.SCITECO_TT_END
.EE
.RE
.
.LP
After startup of the interactive mode, use the \(lqEB~/.teco_ini\fB$\fP\(rq
command to load and fix up the profile macro.
In order to execute a stand-alone script or custom profile macro:
.RS
.SCITECO_TT
.EX
@PACKAGE@ -m script.tes
.SCITECO_TT_END
.EE
.RE
.
.
.SH SEE ALSO
.
.TP
Language reference:
.BR sciteco (7)
.TP
The \fBtroff\fP post-processor for \*(ST, including information on how to write \(lqwomanpages\(rq:
.BR grosciteco.tes (1)
.TP
A \fBtroff\fP pre-processor commonly used to generate man-pages:
.BR tedoc.tes (1)
.TP
Development home, bug tracker and wiki:
.UR @PACKAGE_URL@
\*(ST at Github
.UE
.TP
Related dialects:
.UR http://sourceforge.net/projects/videoteco/
Video TECO
.UE
(\c
.UR http://www.copters.com/teco.html
Manual
.UE ),
.br
.UR http://h71000.www7.hp.com/doc/73final/documentation/pdf/teco.pdf
DEC Standard TECO-11
.UE
.
.
.SH AUTHOR
.
This manpage and the \*(ST program was written by
.MT robin.haberkorn@googlemail.com
Robin Haberkorn
.ME .
\# EOF