the manual generator (generator-docs.tes) has been cleaned up and is now called tedoc.tes

 * some code simplifications
 * it now supports command line arguments via getopt.tes.
 * the -C flag enabled C/C++ mode.
   By default tedoc parses SciTECO code which means it can be used
   to document macro packages as well.
 * Therefore it is installed as a separate tool now.
   It may be used as a Groff preprocessor for third-party macro
   authors to generate (wo)man pages.
 * there's a man page tedoc.tes(1)
 * The troff placeholder macro is now called ".TEDOC".
 * Help topics can now be specified after the starting comment /*$ or !*$.
   Topics have been defined for all built-in commands.

7 files changed, 297 insertions, 167 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index fed0ebb..97619b2 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -2,10 +2,21 @@
 # substitutor is available.
 include $(top_srcdir)/bootstrap.am
 
+# tedoc is a code documentation tool for SciTECO commands
+# and macros, extracting comments from SciTECO and C/C++
+# code.
+# It generates Troff manpage markup and acts as a Troff
+# preprocessor to manpage templates.
+dist_bin_SCRIPTS = tedoc.tes
+
+%.in : %.template tedoc.tes $(SOURCES)
+	$(SCITECO_FULL) -m -- @srcdir@/tedoc.tes \
+	                -C $@ $< $(SOURCES)
+
 # grosciteco is a troff postprocessor similar to grotty
 # which can be used to produce SciTECO-friendly output
 # (woman pages).
-dist_bin_SCRIPTS = grosciteco.tes
+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
@@ -16,18 +27,23 @@ dist_bin_SCRIPTS = grosciteco.tes
 # 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.
+# 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.
 install-exec-hook:
-	@SED@ -i "1s,#!.*sciteco,#!$(bindir)/`echo sciteco | @SED@ '$(transform)'`$(EXEEXT)," \
-	         $(DESTDIR)$(bindir)/grosciteco.tes
+	for script in $(DESTDIR)$(bindir)/*.tes; do \
+		@SED@ -i "1s,#!.*sciteco,#!$(libexecdir)/`echo sciteco-wrapper | @SED@ '$(transform)'`$(EXEEXT)," \
+		      $$script; \
+	done
 
 womendir = $(scitecolibdir)/women
 
 women_DATA = grosciteco.tes.1.woman grosciteco.tes.1.woman.tec
 CLEANFILES = grosciteco.tes.1.intermediate
 
+women_DATA += tedoc.tes.1.woman tedoc.tes.1.woman.tec
+CLEANFILES += tedoc.tes.1.intermediate
+
 women_DATA += sciteco.1.woman sciteco.1.woman.tec
 CLEANFILES += sciteco.1.intermediate
 
@@ -49,6 +65,9 @@ CLEANFILES += $(women_DATA)
 man_MANS = grosciteco.tes.1
 EXTRA_DIST = grosciteco.tes.1.in
 
+man_MANS += tedoc.tes.1
+EXTRA_DIST += tedoc.tes.1.in
+
 man_MANS += sciteco.1
 EXTRA_DIST += sciteco.1.in
 
@@ -59,21 +78,18 @@ SOURCES = $(wildcard @top_srcdir@/src/*.cpp)
 
 CLEANFILES += $(man_MANS)
 
-dist_noinst_SCRIPTS = generate-docs.tes htbl.tes
-
-%.in : %.template generate-docs.tes $(SOURCES)
-	$(SCITECO_FULL) -m @srcdir@/generate-docs.tes \
-	                $@ $< $(SOURCES)
+dist_noinst_SCRIPTS = htbl.tes
 
 if BUILD_HTMLMAN
-html_DATA = grosciteco.1.html sciteco.1.html sciteco.7.html
+html_DATA = grosciteco.tes.1.html tedoc.tes.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
-	$(SCITECO_FULL) -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
deleted file mode 100755
index ee4820c..0000000
--- a/doc/generate-docs.tes
+++ /dev/null
@@ -1,153 +0,0 @@
-#!/usr/bin/sciteco -m
-! ./generate-docs.tes <output> <input> <sources> !
-
-!
-  Preprocess a manpage template, inserting a SciTECO command reference.
-
-  The .COMMANDS request is replaced with Troff markup generated from code
-  comments in <sources>.
-
-  The comments support a small but powerful markup for documenting
-  TECO commands:
-   * comments start with /*$
-   * all lines until first empty line are command syntax descriptions
-     * text followed by "--" is a short description
-     * variable values and characters of syntactic significance should be
-       detected automatically
-     * alternatives are denoted by "|"
-     * every line is an alternative
-     * return values may be specified after "->"
-   * the remaining text is the verbose command description
-     * <name> denotes a variable from the syntax description
-     * empty lines introduce paragraphs
-     * lines beginning with "-" are unordered lists
-     * lines beginning with numbers and dot ("1.", "2.", etc.) are
-       ordered lists
-     * the above transformations are only preprocessing, so that
-       Troff requests, escapes and tman macros may also be used.
-!
-
-@[format_header]{
-  fd--S .U.f :L"S.|Z'U.t Q.f,Q.tXa Q.f,Q.tD I
-
-  ebQ#tm I\# GENERATED FROM Q.#sc (\.#sc):
-.SS Qa -a-10"N I
- ' eq.[header]
-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
-.RI [ Qa ]
->
-j<fr->\(->;>
-j<sMCM[|MC];.u.t <-a"C|-a-|"N1;''r> .,q.txa .,q.td eqa<fr| | ;> eq.[header]i
-.IR Qa
->
-j<frS
-
-;>j<fr
-S
-;>j<fs
-
-
-;>
-j 0a-10"=d'
-zj-a-10"=-d'
-  ebQ#tm g.[header]i
-.
-
-}
-
-@[format_body]{
-  i.LP
-<fr
-
-
-.
-.LP
-;>
-  j<fs
--S
-.IP \(bu 4
-;>j<s
-MD.S; 0L I.IP  FSS 4
->
-  ! set margin for list paragraphs !
-  j 0U.n<
-    Z-.-3"<1;'
-    .,.+3:S.LP"S Q.n">0L I.RE
- 0U.n' | .,.+3:S.IP"S Q.n"=0L I.RS
- %.n' ' '
-    :L;
-  > Q.n"> ZJ I
-.RE '
-  j<s<MC>;-di
--s<-di
-.I >
-  j<frS
-
-;>j<fr
-S
-;>
-  ebQ#tm g.ci
-.
-.
-
-}
-
-! process command-line options !
-LR 0X#ou 2LR 0X#tm EBQ#tm EB L
-[.f
-  <:L;R 0X.f EBQ.f EB L>
-].f
--EF
-
-I\#
-\# AUTOGENERATED FROM Q#tm
-\# DO NOT EDIT MANUALLY!!!
-\#
-
-
-! find insertion point !
-FS
-.COMMANDS
-
-
-
-<
-<
-  ! extract comment !
-  2EB EQ* HX.#sc 2EB
-  s/*$; .-3u.#sc s*/ q.#sc+3,.-2x.ceq.c
-  ! q.#sc= !
-  <fs
-
-
-;>
-  j<fs
-[S,]*[M[ ,	],]
-;>
-  j<0a-13"=df>'0a-10"=df>'0a- "=df>'0a-	"=df>';>
-  zj<-a-13"=-df>'-a-10"=-df>'-a- "=-df>'-a-	"=-df>';>
-
-  ! extract header !
-  h:fd
-
-"Fzj'0,.x.[header]0,.d
-
-  eq.[header]
-  :M[format_header]
-  eq.c
-  :M[format_body]
->
-EF
-Q*-1"=1;'
->
-
-EWQ#ou
-EX
diff --git a/doc/grosciteco.tes.1.in b/doc/grosciteco.tes.1.in
index 0aac8dc..3e21f8a 100644
--- a/doc/grosciteco.tes.1.in
+++ b/doc/grosciteco.tes.1.in
@@ -186,6 +186,9 @@ to make the files accessible in \*(ST's online-help system.
 Language reference including additional information on the \fB?\fP command:
 .BR sciteco (7)
 .TP
+A documentation tool generating man-page markup:
+.BR tedoc.tes (1)
+.TP
 The \fBGNU roff\fP front end program:
 .BR groff (1)
 .TP
diff --git a/doc/sciteco.1.in b/doc/sciteco.1.in
index ed3892f..ead8337 100644
--- a/doc/sciteco.1.in
+++ b/doc/sciteco.1.in
@@ -402,7 +402,11 @@ Language reference:
 .TP
 The \fBtroff\fP post-processor for \*(ST, including
 information on how to write \(lqwomanpages\(rq:
-.BR grosciteco (1)
+.BR grosciteco.tes (1)
+.TP
+A \fBtroff\fP pre-processor commonly used to generate
+man-pages:
+.BR tedoc.tes (1)
 .TP
 Homepage:
 .UR @PACKAGE_URL@
diff --git a/doc/sciteco.7.template b/doc/sciteco.7.template
index f3f5b48..9ce5bf8 100644
--- a/doc/sciteco.7.template
+++ b/doc/sciteco.7.template
@@ -2135,7 +2135,8 @@ by \*(ST.
 .LP
 The same conventions are used elsewhere in this manual.
 .
-.COMMANDS
+.\" Expanded with the command reference:
+.TEDOC
 .
 .
 .SH COMPATIBILITY
diff --git a/doc/tedoc.tes b/doc/tedoc.tes
new file mode 100755
index 0000000..623be3a
--- /dev/null
+++ b/doc/tedoc.tes
@@ -0,0 +1,129 @@
+#!/usr/local/bin/sciteco -m
+!* tedoc.tes [-C] [--] <output> <input> <sources> *!
+
+:EMQ[$SCITECOPATH]/getopt.tes
+
+@[format_header]{
+  FD--S .U.f :L"S.|Z'U.t Q.f,Q.tXa Q.f,Q.tD I^J
+
+  EBQ#tm
+  I\# GENERATED FROM Q.#sc (\.#sc):^J
+  I.SS  Ga -A-10"N I^J '
+  :Q.[topics]">
+    I.SCITECO_TOPIC  G.[topics]
+  '
+
+  EQ.[header]
+  J <FR^J^J.br^J;>
+  J <
+    SMA; .U.t
+    1Ua <."=1;' -A"A|1;' -A"V -1Ua 1;' R>
+    Qa"S
+      Q.tJ
+    |
+      .,Q.tXa .,Q.tD
+      I^J.B Qa^J
+    '
+  >
+  J <
+    S[MC]; .U.t -S[ .,Q.t-1Xa .-1,Q.tD
+    I^J.RI [ Qa ]^J
+  >
+  J <FR->\(->;>
+  J <
+    SMCM[|MC];
+    .U.t <-A"C|-A-|"N1;'' R>
+    .,Q.tXa .,Q.tD EQa
+    <FR| | ;>
+    EQ.[header]
+    I^J.IR Qa^J
+  >
+  J <FRS^J^J;>
+  J <FR^JS^J;>
+  J <FR^J^J^J;>
+  J 0A-10"=D'
+  ZJ -A-10"=-D'
+  EBQ#tm
+  G.[header]
+  I^J.^J
+}
+
+@[format_body]{
+  I.LP^J
+  <FR^J^J^J.^J.LP^J;>
+  J <FS^J-S^J.IP \(bu 4^J;>
+  J <S^JMD.S; 0L I.IP  FSS 4^J>
+  !* set margin for list paragraphs *!
+  J 0U.n <
+    Z-.-3"<1;'
+    .,.+3:S.LP"S
+      Q.n">
+        0L I.RE^J 0U.n
+      '
+    |
+      .,.+3:S.IP"S
+        Q.n"=0L I.RS^J %.n '
+      '
+    '
+    :L;
+  >
+  Q.n"> ZJ I^J.RE '
+  J <S<MC>; -D I^J -S< -D I^J.I >
+  J <FRS^J^J;>
+  J <FR^JS^J;>
+  EBN#tm
+  G.c I^J.^J.^J
+}
+
+!* process command-line options *!
+[optstring]C M[getopt]"F (0/0) '
+: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
+
+I\#
+\# AUTOGENERATED FROM Q#tm
+\# DO NOT EDIT MANUALLY!!!
+\#^J
+
+!* find insertion point *!
+FS^J.TEDOC^J^J
+
+EJ-1<
+  <
+    2U* EU.#scQ*
+
+    !* extract comment *!
+    SQ[comment.start]$;
+    .-:Q[comment.start]-1U.#sc
+    SQ[comment.end]
+    Q.#sc+:Q[comment.start]+1,.-:Q[comment.end]X.c
+    EQ.c
+    <FS^J^J  ^J  ;>
+    J <FS^J[S,]*[M[ ,	],]^J;>
+    J 0A-10"N X.[topics] K '
+    <0A-10"N 0A- "N 0A-9"N 1; ' ' ' D>
+    ZJ <-A-10"N -A- "N -A-9"N 1; ' ' ' -D>
+
+    !* extract header *!
+    H:FD^J^J"F ZJ '
+    0,.X.[header] 0,.D
+
+    EQ.[header]
+    :M[format_header]
+    EQ.c
+    :M[format_body]
+  >
+  EF
+>
+
+EWQ#ou
+EX
diff --git a/doc/tedoc.tes.1.in b/doc/tedoc.tes.1.in
new file mode 100644
index 0000000..77b67d1
--- /dev/null
+++ b/doc/tedoc.tes.1.in
@@ -0,0 +1,130 @@
+.ds ST \\fB@PACKAGE_NAME@\\fP
+.
+.
+.TH "tedoc.tes" 1 \
+    "@DATE@" \
+    "@PACKAGE_NAME@ Version @PACKAGE_VERSION@"
+.
+.
+.SCITECO_TOPIC tedoc tedoc.tes
+.SH NAME
+tedoc \-\-
+Source code documentation tool for \*(ST
+.
+.
+.SH SYNOPSIS
+.
+.SY tedoc.tes
+.OP "-C"
+.OP "--"
+.I output
+.I template
+.I sources...
+.YS
+.
+.
+.SH DESCRIPTION
+.
+.
+\fBtedoc\fP is a tool for extracting documentation from \*(ST macros
+and C/C++ code.
+It is used to document \*(ST's internal commands as well as macro
+packages.
+.SCITECO_TOPIC .TEDOC
+It processes special \*(ST comment blocks from the \fIsources\fP,
+generating \fBtroff\fP man-page markup and inserts them into
+a man-page \fItemplate\fP at the position of the \fBTEDOC\fP
+pseudo-request.
+The result is written to an \fIoutput\fP file.
+\fBtedoc\fP can thus be understood as a \fBtroff\fP preprocessor.
+.
+.SH OPTIONS
+.
+.IP "\fB-C\fP"
+Instruct \fBtedoc\fP to extract C/C++ comments instead of
+\*(ST comments.
+The C comments begin with \(lq/*$\(rq and end with \(lq*/\(rq.
+The \*(ST comments in contrast begin with \(lq!*$\(rq and end
+with \(lq*!\(rq.
+.IP "\fIoutput\fP"
+The resulting man-page file.
+.IP "\fItemplate\fP"
+A man-page template, i.e. a man-page with the \fBTEDOC\fP
+request.
+.IP "\fIsources...\fP"
+An arbitrary number of source code files to scan through.
+The comments are extracted in document order, ie. from the
+first comment in the first source file to the last comment
+in the last source file specified.
+.
+.
+.SH TEDOC COMMENTS
+.\" FIXME: !*$ cannot be indexed since it terminates the
+.\" header comment in *.woman.tec files.
+.SCITECO_TOPIC "/*$"
+.
+The \fBtedoc\fP source code comments support a small but powerful
+semantic markup for documenting \*(ST commands and macros:
+.IP \(bu 4
+Comments start with \(lq!*$\(rq (or \(lq/*$\(rq in C/C++ mode).
+.IP \(bu
+The first line (immediately after the starting comment) may
+contain \fItopic\fP keywords for \*(ST's online help system that
+will point to the beginning of the section generated for this
+\fBtedoc\fP comment.
+This generates \fBSCITECO_TOPIC\fP macro calls defined
+in \fBsciteco.tmac\fP (see \fBgrosciteco.tes\fP(1).
+.IP \(bu
+All lines until first empty line are syntax descriptions.
+.IP \(bu
+Text followed by \(lq--\(rq is a short description.
+.IP \(bu
+Variable values and characters of syntactic significance should be
+detected automatically.
+.IP \(bu
+Alternatives are denoted by \(lq|\(rq.
+.IP \(bu
+Every line is an alternative (e.g. different calling forms of the
+same command or macro).
+.IP \(bu
+Return values may be specified after \(lq->\(rq.
+.IP \(bu
+The remaining text is the verbose command description.
+.RS
+.  IP \(bu
+\(lq<name>\(rq denotes a variable from the syntax description.
+.  IP \(bu
+Empty lines introduce paragraphs.
+.  IP \(bu
+Lines beginning with \(lq-\(rq are unordered lists.
+.  IP \(bu
+Lines beginning with numbers and dot (\(lq1.\(rq, \(lq2.\(rq, etc.) are
+ordered lists.
+.  IP \(bu
+These transformations are only preprocessing, so that
+\fBtroff\fP requests, macros and escapes may also be used freely.
+.RE
+.
+.
+.SH SEE ALSO
+.
+.TP
+\*(ST invocation and help on its environment variables:
+.BR sciteco (1)
+.TP
+A \fBGNU roff\fP post-processor for rendering \fBtroff\fP
+markup into \(lqwomanpages\(rq for \*(ST's online help system
+\(em also documents special \fBtroff\fP macros in \fBsciteco.tmac\fP:
+.BR grosciteco.tes (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