From be39ab9fdbaba118ece1dcc3e064c8452fcdd277 Mon Sep 17 00:00:00 2001 From: Robin Haberkorn Date: Wed, 16 Nov 2016 16:30:46 +0100 Subject: 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. --- doc/Makefile.am | 40 +++++++++---- doc/generate-docs.tes | 153 ------------------------------------------------ doc/grosciteco.tes.1.in | 3 + doc/sciteco.1.in | 6 +- doc/sciteco.7.template | 3 +- doc/tedoc.tes | 129 ++++++++++++++++++++++++++++++++++++++++ doc/tedoc.tes.1.in | 130 ++++++++++++++++++++++++++++++++++++++++ 7 files changed, 297 insertions(+), 167 deletions(-) delete mode 100755 doc/generate-docs.tes create mode 100755 doc/tedoc.tes create mode 100644 doc/tedoc.tes.1.in (limited to 'doc') 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 ! - -! - Preprocess a manpage template, inserting a SciTECO command reference. - - The .COMMANDS request is replaced with Troff markup generated from code - comments in . - - 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 - * 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 -j qa"Sq.tj|.,q.txa.,q.td i -.SCITECO_TOPIC "Qa" -.B Qa -'> -j -j\(->;> -j .,q.txa .,q.td eqa eq.[header]i -.IR Qa -> -jjj -j 0a-10"=d' -zj-a-10"=-d' - ebQ#tm g.[header]i -. - -} - -@[format_body]{ - i.LP - - jj - ! 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;-di --s<-di -.I > - jj - 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= ! - - j - 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] [--] *! + +: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 + 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 \(->;> + J < + SMCM[|MC]; + .U.t <-A"C|-A-|"N1;'' R> + .,Q.tXa .,Q.tD EQa + + EQ.[header] + I^J.IR Qa^J + > + J + J + J + J 0A-10"=D' + ZJ -A-10"=-D' + EBQ#tm + G.[header] + I^J.^J +} + +@[format_body]{ + I.LP^J + + J + 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 ; -D I^J -S< -D I^J.I > + J + 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 + + 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\(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 -- cgit v1.2.3