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/tedoc.tes.1.in | 130 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 doc/tedoc.tes.1.in (limited to 'doc/tedoc.tes.1.in') 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