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"
.RI [ "UI option .\|.\|." ]
.OP "--"
.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
.EX
.SCITECO_TT
#!@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.
.
.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).
It will consequently not expect a \fIscript\fP file name 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.
It 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 "\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.
.
.
.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.
.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.
.
.
.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.
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).
This is useful for GUIs that do not yet support interruptions
directly.
.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
.B @pkgdatadir@/sample.teco_ini
Sample 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 @pkgdatadir@/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 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
Homepage:
.UR @PACKAGE_URL@
\*(ST at Sourceforge
.UE
.TP
Development home, bug tracker and wiki:
.UR @PACKAGE_URL_DEV@
\*(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