first draft of TECO command documentation generator

 * the language reference is a manually written man-page template
 * containing special references for generated documentation (\#$...)
 * SciTECO script generate-docs.tes extracts TECO comments (/*$ ... */)
   from all source files and transforms them to Troff requests that are
   inserted into the document template.
 * TECO doc comments are a rather sophisticated markup:
   * first part until empty line is called header: simplified command syntax descriptions
   * the rest is called body: <identifier> is automatically underlined,
     empty lines generate new paragraphs, lines beginning with "-" or numbers
     denote an indented unordered or numbered list item.
   * regular Troff requests/macros can be used for more sophisticated markup
   * since Autoconf substitutions are performed on the generated man-page,
     @VARIABLEs@ may be used in doc comments as well

4 files changed, 150 insertions, 1 deletions

diff --git a/.gitignore b/.gitignore
index 3e71041..ccbc6d6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,7 +22,8 @@ stamp-*
 /src/sciteco-minimal
 
 # Generated code
-/doc/sciteco.1
+/doc/sciteco.[17]
+/doc/sciteco.7.in
 /doc/Doxyfile
 /doc/doxygen
 
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 48ab9b8..7ed5a5c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -4,6 +4,17 @@ man_MANS = sciteco.1
 EXTRA_DIST = sciteco.1.in
 CLEANFILES = sciteco.1
 
+man_MANS += sciteco.7
+EXTRA_DIST += sciteco.7.template
+CLEANFILES += sciteco.7 sciteco.7.in
+SOURCES = $(wildcard @top_srcdir@/src/*.cpp)
+
+EXTRA_DIST += generate-docs.tes
+
+%.in : %.template generate-docs.tes $(SOURCES)
+	$(BOOTSTRAP_SCITECO) -m @srcdir@/generate-docs.tes \
+			     $@ $< $(SOURCES)
+
 #
 # Doxygen processing (do not install or distribute)
 #
diff --git a/doc/generate-docs.tes b/doc/generate-docs.tes
new file mode 100755
index 0000000..93b0e9d
--- /dev/null
+++ b/doc/generate-docs.tes
@@ -0,0 +1,125 @@
+#!/usr/bin/sciteco -m
+
+@{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 ( Q.#sc\ I):
+.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
+.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/sciteco.7.template b/doc/sciteco.7.template
new file mode 100644
index 0000000..aaffb7b
--- /dev/null
+++ b/doc/sciteco.7.template
@@ -0,0 +1,12 @@
+.ds ST \\fB@PACKAGE_NAME@\\fP
+.
+.
+.TH "@PACKAGE@" 7 \
+    "@DATE@" \
+    "@PACKAGE_NAME@ Version @PACKAGE_VERSION@"
+..
+.
+.SH COMMAND REFERENCE
+\#$COMMANDS
+..
+\# EOF
\ No newline at end of file