implemented self-documenting (online) help system

 * the new "?" (help) command can be used to look up
   help topics.
 * help topics are index from $SCITECOPATH/women/*.woman.tec
   files.
 * looking up a help topic opens the corresponding "womanpage"
   and jumps to the position of the topic (it acts like an anchor
   into the document).
 * styling is performed by *.woman.tec files.
 * Setting up the Scintilla view and munging the *.tec file
   is performed by the new "woman.tes" lexer.
   On supporting UIs (Gtk), womanpages are shown in a variable-width
   font.
 * Woman pages are usually not hand-written, but generated from manpages.
   A special Groff post-processor grosciteco has been introduced for this
   purpose. It is much like grotty, but can output SciTECO macros for styling
   the document (ie. the *.woman.tec files).
   It is documented in its own man-page.
 * grosciteco also introduces sciteco.tmac - special Troff macros
   for controlling the formatting of the document in SciTECO.
   It also defines .SCITECO_TOPIC which can be used to mark up
   help topics/terms in Troff markup.
 * Woman pages are generated/formatted by grosciteco at compile-time, so
   they will work on platforms without Groff (ie. as on windows).
 * Groff has been added as a hard compile-time requirement.
 * The sciteco(1) and sciteco(7) man pages have been augmented with
   help topic anchors.

8 files changed, 813 insertions, 17 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9909122..e63284a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,33 +1,79 @@
 # Make sure that $BOOTSTRAP_SCITECO and the SciTECO-based
 # substitutor is available.
-# The target `sciteco` binary has already been built,
-# but using $BOOTSTRAP_SCITECO ensures that we use
-# a version running on the host machine when cross-compiling
-# with --disable-bootstrap.
 include $(top_srcdir)/bootstrap.am
 
-man_MANS = sciteco.1
-EXTRA_DIST = sciteco.1.in
-CLEANFILES = sciteco.1
+# grosciteco is a troff postprocessor similar to grotty
+# which can be used to produce SciTECO-friendly output
+# (woman pages).
+dist_bin_SCRIPTS = grosciteco.tes
+# grosciteco, like many other postprocessors, works
+# best with its own macro package.
+# Unfortunately, there is no way to query the built-in
+# Groff tmac path.
+# Therefore, the "sciteco" macros are installed into
+# SciTECO's pkgdatadir. Users can copy this file, set up
+# environment variables like $GROFF_TMAC_PATH or pass
+# the directory via `groff -M`.
+dist_pkgdata_DATA = sciteco.tmac
+
+# Fix up the hash-bang line of grosciteco upon installation
+# to refer to the installed sciteco binary.
+# This takes --program-prefix into account.
+install-exec-hook:
+	@SED@ -i "1s,#!.*sciteco,#!$(bindir)/`echo sciteco | @SED@ '$(transform)'`$(EXEEXT)," \
+	         $(DESTDIR)$(bindir)/grosciteco.tes
+
+womendir = $(scitecolibdir)/women
+
+women_DATA = grosciteco.tes.1.woman grosciteco.tes.1.woman.tec
+CLEANFILES = grosciteco.tes.1.intermediate
+
+women_DATA += sciteco.1.woman sciteco.1.woman.tec
+CLEANFILES += sciteco.1.intermediate
+
+women_DATA += sciteco.7.woman sciteco.7.woman.tec
+CLEANFILES += sciteco.7.intermediate
+
+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 \
+	                   $(basename $<).woman $(basename $<).woman.tec $<
+
+%.intermediate : % sciteco.tmac
+	@GROFF@ -Z -Tascii -t -man -M@srcdir@ -msciteco $< >$@
+
+man_MANS = grosciteco.tes.1
+EXTRA_DIST = grosciteco.tes.1.in
+
+man_MANS += sciteco.1
+EXTRA_DIST += sciteco.1.in
 
 man_MANS += sciteco.7
 EXTRA_DIST += sciteco.7.template
-CLEANFILES += sciteco.7 sciteco.7.in sciteco.7.htbl
+CLEANFILES += sciteco.7.in sciteco.7.htbl
 SOURCES = $(wildcard @top_srcdir@/src/*.cpp)
 
-EXTRA_DIST += generate-docs.tes htbl.tes
+CLEANFILES += $(man_MANS)
+
+dist_noinst_SCRIPTS = generate-docs.tes htbl.tes
 
 %.in : %.template generate-docs.tes $(SOURCES)
-	$(BOOTSTRAP_SCITECO) -m @srcdir@/generate-docs.tes \
-			     $@ $< $(SOURCES)
+	$(SCITECO_FULL) -m @srcdir@/generate-docs.tes \
+	                $@ $< $(SOURCES)
 
 if BUILD_HTMLMAN
-html_DATA = sciteco.1.html sciteco.7.html
+html_DATA = grosciteco.1.html sciteco.1.html sciteco.7.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
-	$(BOOTSTRAP_SCITECO) -m @srcdir@/htbl.tes $< $@
+	$(SCITECO_FULL) -m @srcdir@/htbl.tes $< $@
 
 %.html : %.htbl
 	@GROFF@ -Thtml -man $< >$@
diff --git a/doc/generate-docs.tes b/doc/generate-docs.tes
index 2d5af6a..ee4820c 100755
--- a/doc/generate-docs.tes
+++ b/doc/generate-docs.tes
@@ -38,6 +38,7 @@ j<fr
 .br
 ;>
 j<sMA;.u.t 1ua<."=1;'-a"A|1;'-a"V-1ua1;'r> qa"Sq.tj|.,q.txa.,q.td i
+.SCITECO_TOPIC "Qa"
 .B Qa
 '>
 j<s[MC];.u.t-s[.,q.t-1xa .-1,q.td i
diff --git a/doc/grosciteco.tes b/doc/grosciteco.tes
new file mode 100755
index 0000000..d84c6ab
--- /dev/null
+++ b/doc/grosciteco.tes
@@ -0,0 +1,283 @@
+#!/usr/bin/env sciteco -m
+!* grosciteco.tes <output-woman> <output-tec> <input> *!
+
+!* Process command-line options *!
+LR 0X[output-woman] 2LR 0X[output-tec] 2LR 0X[input] HK
+EBQ[input]
+
+! skip whitespace characters !
+@#sw{
+  <0A-^^ "N 1; ' :C;>
+}
+
+!* skip N (string) arguments beginning with current one *!
+@#sa{
+  "~1'<
+    <0A-^^ "= 1; ' 0A-10"= 1; ' :C;> :M#sw
+  >
+}
+
+!* get next integer argument, skipping it *!
+@#gi{
+  \ (0A-^^-"= :C ' <0A"D :C; | 1; '> :M#sw)
+}
+
+!* skip end of command *!
+@#sc{
+  0A-10"= :C '
+}
+
+0U[text.lines] 0U[pos.v] 0U[pos.h]
+
+!* move to (pos.h,pos.v) relative to origin, making space if necessary *!
+@[move]{ [.n
+  U.n J
+  Q[pos.v]-Q[text.lines]">
+    ZJ Q[pos.v]-Q[text.lines]<I^J>
+    Q[pos.v]U[text.lines]
+  |
+    Q[pos.v]L
+  '
+  Q[pos.h]<.-Z"= I  | 0A-10"= I  | C' '>
+  Q.n<.-Z"= 1; ' 0A-10"= 1; ' D>
+].n }
+
+@[style]{ [.l
+  U.l Q[font]-Q[default-style]"N
+    .-Q.lESSTARTSTYLING Q[font],Q.lESSETSTYLING
+  '
+].l }
+
+[topics]
+
+!*
+ * Special characters
+ * FIXME: Use UTF8 characters once available
+ *!
+[glyphs.**]*
+[glyphs.\-]-
+[glyphs.aa]'
+[glyphs.dq]"
+[glyphs.hy]-
+[glyphs.la]<
+[glyphs.ra]>
+[glyphs.lq]"
+[glyphs.rq]"
+[glyphs.rs]\
+[glyphs.+]+
+
+!* process formatter commands *!
+@[format]{ <
+  .-Z"= 1; '
+  0AU[cmd] C
+  Ocmd.U[cmd]
+
+  !cmd.x!
+    :M#sw
+    0AU[cmd] C
+    Ocmd.xU[cmd]
+
+    !cmd.xT!
+      2:M#sa :M#sc F<
+    !cmd.xr!
+      :M#sa :M#giU[res] :M#giU[res.h] :M#giU[res.v] :M#sc F<
+    !cmd.xi!
+      :M#sa :M#sc F<
+    !cmd.xF!
+      L F<
+    !cmd.xX!
+      :M#sw .(W).X.w
+      Ocmd.xXQ.w
+      !cmd.xXsciteco_topic!
+        !*
+         * FIXME: The buffer position of this topic might still
+         * change due to movement commands (esp. when formatting
+         * a table). Only the line+column should no longer change.
+         * Either store line+column or use markers.
+         *!
+        [* EB 0:M[move] .U.d ]*
+        :EU[topics]\.d:
+        C :X[topics]
+        L F<
+      !cmd.xXsciteco_tt!
+        [* EB 0:M[move] .U[ttstart] ]*
+        L F<
+      !cmd.xXsciteco_tt_end!
+        [* EB 0:M[move]
+          .-Q[ttstart]<
+            Q[ttstart]ESSTARTSTYLING Q[ttstart]ESGETSTYLEAT+16,1ESSETSTYLING
+          %[ttstart]>
+        ]*
+        L F<
+      !cmd.xXtty!
+      !cmd.xXdevtag!
+        L F<
+
+    !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]{\.#ntESSTYLESETFONTCourier^J}
+      Ocmd.xfQ[font]
+      !cmd.xfR!
+        Q.nU[default-style]
+        @:EU[styles]{16ESSTYLESETFONTCourier^J}
+        F<
+      !cmd.xfB!
+        @:EU[styles]{1,\.nESSTYLESETBOLD 1,\.#ntESSTYLESETBOLD^J}
+        F<
+      !cmd.xfBI!
+        @:EU[styles]{1,\.nESSTYLESETBOLD 1,\.#ntESSTYLESETBOLD^J}
+      !cmd.xfI!
+        @:EU[styles]{1,\.nESSTYLESETITALIC 1,\.#ntESSTYLESETITALIC^J}
+        @:EU[styles]{0EJ-1"= 1,\.nESSTYLESETUNDERLINE 1,\.#ntESSTYLESETUNDERLINE '^J}
+        F<
+
+    !cmd.xt!
+      :M#sa :M#sc F<
+    !cmd.xs!
+      1;
+
+  !cmd.p!
+    :M#sw :M#gi Q[pos.v]U[origin.v] :M#sc F<
+
+  !cmd.f!
+    :M#sw :M#giU[font] :M#sc F<
+
+  !cmd.s!
+    :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<
+
+  !cmd.v!
+    :M#sw :M#gi/Q[res.v]%[pos.v] :M#sc F<
+
+  !cmd.H!
+    :M#sw :M#gi/Q[res.h]U[pos.h] :M#sc F<
+
+  !cmd.h!
+    :M#sw :M#gi/Q[res.h]%[pos.h] :M#sc F<
+
+  !cmd.m!
+    :M#sw
+    0AU[cmd] C
+    Ocmd.mU[cmd]
+
+    !cmd.md!
+      :M#sc F<
+
+  !cmd.D!
+    :M#sw
+    0AU[cmd] C
+    Ocmd.DU[cmd]
+
+    !cmd.DF!
+      :M#sw
+      0AU[cmd] C
+      Ocmd.DFU[cmd]
+
+        !cmd.DFd!
+          :M#sc F<
+
+    !cmd.Dl!
+      :M#sw :M#gi/Q[res.h]+Q[pos.h]U.[to.h] :M#gi/Q[res.v]+Q[pos.v]U.[to.v] :M#sc
+      [* EB
+      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 '
+        1:M[move] I+ %[pos.v]
+        Q.v-Q[pos.v]<
+          1:M[move] I| %[pos.v]
+        >
+        1:M[move] I+
+        Q.[to.v]U[pos.v]
+      |
+        ! horizontal line !
+        Q.[to.h]-Q[pos.h]"< Q[pos.h]U.h Q.[to.h]U[pos.h] | Q.[to.h]U.h '
+        1:M[move] I+ %[pos.h]
+        Q.h-Q[pos.h]<
+          1:M[move] I- %[pos.h]
+        >
+        1:M[move] I+
+        Q.[to.h]U[pos.h]
+      '
+      ]* F<
+
+  !cmd.t!
+    :M#sw .(:M#sa).X.w
+    [* EB :Q.w:M[move]
+    G.w :Q.w:M[style] ]*
+    :Q.w%[pos.h] :M#sc F<
+
+  !cmd.C!
+    :M#sw .(:M#sa).X.w
+    [* EB 1:M[move]
+    G[glyphs.Q.w] 1:M[style] ]* :M#sc F<
+
+  !cmd.c!
+    :M#sw 0AU.w C
+    [* EB 1:M[move]
+    G[glyphs.U.w] 1:M[style] ]* :M#sc F<
+
+  !cmd.n!
+    :M#sw :M#gi :M#gi :M#sc F<
+
+  !cmd.w!
+    :M#sc F<
+> }
+
+!*
+ * Inline local macro invocations in [format]
+ * This speeds up runtime by 25%
+ *!
+EQ[format]
+  J<FR:M[move]Q[move];>
+  J<FR:M[style]Q[style];>
+  J<FR:M#saQ#sa;>
+  J<FR:M#giQ#gi;>
+  J<FR:M#swQ#sw;>
+  J<FR:M#scQ#sc;>
+  !*
+   * Compress whitespace, kind of dangerous:
+   * J<FRS ;>
+   *!
+Q*U*
+
+:M[format]
+
+!*
+ * Generate the styling instructions based on the styles
+ * of the womanpage buffer. The styles are configured according
+ * to their font positions (already in `styles`).
+ * Styles are NOT generated in `styles` immediately during
+ * formatting, since the buffer positions of text to style
+ * can still change with `move` operations that add whitespace.
+ * Also, here we can generate a minimal list of styling operations
+ * ending up with much smaller *.tec files.
+ * TODO: The size can still be improved by using SCI_SETSTYLINGEX
+ * if appropriate.
+ *!
+EB J 0U#cs 0U#cd
+<
+  .ESGETSTYLEATUs Qs"< Qs= '
+  .-Z"< Qs-Q#cs"= C F< ' '
+  Q#cs"N
+    .-Q#cd Ul
+    @:EU[styles]{\#cdESSTARTSTYLING \#cs,\lESSETSTYLING^J}
+  '
+  QsU#cs .U#cd
+:C;>
+
+!*
+ * Save the clear-text part of the document into <output-woman>
+ *!
+EWQ[output-woman]
+
+EQ[styles]
+
+!* Generate topic index *!
+J I!*Q[topics]*!^J
+
+EWQ[output-tec]
+
+-EX
diff --git a/doc/grosciteco.tes.1.in b/doc/grosciteco.tes.1.in
new file mode 100644
index 0000000..e890a96
--- /dev/null
+++ b/doc/grosciteco.tes.1.in
@@ -0,0 +1,200 @@
+.ds ST \\fB@PACKAGE_NAME@\\fP
+.
+.
+.TH "grosciteco.tes" 1 \
+    "@DATE@" \
+    "@PACKAGE_NAME@ Version @PACKAGE_VERSION@"
+.
+.
+.SCITECO_TOPIC grosciteco grosciteco.tes
+.SH NAME
+grosciteco \-\-
+GNU roff post-processor for \*(ST
+.
+.
+.SH SYNOPSIS
+.
+.SY grosciteco.tes
+.I text_output
+.I tec_output
+.I input
+.YS
+.
+.
+.SH DESCRIPTION
+.
+\fBgrosciteco\fP is a post-processor for \fBGNU roff\fP which works
+similar to \fBgroff\fP's \fBgrotty\fP post-processor and driver.
+Similarily, \fBgrosciteco\fP is a plain-text formatter \(em but
+since it lays out the document itself and is written in the \*(ST
+language, it will generate an additional \*(ST macro that can be
+executed to style the plain-text document.
+.LP
+.SCITECO_TOPIC woman women womanpage
+The plain-text document will usually have the extension \(lqwoman\(rq
+and the accompanying \*(ST macro will have the extension \(lqwoman.tec\(rq.
+Both files combined are called \fIwomanpage\fP since they are commonly
+\*(ST-formatted man pages.
+.LP
+Furthermore, \fIwomanpages\fP can be indexed by search terms
+(called topics).
+A per-file topic index is generated as part of the \(lqwoman.tec\(rq
+output file.
+Users of \fBgrosciteco\fP can define topics in \fBtroff\fP
+markup using the \fBSCITECO_TOPIC\fP troff macro defined
+in the \(lqsciteco.tmac\(rq macro package.
+This macro package should always be loaded when processing
+\fBtroff\fP documents which are going to be post-processed by
+\fBgrosciteco\fP.
+.LP
+Preparing a \fIwomanpage\fP for display is usually performed
+automatically by \*(ST's \(lqwoman.tes\(rq lexer definition
+whenever you open a \(lq*.woman\(rq file in \*(ST.
+\fIwomanpages\fP are recommended to be installed into a special
+directory in \*(ST's standard library.
+The \*(ST command \fB?\fP provides an online help feature
+which gives fast access to properly-installed \fIwomanpages\fP.
+It builds a global topic index of all \fIwomanpages\fP installed
+in the \fB$SCITECOPATH/women\fP directory.
+\fBgrosciteco\fP is thus a central component in providing
+\*(ST's help system, in documenting internal commands, the
+\*(ST standard library macros and third-party macro packages.
+The generation of \fIwomanpages\fP at compile-time means
+that no \fBtroff\fP is required by end users to browse
+documentation within \*(ST.
+.
+.
+.SH OPTIONS
+.
+.IP "\fItext_output\fP
+The plain-text output file, e.g. \(lqgreat-macro.woman\(rq.
+.IP "\fItec_output\fP
+The \*(ST script that when executed after loading
+\fItext_output\fP into a Scintilla view, styles that document.
+It can be thought of as representing meta-information
+for \fItext_output\fP.
+In order to cooperate with the \(lqwoman\(rq lexer and
+\*(ST's \fB?\fP command, its file name should be
+\fItext_output\fP.tec, e.g. \(lqgreat-macro.woman.tec\(rq.
+.IP "\fIinput\fP"
+The \fIinput\fP file is in \fBtroff\fP's device-independant
+output format.
+.
+.
+.SH SPECIAL TROFF MACROS
+.
+.SCITECO_TOPIC sciteco.tmac tmac
+\fBtroff\fP documents should be processed with the
+\(lqsciteco.tmac\(rq macro package that also ships with
+\*(ST.
+It tweaks formatting for display in \*(ST (assuming
+that the lexer system for \fIwomanpages\fP is in place)
+and provides the following \fBtroff\fP macros that
+can be called by documentation authors:
+.
+.TP
+.TQ
+\fB.SCITECO_TOPIC \fItopics...\fR
+.SCITECO_TOPIC .SCITECO_TOPIC SCITECO_TOPIC
+Defines one or more topics in \*(ST's help system.
+Every topic must be in its own macro argument.
+A \fItopic\fP can be looked up in \*(ST using
+the \fB?\fItopic\fB$\fR command, but in case of
+topic collisions, \*(ST will modify the topic name
+to keep it unique.
+The \fB?\fP (question mark) command will jump to the position
+that corresponds to the macro call in \fBtroff\fP
+markup.
+Topics can and should only consist of printable characters,
+so escape characters should be written in their up-caret
+notation (e.g. \(lq^[\(rq instead of escape).
+\*(ST expands control characters to their printabel form
+when looking up terms.
+.TQ
+\fB.SCITECO_TT\fP [\fIline length\fP]
+.SCITECO_TOPIC .SCITECO_TT SCITECO_TT
+Marks the beginning of an area that must be formatted
+in a monospaced font.
+\fBgrosciteco\fP has only limited support for Troff font styles
+and the font family used depends on the \*(ST UI used to
+show the womanpage.
+Since line drawing commands assume a TTY-like output device,
+.B SCITECO_TT
+should precede those sections of text (including the \fBtbl\fP
+macro \fBTS\fP).
+An optional temporary \fIline length\fP may also be specified
+which is especially useful for tables.
+.TQ
+\fB.SCITECO_TT_END\fP [\fBSP\fP]
+.SCITECO_TOPIC .SCITECO_TT_END SCITECO_TT_END
+Marks the end of an area that must be formatted in a
+monospaced font.
+The optional \fBSP\fP keyword may be specified to skip one
+line vertically (via troff's \fB.sp\fP request).
+.
+.LP
+These public macros will be ignored if \(lqsciteco.tmac\(rq
+is not loaded, so it is safe to use them in man pages
+that are also installed into the system.
+.LP
+Note that \(lqsciteco.tmac\(rq is not installed into the
+standard \fBGNU roff\fP macro search directories, but into
+\*(ST data directory at \(lq@pkgdatadir@\(rq.
+It must thus be moved or linked manually into one of the
+search paths, or the data dir must be added to the search
+paths.
+Alternatively, you may also add it to the \fBgroff\fP
+command line with the \fB-M\fP option.
+.
+.
+.SH EXAMPLES
+.
+The following UNIX shell commands will generate the \fIwomanpage\fP for
+a \*(ST macro package with a man page called
+\fBgreat-macro.tes\fP(7sciteco):
+.
+.RS
+.EX
+.SCITECO_TT
+groff -Z -Tascii -man -M@pkgdatadir@ -msciteco \\
+      great-macro.tes.7sciteco >great-macro.tes.7sciteco.intermediate
+grosciteco.tes great-macro.tes.7sciteco.woman great-macro.tes.7sciteco.woman.tec \\
+               great-macro.tes.7sciteco.intermediate
+.SCITECO_TT_END
+.EE
+.RE
+.LP
+The resulting files should be installed to
+.B "@scitecolibdir@/women"
+(or wherever \fB$SCITECOPATH\fP points to at runtime)
+to make the files accessible in \*(ST's online-help system.
+.
+.
+.SH BUGS
+.
+\fBgrosciteco\fP is quite slow, although this is a \*(ST issue.
+.
+.
+.SH SEE ALSO
+.
+.TP
+\*(ST invocation and help on its environment variables:
+.BR sciteco (1)
+.TP
+Language reference including additional information on the \fB?\fP command:
+.BR sciteco (7)
+.TP
+The \fBGNU roff\fP front end program:
+.BR groff (1)
+.TP
+The \fBGNU roff\fP \(lqman\(rq macros for writing man pages:
+.BR groff_man (7)
+.
+.
+.SH AUTHOR
+.
+This manpage and the \*(ST program was written by
+.MT robin.haberkorn@googlemail.com
+Robin Haberkorn
+.ME .
+\# EOF
\ No newline at end of file
diff --git a/doc/htbl.tes b/doc/htbl.tes
index 8998d79..4118e55 100755
--- a/doc/htbl.tes
+++ b/doc/htbl.tes
@@ -1,6 +1,6 @@
-#!/usr/bin/sciteco -m
-! ./htbl.tes <input> <output> !
-! Troff tbl "drop-in" replacement !
+#!/usr/bin/env sciteco -m
+!* htbl.tes <input> <output> *!
+!* Troff tbl "drop-in" replacement *!
 
 LR 0X#in 2LR 0X#ou EBQ#in EB -EF
 
diff --git a/doc/sciteco.1.in b/doc/sciteco.1.in
index bb7d29b..e6c4d8a 100644
--- a/doc/sciteco.1.in
+++ b/doc/sciteco.1.in
@@ -13,6 +13,7 @@ Scintilla-based \fBT\fPext \fBE\fPditor and \fBCO\fPrrector
 .
 .SH SYNOPSIS
 .
+.SCITECO_TOPIC "sciteco"
 .SY @PACKAGE@
 .OP "-h|--help"
 .OP "-e|--eval" macro
@@ -37,6 +38,7 @@ 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 by the
 .B "--mung"
@@ -48,14 +50,20 @@ 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 \(lq#!\(rq.
 Therefore under UNIX-like operating systems, TECO macro files may be
-invoked as scripts by using a Hashbang line like
+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
 .EE
+.SCITECO_TT_END
 .RE
 .
 .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
@@ -101,12 +109,14 @@ 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
@@ -139,8 +149,10 @@ 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.
@@ -149,10 +161,12 @@ If the option is specified, the
 .B \-\-mung
 option has no effect.
 .IP "\fB-m\fR, \fB--mung\fR \fIfile"
+.SCITECO_TOPIC "-m" "--mung"
 Mung \fIfile\fP.
 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
@@ -167,12 +181,14 @@ 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.
@@ -196,6 +212,7 @@ these registers.
 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
@@ -208,6 +225,7 @@ 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.
@@ -217,6 +235,7 @@ 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.
@@ -228,6 +247,7 @@ 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
@@ -253,6 +273,7 @@ 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.
@@ -269,6 +290,7 @@ can be modified in the profile macro.
 \*(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
@@ -285,6 +307,7 @@ Note that this signal can usually also be generated when pressing
 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
@@ -298,6 +321,7 @@ program termination or user-programmed behaviour.
 .SH FILES
 .
 .TP
+.SCITECO_TOPIC ".teco_ini" "profile"
 .B $SCITECOCONFIG/.teco_ini
 Default profile macro.
 .TP
@@ -309,6 +333,7 @@ and opening files specified on the command line.
 .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.
@@ -316,6 +341,7 @@ 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
@@ -324,11 +350,13 @@ 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
@@ -344,6 +372,10 @@ It may also be used as a template for
 Language reference:
 .BR sciteco (7)
 .TP
+The \fBtroff\fP post-processor for \*(ST, including
+information on how to write \(lqwomanpages\(rq:
+.BR grosciteco (1)
+.TP
 Homepage:
 .UR @PACKAGE_URL@
 \*(ST at Sourceforge
diff --git a/doc/sciteco.7.template b/doc/sciteco.7.template
index aa7ae81..f3f5b48 100644
--- a/doc/sciteco.7.template
+++ b/doc/sciteco.7.template
@@ -7,12 +7,14 @@
     "@PACKAGE_NAME@ Version @PACKAGE_VERSION@"
 .
 .
+.SCITECO_TOPIC language
 .SH NAME
 @PACKAGE@ \-\-
 Language reference for the \*(ST text editor and language
 .
 .
 .SH INTRODUCTION AND PHILOSOPHY
+.SCITECO_TOPIC philosophy
 .
 \*(ST is a powerful editor and interactive programming language
 following an unique paradigm of text editing.
@@ -38,6 +40,7 @@ operations, \*(ST supports undoing and redoing on a per-character,
 per-command or even user-configurable level undoing most of the
 side-effects on the overall editor state.
 .LP
+.SCITECO_TOPIC TECO
 \*(ST is a member of the TECO family of text editor languages,
 invented by Dan Murphy in the 1960s.
 TECO was initially a purely command-driven editor that evolved
@@ -47,6 +50,7 @@ Emacs later became an independent program that eventually
 dropped TECO as its scripting language in favour of Lisp.
 \*(ST is not the first attempt to devise a TECO-based interactive
 screen editor.
+.SCITECO_TOPIC "Video TECO"
 It is very similar to \fIVideo TECO\fP, a little known editor
 that pioneered the concept.
 When \fIVideo TECO\fP wanted to \(lqoutdo classic TECOs in every way\(rq,
@@ -94,6 +98,7 @@ Keys with a printable representation (letters, digits and special
 characters) are translated to their printable representation.
 Shift-combinations automatically result in upper-case letters.
 .IP 2.
+.SCITECO_TOPIC ctrl
 Control-combinations (e.g. CTRL+A) are translated to control
 codes, that is a code smaller than 32.
 The control code can be calculated by stripping the seventh bit
@@ -128,12 +133,15 @@ next subsection.
 .
 .SS Function Key Macros
 .
+.SCITECO_TOPIC "function key"
 By default function keys except Escape, Backspace and Return are
 ignored by \*(ST.
 By setting bit 6 of the \fBED\fP flag variable, function key handling
 is enabled:
 .EX
+.SCITECO_TT
 0,64ED
+.SCITECO_TT_END
 .EE
 This is usually performed in the editor profile.
 With certain interfaces (curses) after enabling function keys,
@@ -149,61 +157,83 @@ These are Q-Register strings inserted into the command stream
 keys (or combinations) are pressed.
 The following list of Function Key Macro registers are supported:
 .TP 9
+.SCITECO_TOPIC ^FDOWN
 .B ^FDOWN
 .TQ
+.SCITECO_TOPIC ^FUP
 .B ^FUP
 Inserted when the down/up cursor keys are pressed.
 .TP
+.SCITECO_TOPIC ^FLEFT
 .B ^FLEFT
 .TQ
+.SCITECO_TOPIC ^FSLEFT
 .B ^FSLEFT
 Inserted when the left or shift-left cursor keys are
 pressed.
 .TP
+.SCITECO_TOPIC ^FRIGHT
 .B ^FRIGHT
 .TQ
+.SCITECO_TOPIC ^FSRIGHT
 .B ^FSRIGHT
 Inserted when the right or shift-right cursor keys are
 pressed.
 .TP
+.SCITECO_TOPIC ^FHOME
 .B ^FHOME
 .TQ
+.SCITECO_TOPIC ^FSHOME
 .B ^FSHOME
 Inserted when the Home or shift-Home keys are pressed.
 .TP
+.SCITECO_TOPIC ^FF
 .BI ^FF x
 Inserted when the Fx-key is pressed
 .RI ( x
 is a number between 0 and 63).
 .TP
+.SCITECO_TOPIC ^FDC
 .B ^FDC
 .TQ
+.SCITECO_TOPIC ^FSDC
 .B ^FSDC
 Inserted when the Delete or shift-Delete key is pressed.
 .TP
+.SCITECO_TOPIC ^FIC
 .B ^FIC
 .TQ
+.SCITECO_TOPIC ^FSIC
 .B ^FSIC
 Inserted when the Insert or shift-Insert key is pressed.
 .TP
+.SCITECO_TOPIC ^FPPAGE
 .B ^FPPAGE
 .TQ
+.SCITECO_TOPIC ^FNPAGE
 .B ^FNPAGE
 Inserted when the Page-Up or Page-Down key is pressed.
 .TP
+.SCITECO_TOPIC ^FPRINT
 .B ^FPRINT
 .TQ
+.SCITECO_TOPIC ^FSPRINT
 .B ^FSPRINT
 Inserted when the Print or shift-Print key is pressed.
 .TP
+.SCITECO_TOPIC ^FA1
 .B ^FA1
 .TQ
+.SCITECO_TOPIC ^FA3
 .B ^FA3
 .TQ
+.SCITECO_TOPIC ^FB2
 .B ^FB2
 .TQ
+.SCITECO_TOPIC ^FC1
 .B ^FC1
 .TQ
+.SCITECO_TOPIC ^FC3
 .B ^FC3
 Inserted when the numeric key pad's upper left key (7),
 upper right key (9), central key (5), lower left key (1),
@@ -211,17 +241,23 @@ or lower right key (3) is pressed and num-lock is disabled.
 The key-pad's cursor keys are handled like the regular
 cursor keys.
 .TP
+.SCITECO_TOPIC ^FEND
 .B ^FEND
 .TQ
+.SCITECO_TOPIC ^FSEND
 .B ^FSEND
 Inserted when the End or shift-End key is pressed.
 .TP
+.SCITECO_TOPIC ^FHELP
 .B ^FHELP
 .TQ
+.SCITECO_TOPIC ^FSHELP
 .B ^FSHELP
 Inserted when the Help or shift-Help key is pressed.
 .TQ
+.SCITECO_TOPIC ^FCLOSE
 .B ^FCLOSE
+ISCITECO_TOPIC when the Close key has been pressed.
 Inserted when the Close key has been pressed.
 More importantly, this key is emulated in some GUIs
 (notably GTK+) when the user tries to close \*(ST's
@@ -274,7 +310,9 @@ states.
 For instance, to enable the \(lq^FRIGHT\(rq function key macro
 only in the \(lqstart\(rq state, you could set:
 .EX
+.SCITECO_TT
 1^_U[^FRIGHT]
+.SCITECO_TT_END
 .EE
 .LP
 A set of useful Function Key Macros are provided in the
@@ -298,6 +336,7 @@ are self-inserting, i.e. they insert themself into the command
 stream and may be processed as regular commands or part of them.
 .
 .SS Immediate Editing Commands
+.SCITECO_TOPIC immediate
 .
 In the following table, the Immediate Editing Commands are outlined.
 Some of them are ubiquitous and are not used used as regular
@@ -311,12 +350,14 @@ TECO implementations.
 Most of these commands are control codes, so their control code
 mnemonics are given as well.
 .
+.SCITECO_TT 90n
 .TS
 expand,allbox,tab(;);
 LB LB LB LB LBX
 L L L L L.
 Name;Code;Mnemonics;Context;Description
 T{
+.SCITECO_TOPIC ^G toggle
 Toggle modifier
 T};7;^G;T{
 Everywhere
@@ -330,6 +371,7 @@ effectively switches between undo and redo modes.
 The modifier also influences the behaviour of the TAB key.
 T}
 T{
+.SCITECO_TOPIC ^J enter LF CR
 Insert end of line sequence
 T};10;^J, Return, Enter;T{
 Everywhere
@@ -340,12 +382,14 @@ If automatic end of line sequence translation is disabled,
 the return key will insert the current buffer's end of line
 sequence (line feed; carriage return, line feed; or
 carriage return) according to the
+.SCITECO_TOPIC SCI_GETEOLMODE
 .B SCI_GETEOLMODE
 Scintilla message.
 In auto-EOL-translation mode, the return key will always
 insert a line feed.
 T}
 T{
+.SCITECO_TOPIC ^H backspace
 Rub out character
 T};8;^H, Backspace;T{
 Everywhere
@@ -365,6 +409,7 @@ Inserts the next character from the rubbed out part
 of the command line.
 T}
 T{
+.SCITECO_TOPIC ^W
 Rub out word/command
 T};23;^W;T{
 Non-empty file name arguments
@@ -382,6 +427,7 @@ Non-empty string arguments
 T};T{
 Rub out last word according to Scintilla's definition of a word
 as set by
+.SCITECO_TOPIC SCI_SETWORDCHARS
 .BR SCI_SETWORDCHARS .
 T}
 \^;\^;\^;T{
@@ -421,6 +467,7 @@ i.e. insert at least one character and repeat until
 a new command could begin.
 T}
 T{
+.SCITECO_TOPIC ^U
 Rub out string
 T};21;^U;T{
 String arguments
@@ -491,11 +538,13 @@ This takes Scintilla's indention policy into account
 and results in the same indention as the \fB^I\fP command.
 T}
 T{
+.SCITECO_TOPIC ^Z suspend
 Suspend process
 T};26;^Z;T{
 Everywhere
 T};T{
 Suspends process using
+.SCITECO_TOPIC SIGTSTP
 .BR SIGTSTP .
 This is only an immediate editing command on platforms supporting
 this signal (usually Unices).
@@ -507,6 +556,7 @@ 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 interrupt
 Interrupt
 T};3;^C;T{
 \*(ST is busy
@@ -527,6 +577,7 @@ is self-inserting and might be typed as part of regular commands.
 The \fB^C\fP command itself is disallowed in interactive mode, though.
 T}
 .TE
+.SCITECO_TT_END SP
 .
 .SS Undo and Redo
 .
@@ -535,6 +586,7 @@ effectively constitute \*(ST's undo and redo support.
 As all features implemented by the immediate editing commands,
 undo and redo is only possible when using \*(ST interactively.
 .LP
+.SCITECO_TOPIC rubout undo
 When a character is rubbed out, \*(ST reverses the side effects it
 had when it was typed.
 The rubbed out characters are not discarded immediately but kept
@@ -548,6 +600,7 @@ they can still be seen in the command line's rubbed out area.
 The rubbed out command line is not a part of the command-line macro,
 though.
 .LP
+.SCITECO_TOPIC rubin redo
 Changes can be redone by typing the characters at the command line
 cursor or using one of the re-insertion commands \(em therefore
 undo and redo looks like moving the command line cursor back and forth.
@@ -585,6 +638,7 @@ 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
 so in a manner similar to Posix shells.
 Upon first invocation they try to fully or partially complete the file
@@ -626,6 +680,7 @@ in the user's home directory.
 .
 .
 .SH USER INTERFACE
+.SCITECO_TOPIC UI "user interface"
 .
 \*(ST can be built with support for different textual and
 graphical user interfaces.
@@ -638,6 +693,7 @@ user-interface agnostic macros and profiles easier.
 The user interface will always be segmented into the following
 areas from top of the program window to bottom:
 .IP \(bu 2
+.SCITECO_TOPIC info
 The \fIinfo area\fP identifying the currently edited buffer or
 Q-Register.
 This area is currently sometimes omitted.
@@ -655,6 +711,7 @@ that occurred.
 This area will show errors, warnings, \(lquser messages\(rq
 and other notes and tries to highlight them appropriately.
 .IP \(bu
+.SCITECO_TOPIC popup
 The auto-completion \fIpopup area\fP which is only shown when
 presenting the user with a choice of auto-completions.
 This area will overlap the \fIScintilla\fP and \fImessage
@@ -666,6 +723,7 @@ This is currently a single line of text that is scrolled
 automatically.
 .
 .SS Colors and Theming
+.SCITECO_TOPIC colors theming
 .
 \*(ST supports customizing its look predominantly by setting
 up the current Scintilla view using Scintilla messages
@@ -674,6 +732,7 @@ Most visual properties of the Scintilla view can be set
 via its styles.
 This is also how syntax highlighting (lexing) is set up.
 .LP
+.SCITECO_TOPIC STYLE_DEFAULT
 The \fBSTYLE_DEFAULT\fP (32) style defines the default foreground,
 background color, font etc. and is initialized to white on
 black with some monospaced font by \*(ST.
@@ -690,6 +749,7 @@ The command line area on the other hand will be styled with
 the original colors of \fBSTYLE_DEFAULT\fP and should look
 similar to the current Scintilla view.
 .LP
+.SCITECO_TOPIC STYLE_CALLTIP
 The \fBSTYLE_CALLTIP\fP (38) style is also accessed by
 \*(ST to style the \fIpopup area\fP and is initialized
 to black on (light) blue by \*(ST.
@@ -704,6 +764,7 @@ macro or \fBED\fP hook (for syntax highlighting).
 and lexer configurations for a wide range of languages.
 .
 .SS Gtk CSS Styling
+.SCITECO_TOPIC CSS
 .
 While the tools mentioned above are sufficient for
 Curses UIs, the Gtk+ 3 UI has many more styling possibilities.
@@ -717,15 +778,19 @@ Therefore \*(ST automatically exports the following Gtk
 CSS variables that can be referred to by user-provided
 CSS files:
 .TP
+.SCITECO_TOPIC @sciteco_default_fg_color
 .B @sciteco_default_fg_color
 The foreground color of Scintilla's \fBSTYLE_DEFAULT\fP.
 .TP
+.SCITECO_TOPIC @sciteco_default_bg_color
 .B @sciteco_default_bg_color
 The background color of Scintilla's \fBSTYLE_DEFAULT\fP.
 .TP
+.SCITECO_TOPIC @sciteco_calltip_fg_color
 .B @sciteco_calltip_fg_color
 The foreground color of Scintilla's \fBSTYLE_CALLTIP\fP.
 .TP
+.SCITECO_TOPIC @sciteco_calltip_bg_color
 .B @sciteco_calltip_bg_color
 The background color of Scintilla's \fBSTYLE_CALLTIP\fP.
 .LP
@@ -748,6 +813,7 @@ CSS theming.
 .
 .
 .SH ARITHMETICS AND EXPRESSIONS
+.SCITECO_TOPIC arithmetics expressions
 .
 \*(ST abstracts classic TECO's scheme of commands accepting at most
 two prefix arguments and returning at most one value for the next command
@@ -784,52 +850,66 @@ binary (bit by bit) negation for instance using the
 command.
 .
 .SS Operators
+.SCITECO_TOPIC operators
 .
 The following binary operators are supported with descending
 precedence, whereas borders separate operators of the \fIsame\fP
 precedence:
+.SCITECO_TT 90n
 .TS
 expand,box,tab(;);
 L LX.
 \fIbase\fB ^* \fIpower\fR;T{
+.SCITECO_TOPIC ^* power
 Raise \fIbase\fP to \fIpower\fP.
 T}
 =
 \fIa\fB ^/ \fIb\fR;T{
+.SCITECO_TOPIC ^/ remainder modulo
 Remainder of \fIa\fP divided by \fIb\fP.
 It is actually a modulo operation conforming to the
 host C compiler's modulo semantics.
 T}
 \fIa\fB / \fIb\fR;T{
+.SCITECO_TOPIC / divide slash
 Divide \fIa\fP by \fIb\fP.
 Naturally it is a division without remainder.
 T}
 \fIa\fB * \fIb\fP;T{
+.SCITECO_TOPIC * multiply asterisk
 Multiply \fIa\fP by \fIb\fP.
 T}
 =
 \fIa\fB - \fIb\fP;T{
+.SCITECO_TOPIC - subtract minus
 Subtract \fIb\fP from \fIa\fP.
 T}
 \fIa\fB + \fIb\fP;T{
+.SCITECO_TOPIC + add plus
 Add \fIb\fP to \fIa\fP.
 T}
 =
 \fIa\fB & \fIb\fP;T{
+.SCITECO_TOPIC & and ampersand
 Binary AND.
 T}
 =
 \fIa\fB ^# \fIb\fP;T{
+.SCITECO_TOPIC ^# xor
 Binary exclusive OR (XOR).
 T}
 =
 \fIa\fB # \fIb\fP;T{
+.SCITECO_TOPIC # or hash
 Binary OR.
 T}
 .TE
+.SCITECO_TT_END SP
 .LP
+.SCITECO_TOPIC associativity
 All binary operators are \fIleft-associative\fP, ie. associate
 from left to right, in \*(ST.
+.SCITECO_TOPIC ( ) brackets
 Round brackets may be used for grouping expressions to override
 operator precedence and associativity.
 For instance, since \(lq\fB^/\fP\(rq, \(lq\fB/\fP\(rq and \(lq\fB*\fP\(rq
@@ -851,6 +931,7 @@ dealing with braces.
 As the current behaviour has probably little benefits, the rules
 governing braces might be made stricter in a future release of \*(ST.
 .LP
+.SCITECO_TOPIC , comma barrier
 Another construct that may be used as an argument barrier to explicitly
 separate arguments is the comma (\(lq,\(rq).
 It is obligatory when trying to push a sequence of number constants
@@ -867,6 +948,7 @@ commands are used).
 The only unary operator currently supported is
 .RB \(lq - \(rq.
 The minus-operator is special and has unique semantics.
+.SCITECO_TOPIC prefix
 It sets the so called \fBprefix sign\fP which is 1 by default
 to -1.
 This prefix sign may be evaluated by commands \(em most often it is the
@@ -881,6 +963,7 @@ numbers the result is a negative number.
 .
 .
 .SH BUFFER RING
+.SCITECO_TOPIC ring
 .
 \*(ST organizes files to edit in the so called buffer ring.
 The ring is a circular list of buffers.
@@ -930,6 +1013,7 @@ or inserting characters by code, the code may be an Unicode
 codepoint instead of byte-sized integer.
 Currently however, \*(ST will only handle ASCII files.
 .LP
+.SCITECO_TOPIC "EOL translation"
 To simplify working with files using different end of line
 sequences (combinations of carriage return and line feed),
 \*(ST implements an \fIautomatic EOL translation\fP
@@ -959,7 +1043,9 @@ The feature is enabled by default but is controlled by bit 4
 of the \fBED\fP flag setting.
 It can be turned off by executing:
 .EX
+.SCITECO_TT
 16,0ED
+.SCITECO_TT_END
 .EE
 This may be beneficial when working with very large files \(em
 as the EOL translation imposes a performance penalty \(em
@@ -972,6 +1058,7 @@ For more details, please refer to this manual's command
 reference.
 .
 .SS Buffer Editing Hooks
+.SCITECO_TOPIC hooks
 .
 When opening or editing a file with the \fBEB\fP command
 or when closing a file with the \fBEF\fP command, you
@@ -983,7 +1070,9 @@ editing operations.
 Hooks are by default disabled.
 To enable them, set bit 5 in the \fBED\fP flags:
 .EX
+.SCITECO_TT
 0,32ED
+.SCITECO_TT_END
 .EE
 \*(ST will now execute the macro in global Q-Register \(lqED\(rq
 whenever a relevant operation is performed.
@@ -1068,6 +1157,7 @@ hooks (see
 .
 .
 .SH COMMAND SYNTAX
+.SCITECO_TOPIC syntax
 .
 \*(ST's command syntax is quite flexible and diverse but may be
 categorized into some base command types.
@@ -1108,27 +1198,34 @@ has been completely specified and updates to the string arguments
 are handled interactively.
 .
 .SS Modifiers
+.SCITECO_TOPIC modifiers
 .
 A command's behaviour or syntax may be influenced by so called
 modifiers written in front of commands.
 When specifying more than one modifier their order is insignificant.
 .LP
+.SCITECO_TOPIC : colon
 The colon (\fB:\fP) modifier usually prevents a command from
 failing and instructs it to return a condition (success/failure)
 boolean instead.
 .EX
+.SCITECO_TT
 1000:C=
+.SCITECO_TT_END
 .EE
 For instance if \(lq1000C\(rq would fail, \(lq1000:C\(rq will
 return 0 instead.
 .LP
+.SCITECO_TOPIC @ at
 The at (\fB@\fP) modifier allows the string termination character
 to be changed for individual commands.
 The alternative termination character must be specified just before
 the first string argument.
 For instance:
 .EX
+.SCITECO_TT
 @FS/foo/bar/
+.SCITECO_TT_END
 .EE
 Any character may be used as an alternative termination character.
 There is one special case, though.
@@ -1140,12 +1237,15 @@ be chosen.
 This feature is especially useful for embedding TECO code in
 string arguments, as in:
 .EX
+.SCITECO_TT
 @^Um{
   @FS{foo}/bar/
 }
+.SCITECO_TT_END
 .EE
 .
 .SH Q-REGISTERS
+.SCITECO_TOPIC Q-Register
 .
 \*(ST may store data in so called Q-Registers.
 Each Q-Register cell has an integer and string part (can store
@@ -1187,6 +1287,7 @@ Some of the registers with special significance are initialized
 by \*(ST while others must be manually defined.
 The following list is an overview of all special global registers:
 .TP 2
+.SCITECO_TOPIC "search condition"
 .BR _ " (underscore)"
 Search string and search condition register.
 Also used by the globbing command \fBEN\fP, so it is also
@@ -1198,6 +1299,7 @@ Replacement string register.
 Its integer part is currently unused.
 It is initialized automatically on startup.
 .TP
+.SCITECO_TOPIC filename
 .BR * " (asterisk)"
 File name (string part) and id (numeric part) of current
 buffer in ring.
@@ -1221,10 +1323,13 @@ buffer with \(lq-%*\fB$\fP\(rq, changing to the next
 buffer with \(lq%*\fB$\fP\(rq and changing the current buffer
 temporarily:
 .EX
+.SCITECO_TT
 [* ! ...change current buffer... ! ]*
+.SCITECO_TT_END
 .EE
 The register is initialized automatically on startup.
 .TP
+.SCITECO_TOPIC "working directory"
 .BR $ " (dollar)"
 The process' current working directory (string part).
 Its numeric part is currently unused.
@@ -1237,7 +1342,9 @@ directory in a manner similar to the \fBFG\fP command.
 This allows you to change the current directory temporarily
 with the following idiom:
 .EX
+.SCITECO_TT
 [$ ! ...change current directory... ! ]$
+.SCITECO_TT_END
 .EE
 As with \fBFG\fP, relative directories may be specified
 but querying \(lq$\(rq will still return an absolute path.
@@ -1267,6 +1374,7 @@ Their numeric parts are currently unused.
 The mechanisms involved are documented more elaborately in
 .BR sciteco (1).
 .TP
+.SCITECO_TOPIC ~ clipboard
 .BI ~ clipboard
 These registers constitute \*(ST's support for system clipboards.
 Clipboard support is highly UI-specific, so different
@@ -1277,6 +1385,7 @@ every available clipboard either on startup or only when
 entering interactive mode.
 The register \(lq~\(rq refers to the default clipboard which
 will always exist if clipboards are supported.
+.SCITECO_TOPIC ~P ~S ~C
 Other commonly used clipboard registers are \(lq~P\(rq for the
 primary selection, \(lq~S\(rq for the secondary selection and
 \(lq~C\(rq for the clipboard selection.
@@ -1284,6 +1393,7 @@ 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
+.SCITECO_TOPIC xterm
 \*(ST does \fBnot\fP generally support clipboards on ncurses,
 but has special support when used with a sufficiently recent version
 of \fBxterm\fP(1).
@@ -1293,6 +1403,7 @@ automatically, users will have to set the flag 256 of the
 the \fISetSelection\fP and \fIGetSelection\fP window operations.
 \*(ST will still check whether XTerm is actually used in
 a particular session.
+.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.
@@ -1373,6 +1484,7 @@ For instance the specifications \(lqa\(rq and \(lqA\(rq
 are equivalent to \(lq[A]\(rq.
 .
 .SS Push-Down List
+.SCITECO_TOPIC "push down" stack
 .
 Another data structure supported by \*(ST is the Q-Register
 push-down list.
@@ -1387,11 +1499,14 @@ commands.
 For instance to search in a macro without overwriting the
 contents of the search register you could write:
 .EX
+.SCITECO_TT
 [_ Sfoo$ ]_
+.SCITECO_TT_END
 .EE
 .
 .
 .SH STRING-BUILDING CHARACTERS
+.SCITECO_TOPIC "string building"
 .
 As alluded to earlier \*(ST supports special characters in
 command string arguments and long Q-Register names.
@@ -1426,6 +1541,7 @@ 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 ^Qc ^Rc quote
 .BI ^Q c
 .TQ
 .BI ^R c
@@ -1433,6 +1549,7 @@ Escape character \fIc\fP.
 The character is not handled as a string building character,
 so for instance \(lq^Q^Q\(rq translates to \(lq^Q\(rq.
 .TP
+.SCITECO_TOPIC ^V^V ^Vc lower
 .B ^V^V
 .TQ
 .BI ^V c
@@ -1440,11 +1557,13 @@ Translates all following characters into lower case.
 When \fB^V\fP is not followed by \fB^V\fP, a single character
 \fIc\fP is lower-cased.
 .TP
+.SCITECO_TOPIC ^W^W ^Wc
 .B ^W^W
 .TQ
 .BI ^W c
 Analogous to \fB^V\fP, but upper-cases characters.
 .TP
+.SCITECO_TOPIC ^E\\ ^E\\q
 .BI ^E\(rs q
 Expands to the formatted number stored in the
 numeric part of Q-Register \fIq\fP.
@@ -1455,16 +1574,19 @@ Currently, long Q-Register names have a separate independant
 level of string building character processing, allowing you
 to build Q-Register names whose content is then expanded.
 .TP
+.SCITECO_TOPIC ^EU ^EUq
 .BI ^EU q
 Expands to the character whose code is stored in the numeric
 part of Q-Register \fIq\fP.
 For instance if register \(lqA\(rq contains the code 66,
 \(lq^EUa\(rq expands to the character \(lqB\(rq.
 .TP
+.SCITECO_TOPIC ^EQ ^EQq
 .BI ^EQ q
 Expands to the string contents of the Q-Register specified by
 \fIq\fP.
 .TP
+.SCITECO_TOPIC ^E@ ^E@q
 .BI ^E@ q
 Expands to the shell-quoted string contents of the Q-Register
 specified by \fIq\fP.
@@ -1475,6 +1597,7 @@ This is useful when generating UNIX shell code or when passing
 registers with unknown contents as parameters to external
 commands using the \fBEC\fP command.
 .TP
+.SCITECO_TOPIC ^EN ^ENq
 .BI ^EN q
 Expands to the string contents of the Q-Register specified
 by \fIq\fP but with glob pattern wildcards escaped.
@@ -1491,6 +1614,7 @@ be escaped.
 .
 .
 .SH PATTERN MATCH CHARACTERS
+.SCITECO_TOPIC pattern
 .
 \*(ST's search and replace commands allow the use of wildcards
 for pattern matching.
@@ -1506,38 +1630,47 @@ The following pattern match constructs are supported for matching
 one character in different character classes
 (caret-notations refer to the corresponding control characters):
 .TP
+.SCITECO_TOPIC ^S ^EB
 .B ^S
 .TQ
 .B ^EB
 Matches all non-alpha-numeric characters.
 .TP
+.SCITECO_TOPIC ^EA
 .B ^EA
 Matches all alphabetic characters.
 .TP
+.SCITECO_TOPIC ^EC
 .B ^EC
 Matches all symbol constituents.
 These are currently defined as alpha-numeric characters,
 dot (.) and dollar ($) signs.
 .TP
+.SCITECO_TOPIC ^ED
 .B ^ED
 Matches all digits.
 .TP
+.SCITECO_TOPIC ^EG ^EGq
 .BI ^EG q
 Matches all characters in the string of the Q-Register
 specified by \fIq\fP, i.e. one of the characters in
 the register.
 .TP
+.SCITECO_TOPIC ^EL
 .B ^EL
 Matches all line break characters.
 These are defined as carriage return, line-feed, vertial tab and
 form feed.
 .TP
+.SCITECO_TOPIC ^ER
 .B ^ER
 Matches all alpha-numeric characters.
 .TP
+.SCITECO_TOPIC ^EV
 .B ^EV
 Matches all lower-case alphabetic characters.
 .TP
+.SCITECO_TOPIC ^EW
 .B ^EW
 Matches all upper-case alphabetic characters.
 .TP
@@ -1548,24 +1681,29 @@ contains only the character itself.
 The following additional pattern match constructs are supported
 (caret-notations refer to the corresponding control characters):
 .TP
+.SCITECO_TOPIC ^X ^EX
 .B ^X
 .TQ
 .B ^EX
 Matches any character.
 .TP
+.SCITECO_TOPIC ^N
 .BI ^N class
 Matches any character \fBnot\fP in \fIclass\fP.
 All constructs listed above for matching classes may be used.
 .TP
+.SCITECO_TOPIC ^EM
 .BI ^EM pattern
 Matches many occurrences (at least one) of \fIpattern\fP.
 Any pattern match construct and non-magic character may be used.
 .TP
+.SCITECO_TOPIC ^ES
 .B ^ES
 Matches any sequence of whitespace characters (at least one).
 Whitespace characters are defined as line-break characters,
 the space and horizontal tab characters.
 .TP
+.SCITECO_TOPIC ^E[
 .BI ^E[ pattern1 , pattern2 , ... ]
 Matches one in a list of patterns.
 Any pattern match construct may be used.
@@ -1639,6 +1777,7 @@ These are documented in the section
 .BR "COMMANDLINE EDITING" .
 .
 .SS Glob Patterns
+.SCITECO_TOPIC glob
 .
 Some commands accept glob patterns
 in their file name arguments to perform pattern matching
@@ -1685,6 +1824,7 @@ wildcards.
 .
 .
 .SH FLOW CONTROL
+.SCITECO_TOPIC flow
 .
 \*(ST is a structured imperative language.
 Commands are executed from left to right.
@@ -1718,6 +1858,7 @@ the program counter and influencing parsing, it is described in this
 document's command reference.
 \*(ST may do simple unconditional and computed gotos.
 .LP
+.SCITECO_TOPIC label
 Labels are symbolic and are defined with the following syntax:
 .br
 .BI ! label !
@@ -1731,10 +1872,12 @@ Therefore every macro invocation has its own label namespace and gotos
 to a label have constant complexity once a label has been parsed.
 Terminating a macro execution (or command line) fails if a label that
 is jumped to has not been defined.
+.SCITECO_TOPIC comment
 Labels also have another important role in \*(ST \(em they are used
 as comments.
 .
 .SS Loops
+.SCITECO_TOPIC < > loop
 .
 Gotos may be used for looping, but \*(ST also supports a dedicated
 structured looping construct.
@@ -1774,16 +1917,20 @@ infinite one.
 Additionally \*(ST supports special colon-modified forms
 of the loop start and end commands for processing the
 argument stack dynamically.
+.SCITECO_TOPIC :>
 The \fB:>\fP loop end command will \fInot\fP pop values left
 on the stack since the beginning of the loop and can be used
 to aggregate stack values.
 For instance, the following command will leave the numbers
 1 to 5 on the expression stack:
 .EX
+.SCITECO_TT
 0Ua 5<%a:>
+.SCITECO_TT_END
 .EE
 The command can be understood as an aggregated form of the
 expression \(lq(%a,%a,%a,%a,%a)\(rq.
+.SCITECO_TOPIC :<
 Consequently, the colon-modified loop start command will
 \fInot\fP represent an argument barrier and the corresponding
 loop end command will not discard any values which is useful
@@ -1791,7 +1938,9 @@ for looping over the contents of the stack.
 E.g. the following command will print the numbers 1 to 5
 (actually every additional number argument):
 .EX
+.SCITECO_TT
 1,2,3,4,5,-1:<"~1;'=>
+.SCITECO_TT_END
 .EE
 If the loop start is colon-modified, the colon in front
 of the loop end command is ignored if present.
@@ -1801,6 +1950,9 @@ may be used in loops like \fBF<\fP and \fBF>\fP.
 They are described in the reference section of this manual.
 .
 .SS Conditionals
+.\" NOTE: Two quoted double-quotes are necessary to escape
+.\" a single double quote in macro arguments
+.SCITECO_TOPIC """" conditional if then else
 .
 Last but not least, \*(ST supports so called conditionals.
 They correspond to structured IF-THEN-ELSE statements
@@ -1826,6 +1978,7 @@ The possible conditions are defined in the following list.
 Unless \fIn\fP is defined optional, the conditionals described
 below yield an error if \fIn\fP is omitted:
 .TP
+.SCITECO_TOPIC """~"
 \# [n]"~
 [\fIn\fP]\fB\(dq~\fP
 Applies if \fIn\fP is \fBnot\fP given (i.e. the argument
@@ -1837,23 +1990,29 @@ parameter values.
 For instance the following macro inserts \fIn\fP tab characters
 (one by default):
 .EX
+.SCITECO_TT
 @^Ut{
   "~1'<9@I//>
 }
+.SCITECO_TT_END
 .EE
 .TP
+.SCITECO_TOPIC """A"
 .IB n \(dqA
 Applies if \fIn\fP is the code of an alphabetic character.
 .TP
+.SCITECO_TOPIC """C"
 .IB n \(dqC
 Applies if \fIn\fP is the code of a symbol constituent.
 Like in pattern matching, a symbol constituent is defined
 as an alpha-numeric character, dot, dollar or underscore.
 .TP
+.SCITECO_TOPIC """D"
 .IB n \(dqD
 Applies if \fIn\fP is the code of a digit character (0 to 9).
 The current radix is insignificant.
 .TP
+.SCITECO_TOPIC """I"
 .IB n \(dqI
 Applies if \fIn\fP is the code of a directory separator
 (e.g. \(lq/\(rq on UNIX, \(lq\\\(rq or \(lq/\(rq on Windows).
@@ -1865,6 +2024,7 @@ in portable macros.
 This is not the case, for instance when working with environment
 registers.
 .TP
+.SCITECO_TOPIC """S" """T"
 .IB n \(dqS
 .TQ
 .IB n \(dqT
@@ -1873,6 +2033,7 @@ success (or truth).
 Therefore it is equivalent to a check for less than
 zero (negative).
 .TP
+.SCITECO_TOPIC """F" """U"
 .IB n \(dqF
 .TQ
 .IB n \(dqU
@@ -1881,6 +2042,7 @@ failure (or falsehood).
 Therefore it is equivalent to a check for greater than
 or equal to zero (non-negative).
 .TP
+.SCITECO_TOPIC """E" """="
 .IB n \(dqE
 .TQ
 .IB n \(dq=
@@ -1890,6 +2052,7 @@ To check two values \fIa\fP and \fIb\fP for equality you
 will commonly write:
 .IB a - b \(dq=
 .TP
+.SCITECO_TOPIC """G" """>"
 .IB n \(dqG
 .TQ
 .IB n \(dq>
@@ -1899,6 +2062,7 @@ To check if a value \fIa\fP is greater than a value \fIb\fP you
 will commonly write:
 .IB a - b \(dq>
 .TP
+.SCITECO_TOPIC """L" """<"
 .IB n \(dqL
 .TQ
 .IB n \(dq<
@@ -1908,6 +2072,7 @@ To check if a value \fIa\fP is less than a value \fIb\fP you
 will commonly write:
 .IB a - b \(dq<
 .TP
+.SCITECO_TOPIC """N"
 .IB n \(dqN
 Applies if \fIn\fP is not zero.
 .br
@@ -1915,13 +2080,16 @@ To check two values \fIa\fP and \fIb\fP for inequality you
 will commonly write:
 .IB a - b \(dqN
 .TP
+.SCITECO_TOPIC """R"
 .IB n \(dqR
 Applies if \fIn\fP is the code of an alpha-numeric character.
 .TP
+.SCITECO_TOPIC """V"
 .IB n \(dqV
 Applies if \fIn\fP is the code of a lower-case alphabetic
 character.
 .TP
+.SCITECO_TOPIC """W"
 .IB n \(dqW
 Applies if \fIn\fP is the code of a upper-case alphabetic
 character.
@@ -1934,6 +2102,7 @@ loops in conditional blocks.
 .
 .
 .SH COMMAND REFERENCE
+.SCITECO_TOPIC reference
 .
 This section documents all of the commands supported by
 \*(ST.
diff --git a/doc/sciteco.tmac b/doc/sciteco.tmac
new file mode 100644
index 0000000..7613c6e
--- /dev/null
+++ b/doc/sciteco.tmac
@@ -0,0 +1,65 @@
+.\" sciteco.tmac
+.\"
+.\" grosciteco is similar to grotty, so we can
+.\" inherit its definitions:
+.nroff
+.do mso tty.tmac
+.
+.\"
+.\" Define topics at the current document position.
+.\" This is handled by grosciteco to create a topic index
+.\" at the top of the file which is in turn read by SciTECO
+.\" to build a global help topic index.
+.\"
+.\" NOTE: We let Troff handle the argument processing, since
+.\" parsing them in SciTECO would be tricky.
+.\"
+.de SCITECO_TOPIC
+.  while \\n(.$ \{\
+.    device sciteco_topic:\\$1
+.    shift 1
+.  \}
+..
+.
+.
+.\"
+.\" grosciteco does not handle font families right now
+.\" and probably will never do because of the limited
+.\" number of Scintilla styles available.
+.\" But even if we did, we sometimes have to enforce
+.\" a fixed-width font for drawings and tables, since
+.\" they can only be "typeset" with glyphs by Scintilla.
+.\"
+.de SCITECO_TT
+.  if \\n(.$ .ll \\$*
+.  device sciteco_tt
+..
+.
+.de SCITECO_TT_END
+.  if '\\$1'SP' .sp
+.  device sciteco_tt_end
+.  ll 65535n
+..
+.
+.\"
+.\" Effectively disable paragraph filling in man pages.
+.\" Word wrapping will be performed by Scintilla.
+.\"
+.ll 65535n
+.nr LT 90n
+.
+.\"
+.\" remove hyphenation
+.\"
+.nh
+.nr HY 0
+.
+.de hy
+..
+.de nh
+..
+.
+.\" avoid line breaks after hyphen-like characters.
+.cflags 0 -\[hy]\[em]\[en]
+.
+.\" end of file, make sure this is the last line
\ No newline at end of file