aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am75
-rw-r--r--doc/cheat-sheet.mm4
-rw-r--r--doc/grosciteco.tes.1.in12
-rwxr-xr-xdoc/grosciteco.tes.in (renamed from doc/grosciteco.tes)75
-rwxr-xr-xdoc/htbl.tes9
-rw-r--r--doc/sciteco.1.in125
-rw-r--r--doc/sciteco.7.template125
-rw-r--r--doc/sciteco.tmac23
-rw-r--r--doc/tedoc.tes.1.in2
-rwxr-xr-xdoc/tedoc.tes.in (renamed from doc/tedoc.tes)29
-rw-r--r--doc/tutorial.ms.in20
11 files changed, 361 insertions, 138 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index f69d95f..f5b3d03 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -7,16 +7,20 @@ include $(top_srcdir)/bootstrap.am
# code.
# It generates Troff manpage markup and acts as a Troff
# preprocessor to manpage templates.
-dist_bin_SCRIPTS = tedoc.tes
+bin_SCRIPTS = tedoc.tes
+CLEANFILES = tedoc.tes
+dist_noinst_SCRIPTS = tedoc.tes.in
%.in : %.template tedoc.tes @top_srcdir@/src/*.c
- $(SCITECO_FULL) -m -- @srcdir@/tedoc.tes \
+ $(SCITECO_FULL) -m -- tedoc.tes \
-C $@ $< @top_srcdir@/src/*.c
# grosciteco is a troff postprocessor similar to grotty
# which can be used to produce SciTECO-friendly output
# (woman pages).
-dist_bin_SCRIPTS += grosciteco.tes
+bin_SCRIPTS += grosciteco.tes
+CLEANFILES += grosciteco.tes
+dist_noinst_SCRIPTS += grosciteco.tes.in
# grosciteco, like many other postprocessors, works
# best with its own macro package.
# Unfortunately, there is no way to query the built-in
@@ -27,56 +31,59 @@ dist_bin_SCRIPTS += grosciteco.tes
# the directory via `groff -M`.
dist_scitecodata_DATA = sciteco.tmac
-# Fix up the hash-bang line of installed SciTECO scripts upon
-# installation to refer to the installed sciteco binary.
-# This takes --program-prefix into account.
-#
-# FIXME: This will patch the hash-bang line repeatedly.
-install-exec-hook:
- $(SCITECO_FULL) -e "@EB'$(DESTDIR)$(bindir)/*.tes' 1U* \
- EJ-1<%*^[ 0,^Q::@FR'#!^EM^Xsciteco'#!$(SCITECO_INSTALLED)'> \
- :EX"
+# Fix up the hash-bang line of installed SciTECO scripts.
+# This takes --prefix and --program-prefix into account.
+# On the other hand, since this is run at build time,
+# it breaks bindir-overwriting at `make install` time,
+# which could only be made to work with an install-exec-hook.
+# Patching installed scripts however broke the FreeBSD port
+# builds with Poudriere where BINMODE=555 is set.
+# It was therefore decided to sacrifice the rarely used
+# `make install bindir=...` and appease the FreeBSD port
+# committers instead.
+%.tes : %.tes.in
+ $(SCITECO_FULL) -qioe '0,^Q::@FR/#!^EM^Xsciteco/#!^EQ[^A1]/^[' \
+ $(SCITECO_INSTALLED) <$< >$@
womendir = $(scitecolibdir)/women
women_DATA = grosciteco.tes.1.woman grosciteco.tes.1.woman.tec
-CLEANFILES = grosciteco.tes.1 grosciteco.tes.1.intermediate
+CLEANFILES += grosciteco.tes.1
EXTRA_DIST = grosciteco.tes.1.in
women_DATA += tedoc.tes.1.woman tedoc.tes.1.woman.tec
-CLEANFILES += tedoc.tes.1 tedoc.tes.1.intermediate
+CLEANFILES += tedoc.tes.1
EXTRA_DIST += tedoc.tes.1.in
women_DATA += sciteco.1.woman sciteco.1.woman.tec
-CLEANFILES += sciteco.1 sciteco.1.intermediate
+CLEANFILES += sciteco.1
EXTRA_DIST += sciteco.1.in
women_DATA += sciteco.7.woman sciteco.7.woman.tec
-CLEANFILES += sciteco.7 sciteco.7.intermediate sciteco.7.in sciteco.7.htbl
+CLEANFILES += sciteco.7 sciteco.7.in
EXTRA_DIST += sciteco.7.template
women_DATA += tutorial.woman tutorial.woman.tec
-CLEANFILES += tutorial.ms tutorial.intermediate
+CLEANFILES += tutorial.ms
EXTRA_DIST += tutorial.ms.in
CLEANFILES += $(women_DATA)
-# NOTE: *.intermediate files are only generated since SciTECO scripts
-# cannot currently read stdin, so the grosciteco postprocessor
-# has to be run on a separate file.
-%.woman %.woman.tec : %.intermediate grosciteco.tes
- $(SCITECO_FULL) -m -- @srcdir@/grosciteco.tes \
- $@ $<
+# NOTE: grosciteco.tes generates two artifacts, but two targets in one rule would be independent.
+# Grouped targets (&:) on the other hand are unreliable/buggy.
+%.woman.tec : %.woman;
-%.intermediate : % sciteco.tmac
- @GROFF@ -wall -Z -Kutf-8 -Tutf8 -t -man -M@srcdir@ -msciteco $< >$@
+%.woman : % sciteco.tmac grosciteco.tes
+ @GROFF@ @GROFF_FLAGS@ -wall -Z -Tutf8 -t -man -M@srcdir@ -msciteco $< | \
+ $(SCITECO_FULL) -im -- grosciteco.tes $@
-tutorial.intermediate : tutorial.ms sciteco.tmac
- @GROFF@ -wall -Z -Kutf-8 -Tutf8 -t -ms -M@srcdir@ -msciteco $< >$@
+tutorial.woman : tutorial.ms sciteco.tmac grosciteco.tes
+ @GROFF@ @GROFF_FLAGS@ -wall -Z -Tutf8 -t -ms -M@srcdir@ -msciteco $< | \
+ $(SCITECO_FULL) -im -- grosciteco.tes $@
man_MANS = grosciteco.tes.1 tedoc.tes.1 sciteco.1 sciteco.7
-dist_noinst_SCRIPTS = htbl.tes
+dist_noinst_SCRIPTS += htbl.tes
if BUILD_HTMLDOCS
html_DATA = grosciteco.tes.1.html tedoc.tes.1.html \
@@ -84,16 +91,12 @@ html_DATA = grosciteco.tes.1.html tedoc.tes.1.html \
CLEANFILES += $(html_DATA)
endif
-# NOTE: The *.htbl files are only generated since SciTECO
-# scripts cannot be integrated into pipelines easily yet.
-%.htbl : % htbl.tes
- $(SCITECO_FULL) -m -- @srcdir@/htbl.tes $< $@
-
-%.html : %.htbl
- @GROFF@ -wall -Thtml -man $< >$@
+%.html : % htbl.tes
+ $(SCITECO_FULL) -qiom -- @srcdir@/htbl.tes <$< | \
+ @GROFF@ @GROFF_FLAGS@ -wall -Thtml -man >$@
%.html : %.ms
- @GROFF@ -wall -Thtml -ms $< >$@
+ @GROFF@ @GROFF_FLAGS@ -wall -Thtml -ms $< >$@
# FIXME: We may want to build the cheat sheet automatically.
# This would require a full Groff installation, though.
diff --git a/doc/cheat-sheet.mm b/doc/cheat-sheet.mm
index 60104ff..ba7247c 100644
--- a/doc/cheat-sheet.mm
+++ b/doc/cheat-sheet.mm
@@ -14,7 +14,7 @@
\#.SP
Overview of \fBSciTECO\fP as an editor.
A full language description can be found in
-.pdfhref W -D https://rhaberkorn.github.io/sciteco/sciteco.7.html -A . \fBsciteco\fP(7)
+.pdfhref W -D https://sciteco.fmsbw.de/sciteco.7.html -A . \fBsciteco\fP(7)
.br
.
.\" subscripts
@@ -278,7 +278,7 @@ Insert \*$ (ASCII 27).
. 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://sciteco.fmsbw.de/knowledge/Useful%20Macros/#indent-code-block -A . \fIn\^\fCM#it\fP
.ETB
.
.TBLX "Text Deletion" width='30% 70%'
diff --git a/doc/grosciteco.tes.1.in b/doc/grosciteco.tes.1.in
index 9056a60..4d3fd0b 100644
--- a/doc/grosciteco.tes.1.in
+++ b/doc/grosciteco.tes.1.in
@@ -18,7 +18,7 @@ GNU roff post-processor for \*(ST
.OP "-t" tec_output
.OP "--"
.I text_output
-.I input
+.RI < input
.YS
.
.
@@ -79,8 +79,8 @@ This is also the default when omitted.
.IP "\fItext_output\fP
The plain-text output file, e.g. \(lqgreat-macro.woman\(rq.
.IP "\fIinput\fP"
-The \fIinput\fP file is in \fBtroff\fP's device-independant
-output format.
+\fBtroff\fP's device-independant output format
+is read from \fIstdin\fP.
.
.
.SH SPECIAL TROFF MACROS
@@ -168,8 +168,8 @@ a \*(ST macro package with a man page called
.SCITECO_TT
.EX
groff -Z -Kutf-8 -Tutf8 -man -M@scitecodatadir@ -msciteco \\
- great-macro.tes.7sciteco >great-macro.tes.7sciteco.intermediate
-grosciteco.tes great-macro.tes.7sciteco.woman great-macro.tes.7sciteco.intermediate
+ great-macro.tes.7sciteco | \\
+grosciteco.tes great-macro.tes.7sciteco.woman
.SCITECO_TT_END
.EE
.RE
@@ -211,7 +211,7 @@ The \fBGNU roff\fP \(lqman\(rq macros for writing man pages:
.SH AUTHOR
.
This manpage and the \*(ST program was written by
-.MT robin.haberkorn@googlemail.com
+.MT rhaberkorn@fmsbw.de
Robin Haberkorn
.ME .
\# EOF \ No newline at end of file
diff --git a/doc/grosciteco.tes b/doc/grosciteco.tes.in
index ac268b6..c4f16e1 100755
--- a/doc/grosciteco.tes
+++ b/doc/grosciteco.tes.in
@@ -1,16 +1,18 @@
-#!/usr/local/bin/sciteco -m
-!* grosciteco.tes [-t <output-tec>] [--] <output-woman> <input> *!
+#!/usr/local/bin/sciteco -mi
+!* grosciteco.tes [-t <output-tec>] [--] <output> <input *!
0,2EJ !* FIXME: Memory limiting is too slow *!
-:EMQ[$SCITECOPATH]/getopt.tes
+:EIQ[$SCITECOPATH]/getopt.tes
!* Process command-line options *!
-[optstring]t: M[getopt]"F (0/0) '
-LR 0X[output-woman] 2LR 0X[input] HK
+[optstring]t:
+M[getopt]U[output-woman] Q[output-woman]"< Invalid command-line^J 1 '
+EU[output-woman]Q[\[output-woman]]
:Q[getopt.t]"< EU[getopt.t]Q[output-woman].tec '
-EBN[input]
+EBN[output-woman] HK 1EB
+
0EE !* Groff intermediate code is always ASCII *!
!* skip whitespace characters *!
@@ -54,7 +56,7 @@ EBN[input]
!* FIXME: Works only for straight lines *!
@[line]{ U.[to.v] U.[to.h]
Q.[to.h]-Q[pos.h]"= Q.[to.v]-Q[pos.v]"=  ' '
- [* EB
+ [* EBN[output-woman]
Q.[to.h]-Q[pos.h]"=
!* vertical line *!
Q.[to.v]-Q[pos.v]"< Q[pos.v]U.v Q.[to.v]U[pos.v] | Q.[to.v]U.v '
@@ -113,6 +115,7 @@ EBN[input]
[glyphs.Fc]»
[glyphs.rs]\
[glyphs.ti]~
+[glyphs.sl]/
[glyphs.+]+
[glyphs.->]→
[glyphs.tm]™
@@ -146,29 +149,35 @@ EBN[input]
* a table). Only the line+column should no longer change.
* Either store line+column or use markers.
*!
- [* EB 0:M[move] U.d ]*
+ [* EBN[output-woman] 0:M[move] U.d ]*
:EU[topics]\.d:
C :X[topics]
L F<
!cmd.xXsciteco_tt!
- [* EB 0:M[move] U[ttstart] ]*
+ [* EBN[output-woman] 0:M[move] U[ttstart] ]*
L F<
!cmd.xXsciteco_tt_end!
- [* EB 0:M[move]
+ [* EBN[output-woman] 0:M[move]
-Q[ttstart]<
Q[ttstart]ESSTARTSTYLING Q[ttstart]ESGETSTYLEAT+16,1ESSETSTYLING
%[ttstart]>
]*
L F<
!cmd.xXsciteco_startstyling!
- [* EB 0:M[move] U[stylestart] ]*
+ [* EBN[output-woman] 0:M[move] U[stylestart] ]*
L F<
!cmd.xXsciteco_setstyling!
C :M#giU.s
- [* EB 0:M[move]
+ [* EBN[output-woman] 0:M[move]
Q[stylestart]ESSTARTSTYLING Q.s,(-Q[stylestart])ESSETSTYLING
]*
L F<
+ !cmd.xXsciteco_foldlevel!
+ C :M#giU.[foldlevel]
+ [* EBN[output-woman] 0:M[move]
+ Q.[foldlevel],(ESLINEFROMPOSITION)ESSETLINESTATE
+ ]*
+ L F<
!cmd.xXtty!
!cmd.xXdevtag!
L F<
@@ -176,11 +185,11 @@ EBN[input]
!cmd.xf!
:M#sa :M#giU.n Q.n+16U.#nt .(:M#sa).X[font] :M#sc
:Q[fonts.\.n]"F F< ' -U[fonts.\.n]
- @:EU[styles]{\.#ntESSTYLESETFONTMonospace^J}
+ @:EU[styles]{\.#ntESSTYLESETFONTQ[lexer.font]^J}
Ocmd.xfQ[font]
!cmd.xfR!
Q.nU[default-style]
- @:EU[styles]{16ESSTYLESETFONTMonospace^J}
+ @:EU[styles]{16ESSTYLESETFONTQ[lexer.font]^J}
F<
!cmd.xfB!
@:EU[styles]{1,\.nESSTYLESETBOLD 1,\.#ntESSTYLESETBOLD^J}
@@ -210,7 +219,7 @@ EBN[input]
:M#sw :M#gi :M#sc F<
!cmd.V!
- :M#sw :M#gi/Q[res.v]-1+Q[origin.v]U[pos.v] :M#sc F<
+ :M#sw :M#gi/Q[res.v]-1+Q[origin.v]U[pos.v] Q[pos.v]"<0U[pos.v]' :M#sc F<
!cmd.v!
:M#sw :M#gi/Q[res.v]%[pos.v] :M#sc F<
@@ -267,7 +276,7 @@ EBN[input]
!cmd.t!
:M#sw .(:M#sa).X.w
- [* EB :Q.w:M[move]
+ [* EBN[output-woman] :Q.w:M[move]
G.w :Q.w:M[style] ]*
:Q.w%[pos.h] :M#sc F<
@@ -278,17 +287,17 @@ EBN[input]
|
.(:M#sa).X.w 0Q[glyphs.Q.w]U.w
'
- [* EB 1:M[move]
+ [* EBN[output-woman] 1:M[move]
Q.wI 1:M[style] ]* :M#sc F<
!cmd.c!
:M#sw 0AU.w C
- [* EB 1:M[move]
+ [* EBN[output-woman] 1:M[move]
G[glyphs.U.w] 1:M[style] ]* :M#sc F<
!cmd.N!
:M#sw :M#giU.w
- [* EB 1:M[move]
+ [* EBN[output-woman] 1:M[move]
Q.wI 1:M[style] ]* :M#sc F<
!cmd.n!
@@ -329,7 +338,7 @@ Q*U*
* TODO: The size can still be improved by using SCI_SETSTYLINGEX
* if appropriate.
*!
-EB 0EE !* operate in single-byte mode *!
+EBN[output-woman] 0EE !* operate in single-byte mode *!
J 0U#cs 0U#cd
<
.ESGETSTYLEATUs Qs"< Qs= '
@@ -342,9 +351,33 @@ J 0U#cs 0U#cd
:C;>
!*
+ * The fold level is stored in the line state since it is set
+ * while the document is not fully built yet.
+ *!
+J 0U#li 0U[cur.fl] 0U[last.line]
+ESGETLINECOUNT<
+ Q#liESGETLINESTATEU#fl
+ Q#fl"N
+ Q[cur.fl]"N
+ Q#li-Q[last.line]Ux
+ 1024%[cur.fl]
+ @:EU[styles]{\[last.line]U.l \x<\[cur.fl],Q.lESSETFOLDLEVEL %.l>^J}
+ '
+ Q#li+1U[last.line] Q#flU[cur.fl]
+ (1024+Q#fl-1)#(2^*13)U#fl
+ @:EU[styles]{\#fl,\#liESSETFOLDLEVEL^J}
+ '
+%#li>
+Q[cur.fl]"N
+ Q#li-Q[last.line]Ux
+ 1024%[cur.fl]
+ @:EU[styles]{\[last.line]U.l \x<\[cur.fl],Q.lESSETFOLDLEVEL %.l>^J}
+'
+
+!*
* Save the clear-text part of the document into <output-woman>
*!
-2EL EWQ[output-woman]
+2EL EW
EQ[styles]
diff --git a/doc/htbl.tes b/doc/htbl.tes
index 9cd5100..19f81a2 100755
--- a/doc/htbl.tes
+++ b/doc/htbl.tes
@@ -1,11 +1,9 @@
-#!/usr/local/bin/sciteco -m
-!* htbl.tes <input> <output> *!
+#!/usr/local/bin/sciteco -qiom
+!* cat input | htbl.tes >output *!
!* Troff tbl "drop-in" replacement *!
0,2EJ !* FIXME: Memory limiting is too slow *!
-LR 0X#in 2LR 0X#ou EBN#in EB -EF
-
<
!*
* <table> will implicitly close <p>'s so we must recalculate the margin.
@@ -112,5 +110,4 @@ q.[drows]<
I.HTML </table>^J
>
-2EL EWQ#ou
-EX \ No newline at end of file
+2EL -EX
diff --git a/doc/sciteco.1.in b/doc/sciteco.1.in
index f57415c..e47ca93 100644
--- a/doc/sciteco.1.in
+++ b/doc/sciteco.1.in
@@ -16,6 +16,10 @@ Scintilla-based \fBT\fPext \fBE\fPditor and \fBCO\fPrrector
.SCITECO_TOPIC "sciteco"
.SY @PACKAGE@
.OP "-h|--help"
+.OP "-v|--version"
+.OP "-q|--quiet"
+.OP "-i|--stdin"
+.OP "-o|--stdout"
.OP "-e|--eval" macro
.OP "-m|--mung"
.OP "--no-profile"
@@ -59,12 +63,13 @@ invoked as scripts by using a Hash-Bang line like
.RS
.SCITECO_TT
.EX
-#!@bindir@/sciteco -m
+#!@bindir@/@PACKAGE@ -m
.SCITECO_TT_END
.EE
.RE
.
.LP
+.SCITECO_TOPIC argv arguments
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.
@@ -72,27 +77,29 @@ 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.
+All remaining arguments after the built-in processing of options
+are passed to the executed macro using an array of global Q-registers \fB^A\fIx\fR.
+The \fIscript\fP file name expected when \(lq\-\-mung\(rq is given
+is currently \fBnot\fP included in this array.
+Q-register \fB^A0\fP is the name of the current process as passed to C
+programs in \(lqargv[0]\(rq.
+.
+.LP
+Upon startup \*(ST's buffer ring always contains only one unnamed buffer.
+If \(lq\-\-stdin\(rq is given, \*(ST first reads from \fIstdin\fP until end-of-file
+into the unnamed buffer.
+This is includes automatic EOL translation just like when using the \fBEB\fP command
+and can therefore be disabled by specifying \(lq\-\-8bit\(rq.
+If reading from \fIstdin\fP results in any text additions, the buffer is left \fIdirty\fP.
+The current position (called dot) is always left at the beginning of the buffer.
.
.LP
If the munged macro does not request program termination using the
-\fBEX\fP command or exits using \fB^C\fP, \*(ST will automatically
+\fBEX\fP command or exits using \fB^C^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.
@@ -119,7 +126,7 @@ 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
+for \(lquser\(rq-level 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.
@@ -141,6 +148,10 @@ Batch mode does not have these restrictions.
.IP \(bu
A few commands that modify the command line are only available
in interactive mode.
+.IP \(bu
+A few commands like \fB^C\fP are disallowed in interactive mode
+when run from the command-line macro or behave slightly
+differently compared to batch mode (e.g. \fB$$\fP or \fB==\fP).
.RE
.
.LP
@@ -179,6 +190,29 @@ option.
.IP "\fB-h\fR, \fB--help\fR"
.SCITECO_TOPIC "-h" "--help"
Display a short help text on the console.
+.IP "\fB-v\fR, \fB--version\fR"
+.SCITECO_TOPIC "-v" "--version"
+Display the \*(ST version in an easy to parse way.
+See also the \fBEO\fP command.
+.IP "\fB-q\fR, \fB--quiet\fR"
+.SCITECO_TOPIC "-q" "--quiet"
+Do not print any messages to \fIstdout\fP except for \(lquser\(rq-level
+messages, i.e. messages printed via \fBT\fP, \fB^T\fP and related
+commands.
+This is useful when piping the output of \*(ST into other programs.
+.IP "\fB-i\fR, \fB--stdin\fR"
+.SCITECO_TOPIC "-i" "--stdin"
+Reads from \fIstdin\fP into the unnamed buffer before executing any macro.
+Allows to easily integrate \*(ST into an UNIX pipeline, at least
+if you don't need to process infinite streams.
+This normalizes end-of-line (EOL) characters just like when opening
+any other file.
+.IP "\fB-o\fR, \fB--stdout\fR"
+.SCITECO_TOPIC "-o" "--stdout"
+\# FIXME: Perhaps this should imply --quiet?
+Prints the current document's contents to \fIstdout\fP immediately before
+terminating the program, restoring the original EOL characters.
+This is also useful when piping the output of \*(ST into other programs.
.IP "\fB-e\fR, \fB--eval\fR \fImacro"
.SCITECO_TOPIC "-e" "--eval"
Evaluate (execute)
@@ -223,7 +257,12 @@ Execute \(lqsciteco --help\(rq for more details.
.SCITECO_TOPIC status
.
\*(ST will return a non-null exit code if an error occurred during
-batch mode processing.
+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
@@ -411,12 +450,22 @@ and opening files specified on the command line.
.B $SCITECOPATH/*.tes
Standard library macros.
.TP
-.SCITECO_TOPIC savepoint
+.BI # filename #
+Recovery file:
+After a configurable recovery interval \*(ST dumps up all modified buffers
+(unsaved changes), that have not been dumped previously.
+These files should be ignored by version control systems and may
+be left around after crashes and unexpected restarts.
+See \fB6EJ\fP for more details.
+.TP
+.SCITECO_TOPIC savepoint backup
.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
+They are internally used when rubbing out file saves
+and are conceptually similar to backup files in other editors.
+However they are temporary and should be ignored by version
control systems, etc.
.TP
.SCITECO_TOPIC ".teco_session" session
@@ -492,6 +541,42 @@ In order to execute a stand-alone script or custom profile macro:
.EE
.RE
.
+.LP
+The easiest way to integrate \*(ST into an UNIX pipeline is
+by using the \(lq--quiet --stdin --stdout\(rq or \(lq-qio\(rq
+parameters.
+For instance in order to prefix all lines with a line number:
+.RS
+.SCITECO_TT
+.EX
+dmesg | @PACKAGE@ -qioe '<%a\\@I/ / :L;>'
+.SCITECO_TT_END
+.EE
+.RE
+.
+.LP
+This also works in interactive mode, so \(lq@PACKAGE@ -i\(rq
+allows you to interactively edit text read from \fIstdin\fP.
+Suppose you would want to print only those lines from \fIstdin\fP
+matching \(lqiwm0:\(rq:
+.RS
+.SCITECO_TT
+.EX
+dmesg | @PACKAGE@ -qie '<@S/iwm0:/; :L; -T>'
+.SCITECO_TT_END
+.EE
+.RE
+.
+.LP
+In order to query the installation path of the standard library,
+which is useful for authors of third-party macro packages:
+.RS
+.SCITECO_TT
+.EX
+@PACKAGE@ -qe ':G[$SCITECOPATH]'
+.SCITECO_TT_END
+.EE
+.RE
.
.SH SEE ALSO
.
@@ -527,7 +612,7 @@ DEC Standard TECO-11
.SH AUTHOR
.
This manpage and the \*(ST program was written by
-.MT robin.haberkorn@googlemail.com
+.MT rhaberkorn@fmsbw.de
Robin Haberkorn
.ME .
\# EOF \ No newline at end of file
diff --git a/doc/sciteco.7.template b/doc/sciteco.7.template
index 4736be2..cb718e0 100644
--- a/doc/sciteco.7.template
+++ b/doc/sciteco.7.template
@@ -680,6 +680,16 @@ work as an immediate editing command in the GUI or as a signal
dispatched from an associated console or from another process.
T}
T{
+.SCITECO_TOPIC ^L redraw
+Redraw
+T};12;^L;T{
+Everywhere
+T};T{
+Enforces a complete redraw of the entire window.
+This is useful when the display becomes corrupted,
+especially when using the Curses UI.
+T}
+T{
.SCITECO_TOPIC interrupt
Interrupt
T};3;^C;T{
@@ -864,8 +874,9 @@ areas\fP.
.IP \(bu
The \fIcommand line area\fP, showing the currently effective
and rubbed-out command line as it is edited.
-This is currently a single line of text that is scrolled
-automatically.
+This is a single line by default, but can be configured with \(lq5EJ\(rq.
+Since it is also a Scintilla view, it can be further customized by
+running \(lq0,2048ED\(rq and invoking Scintilla messages using \fBES\fP.
.
.SS Colors and Theming
.SCITECO_TOPIC colors theming
@@ -982,6 +993,7 @@ The integer storage size may be changed at \*(ST build time
however.
In this specific build, integers are @TECO_INTEGER@-bit.
.LP
+.SCITECO_TOPIC bool boolean
Some commands expect or return booleans, most often signifying
success or failure.
Booleans are also integers but unlike in ordinary (sane) languages
@@ -1251,12 +1263,12 @@ stack are discarded.
This way, \fPED\fP hooks should not interfere with
the stack-semantics of commands triggering them.
.LP
-Possible arguments to the \(lqED\(rq macro begin with 1 and
+Possible arguments to the \(lqED\(rq macro begin with 0 and
are defined consecutively so the macro can branch to the
operation using a computed goto.
The different values are defined as follows:
.TP
-.B 1
+.B 0
A file has been \fBadded\fP to the buffer ring.
It may or may not already exist in the file system.
This file is \*(ST's current document when this hook
@@ -1264,7 +1276,7 @@ executes.
Scintilla lexing may be configured in this hook \(em it
usually only has to be done once.
.TP
-.B 2
+.B 1
A buffer has been \fBedited\fP (made the current file).
This hook is not executed when a file is freshly added
to the buffer ring, since this can be simulated easily
@@ -1272,13 +1284,13 @@ by branching within the \(lqED\(rq macro.
In this hook you may want to define language-specific
auxiliary macros, for instance.
.TP
-.B 3
+.B 2
A buffer is about to be \fBclosed\fP (removed from the
buffer ring).
The buffer that is about to be closed, is still the
current document when this hook runs.
.TP
-.B 4
+.B 3
\*(ST is about to \fBquit\fP, i.e. exit normally.
This is \*(ST's equivalent of
.BR atexit (3)
@@ -1383,13 +1395,16 @@ return 0 instead.
.LP
.SCITECO_TOPIC ::
Two colons (\fB::\fP) can sometimes further modify a command's behavior \(em
-currently it is used by the \fB::S\fP search comparison command
-and a few related search-and-replace operations.
+currently it is used by the timestamp command \fB::^H\fP,
+the \fB::S\fP search comparison command and a few related search-and-replace operations.
.LP
.SCITECO_TOPIC @ at
When put in front of a command with string arguments,
the at (\fB@\fP) modifier always allows the string termination character
to be changed for that particular command.
+\# This particular bit of syntax is TECO-64 inspired.
+Whitespace characters (as by \*(ST's understanding of no-op characters)
+are ignored immediately after the command name if it was \fB@\fP-modified.
The alternative termination character must be specified just before
the first string argument.
For instance:
@@ -1398,13 +1413,13 @@ For instance:
@FS/foo/bar/
.SCITECO_TT_END
.EE
-Any character may be used as an alternative termination character.
+Any non-whitespace character may be used as an alternative termination character
+and is matched case-insensitively.
There is one special case, though.
If specified as the opening curly brace (\fB{\fP), a string argument
will continue until the closing curly brace (\fB}\fP).
Curly braces must be balanced and after the closing curly brace
-the termination character is reset to Escape and another one may
-be chosen.
+a new termination character may be chosen after optional whitespace.
This feature is especially useful for embedding TECO code in
string arguments, as in:
.SCITECO_TT
@@ -1414,6 +1429,16 @@ string arguments, as in:
}
.SCITECO_TT_END
.EE
+Since whitespace is ignored in front of the alternative escape character,
+this could have also been written as:
+.SCITECO_TT
+.EX
+@^Um
+{
+ @FS {foo} /bar/
+}
+.SCITECO_TT_END
+.EE
The termination character can be \fIquoted\fP if you want to handle
it like any regular character.
For instance, you could write \(lqS^Q\fB$$\fP\(rq to search for the
@@ -1548,7 +1573,6 @@ but querying \(lq$\(rq will still return an absolute path.
The \(lq$\(rq register may also be edited but changing its
string contents this way has no effect on the current
working directory.
-Appending to the \(lq$\(rq register is unsupported.
The register is initialized automatically on startup.
.TP
.BR $ " (Escape)"
@@ -1590,6 +1614,11 @@ 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
+The default clipboard \(lq~\(rq refers to the clipboard selection
+if there are multiple clipboards.
+You can set bit 10 of the \fBED\fP flags to change it to the
+primary clipboard.
+.br
\*(ST supports two ways of driving the clipboard on ncurses.
.SCITECO_TOPIC OSC-52 xterm
First of all, there is built-in support for OSC-52 escape sequences,
@@ -1637,8 +1666,28 @@ EOL normalization will take place (if enabled), so that pasting
clipboards does not introduce unexpected EOL sequences.
The Q-Register view's EOL mode will \fBnot\fP be guessed from
the original clipboard contents, though.
-The numeric parts of the clipboard registers are currently
-not used by \*(ST.
+The numeric parts of the clipboard registers are
+currently not used by \*(ST.
+.TP
+.SCITECO_TOPIC ^Ax
+.BI ^A x
+An argument passed on the operating system's command line.
+\fIx\fP can be an integer beginning with 0.
+.B ^A0
+is the name of the program, as passed via \(lqargv[0]\(rq to
+C programs, and is guaranteed to always exist.
+All remaining registers for \fIx\fP larger than or equal to 1
+represent the command-line parameters after all the built-in
+options as reported by \(lq@PACKAGE@ --help\(rq.
+In other words all the options processed by the \*(ST main program
+including the file names after \(lq--mung\(rq are automatically
+excluded from the
+.BI ^A x
+array.
+The numeric parts of the argument registers are
+currently not used by \*(ST.
+For more details, see
+.BR sciteco (1).
.TP
.BI ^K key
Key macro registers as documented in section
@@ -1786,6 +1835,12 @@ character and their case is insignificant.
In the following list of supported expressions, the caret-notation
thus refers to the corresponding control code:
.TP
+.SCITECO_TOPIC ^P
+.B ^P
+Disable interpretation of all further string building characters,
+so all following characters will be taken verbatim.
+There is no way to escape the string terminator after \(lq^P\(rq.
+.TP
.SCITECO_TOPIC ^Qc ^Rc quote
.BI ^Q c
.TQ
@@ -1839,6 +1894,19 @@ Operations on registers (\fBEU\fP) similarily consult the
register's encoding.
Everything else expects Unicode codepoints.
.TP
+.SCITECO_TOPIC ^E< ^E<>
+.BI ^E< code >
+Expands to the character, specified by \fIcode\fP.
+\# This is Video-TECO-like. TECO-11 only accepts octal codes AFAIK.
+It is read in decimal by default, but can be given in hexadecimal if lead by \(lq0x\(rq
+or octal if given with a leading \(lq0\(rq.
+The current radix as specified by \fB^R\fP does not influence parsing.
+These semantics are compatible with libc's
+.BR stroull (3).
+The sequence \(lq^E<0x41>\(rq for instance expands to the character \(lqA\(rq.
+The interpretation of this code as bytes or Unicode codepoints depends on the context
+just like for \fB^EU\fP.
+.TP
.SCITECO_TOPIC ^EQ ^EQq
.BI ^EQ q
Expands to the string contents of the Q-Register specified by
@@ -2118,13 +2186,15 @@ in classic TECOs.
.
.SS Gotos and Labels
.
-The most basic flow control command in \*(ST is the Go-to command.
+An important 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 can perform simple unconditional and computed gotos.
+\*(ST can perform simple unconditional and computed gotos
+which are just as powerful as switch-case statements in other
+languages.
.LP
-.SCITECO_TOPIC label
+.SCITECO_TOPIC "!" label
Labels are symbolic and are defined with the following syntax:
.br
.BI ! label !
@@ -2153,7 +2223,7 @@ In addition to labels and unlike most classic TECO dialects,
\*(ST also supports true comments.
True comments are parsed faster than labels and do not
take up memory in goto tables.
-.SCITECO_TOPIC "block comment"
+.SCITECO_TOPIC "!*" "block comment"
One form of comments is the block comment:
.br
.BI !* comment *!
@@ -2165,7 +2235,8 @@ They are analoguous to C's
.BI /* ... */
comments.
.LP
-.SCITECO_TOPIC "EOL comment"
+\# This form of comment was originally in TECO-64.
+.SCITECO_TOPIC "!!" "EOL comment"
The second form of real comments are end-of-line comments,
which are analogous to C++'s \fB//\fP comments:
.br
@@ -2444,12 +2515,14 @@ The same conventions are used elsewhere in this manual.
.
.SH COMPATIBILITY
.
-\*(ST is not compatible with any particular TECO dialect,
-but is quite similar to
-.BR "Video TECO" .
-Most Video TECO and many Standard TECO programs should
+\*(ST strives to be compatible with \(lqstandard\(rq DEC TECO-11 whereever this
+does not hinder \*(ST's nature as an interactive modern editor.
+In questions concerning multiple buffers and interactivity
+\*(ST draws inspiration from Video TECO.
+Most Video TECO and many \(lqstandard\(rq TECO macros should
be portable with little or no changes.
-This manual mentions differences on several occasions.
+\*(ST however conciously deviates from both dialects to preserve
+features considered intrinsic and defining to the project.
.
.
.SH SEE ALSO
@@ -2488,7 +2561,7 @@ Overview of CSS in GTK
.SH AUTHOR
.
This manpage and the \*(ST program was written by
-.MT robin.haberkorn@googlemail.com
+.MT rhaberkorn@fmsbw.de
Robin Haberkorn
.ME .
\# EOF \ No newline at end of file
diff --git a/doc/sciteco.tmac b/doc/sciteco.tmac
index 026e489..8e53407 100644
--- a/doc/sciteco.tmac
+++ b/doc/sciteco.tmac
@@ -66,6 +66,29 @@
. device sciteco_setstyling:\\$1
..
.
+.\" Set the fold level of the current line __and__ all following lines.
+.\" This could be called at the beginning of chapters and sections.
+.de SCITECO_FOLDLEVEL
+. device sciteco_foldlevel:\\$1
+..
+.
+.\" man-page specific extensions.
+.\" FIXME: Is there a reliable way to detect the man-page macros?
+.if dan \{\
+. rn SH SH-orig
+. de SH
+. SH-orig
+. SCITECO_FOLDLEVEL 1
+. nop \\$*
+. .
+. rn SS SS-orig
+. de SS
+. SS-orig
+. SCITECO_FOLDLEVEL 2
+. nop \\$*
+. .
+.\}
+.
.\"
.\" Effectively disable paragraph filling in man pages.
.\" Word wrapping will be performed by Scintilla.
diff --git a/doc/tedoc.tes.1.in b/doc/tedoc.tes.1.in
index 9f87b37..f942552 100644
--- a/doc/tedoc.tes.1.in
+++ b/doc/tedoc.tes.1.in
@@ -124,7 +124,7 @@ The \fBGNU roff\fP \(lqman\(rq macros for writing man pages:
.SH AUTHOR
.
This manpage and the \*(ST program was written by
-.MT robin.haberkorn@googlemail.com
+.MT rhaberkorn@fmsbw.de
Robin Haberkorn
.ME .
\# EOF \ No newline at end of file
diff --git a/doc/tedoc.tes b/doc/tedoc.tes.in
index 1f13e54..cc4f726 100755
--- a/doc/tedoc.tes
+++ b/doc/tedoc.tes.in
@@ -3,12 +3,12 @@
0,2EJ !* FIXME: Memory limiting is too slow *!
-:EMQ[$SCITECOPATH]/getopt.tes
+:EIQ[$SCITECOPATH]/getopt.tes
@[format_header]{
FD--S .,(:L"S.|Z')@Xa I^J
- EBQ#tm
+ EBN[\#tm]
I\# GENERATED FROM Q.#sc (\.#sc):^J
I.SS  Ga -A-10"N I^J '
:Q.[topics]">
@@ -45,7 +45,7 @@
J <FR^J^J^J;>
J 0A-10"=D'
ZJ -A-10"=-D'
- EBQ#tm
+ EBN[\#tm]
G.[header]
I^J.^J
}
@@ -73,35 +73,34 @@
J <S<MC>; -D I^J -S< -D I^J.I >
J <FRS^J^J;>
J <FR^JS^J;>
- EBN#tm
+ EBN[\#tm]
G.c I^J.^J.^J
}
!* process command-line options *!
-[optstring]C M[getopt]"F (0/0) '
+[optstring]C
+M[getopt]U#ou Q#ou"< Invalid command-line^J 1 '
:Q[getopt.C]"<
[comment.start]!* [comment.end]*!
|
[comment.start]/* [comment.end]*/
'
-LR 0X#ou
-2LR 0X#tm EBN#tm EB L
-[.f
- <:L;R 0X.f EBQ.f EB L>
-].f
--EF
+Q#ou+1U#tm Q#tmU.i <:Q[\.i]:; EBN[\.i] %.i>
+
+!* switch to the main troff template (#tm) *!
+EB EF
I\#
-\# AUTOGENERATED FROM Q#tm
+\# AUTOGENERATED FROM Q[\#tm]
\# DO NOT EDIT MANUALLY!!!
\#^J
!* find insertion point *!
-FS^J.TEDOC^J^J
+:FS^J.TEDOC^J^J"F Missing .TEDOC call^J 1 '
EJ-1<
<
- 2U* EU.#scQ*
+ 2U* [*].#sc
!* extract comment *!
SQ[comment.start]$;
@@ -127,5 +126,5 @@ EJ-1<
EF
>
-2EL EWQ#ou
+2EL EWQ[\#ou]
EX
diff --git a/doc/tutorial.ms.in b/doc/tutorial.ms.in
index acbf9ac..92da0af 100644
--- a/doc/tutorial.ms.in
+++ b/doc/tutorial.ms.in
@@ -58,6 +58,7 @@ This tutorial guides you through the bare essentials of the editor.
Try the examples directly on this document.
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Get me out of here!
.
.LP
@@ -73,6 +74,7 @@ In the remainder of this document, command examples are therefore formatted as f
.DE
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Navigation
.
.LP
@@ -94,6 +96,7 @@ Using cursor movement or mouse buttons updates the movement
commands in the command line (the line at the bottom of the screen after \fB*\fP).
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Insertion
.
.LP
@@ -115,6 +118,7 @@ There is no \(lqinsert\(rq mode, you are merely providing a string argument
to the interactively executed \fBI\fP command.
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Deletion
.
.LP
@@ -130,6 +134,7 @@ Use the following command instead to discard all changes:
.DE
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Saving
.
.LP
@@ -155,6 +160,7 @@ Remember, you can type CTRL+W to undo even the file write and restore the
previous state of the file.
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Loading
.
.LP
@@ -184,6 +190,7 @@ in a typical UNIX shell!
Of course, you can press CTRL+W to revert opening the file.
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Search and replace
.
.LP
@@ -210,6 +217,7 @@ so \fBS\fP\*$ repeats the last search and \fBFR\fP\*($$ repeats the last
search-replace operation.
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Q-Registers
.
.LP
@@ -232,6 +240,7 @@ This however might not work out of the box if you are running the ncurses
version of \*(ST.
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Programming
.
.LP
@@ -247,6 +256,7 @@ of performing a search-replace operation on the entire buffer:
.DE
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Customize
.
.LP
@@ -271,6 +281,7 @@ $ @PACKAGE@ --no-profile
.DE
.
.NH 2
+.SCITECO_FOLDLEVEL 1
Further reading
.
.LP
@@ -280,7 +291,7 @@ Consult or even print the official Cheat Sheet to extend your
\(lqvocabulary\(rq of \*(ST commands:
.
.ID 0
-https://sciteco.sf.net/manuals/cheat-sheet.pdf
+https://sciteco.fmsbw.de/manuals/cheat-sheet.pdf
.DE
.
.LP
@@ -302,16 +313,15 @@ To open the language reference, type:
.LP
If you want to read the tutorial at any later time, just
type \fB?\fPtutorial\*$.
-You may also want to have a look at the Wiki and FAQ:
+You may also want to have a look at the Knowledge Base and FAQ:
.
.ID 0
-https://github.com/rhaberkorn/sciteco/wiki
+https://sciteco.fmsbw.de/knowledge/
.DE
.
.LP
If you cannot find a solution to your problem,
-you can of course open an Issue or Discussion on \*(ST's
-Github page.
+you can of course write to the dings@fmsbw.de mailing list.
We are also happy to help out on the official IRC
channel:
Join #sciteco at irc.libera.chat.
generated by cgit v1.2.3 (git 2.25.1) at 2026-02-02 17:19:41 +0000