From ef897b418a4487196e1dbc18a97046f8f0aea2e8 Mon Sep 17 00:00:00 2001 From: Robin Haberkorn Date: Tue, 24 Dec 2024 13:29:32 +0300 Subject: introduced true block and EOL comments * The previous convention of !* ... *! are now true block comments, i.e. they are parsed faster, don't spam the goto table and allow embedding of exclamation marks - only "*!" terminates the comment. * It is therefore now forbidden to have goto labels beginning with "*". * Also support "!!" to introduce EOL comments (like C++'s //). This disallows empty labels, but they weren't useful anyway. This is the shortest way to begin a comment. * All comment labels have been converted to true comments, to ensure that syntax highlighting works correctly. EOL comments are used for single line commented-out code, since it's easiest to uncomment - you don't have to jump to the line end. This is a pure convention / coding style. Other people might do it differently. * It's of course still possible to abuse goto labels as comments as TECO did for ages. * In lexing / syntax highlighting, labels and comments are highlighted differently. * When syntax highlighting, a single "!" will first be highlighted as a label since it's not yet unambiguous. Once you type the second character (* or !), the first character is retroactively styled as a comment as well. --- doc/sciteco.7.template | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/sciteco.7.template b/doc/sciteco.7.template index 053a5cb..f9cad80 100644 --- a/doc/sciteco.7.template +++ b/doc/sciteco.7.template @@ -2085,7 +2085,8 @@ Labels are symbolic and are defined with the following syntax: .br .BI ! label ! .br -Whereas \fIlabel\fP is an arbitrary string. +Whereas \fIlabel\fP is an arbitrary non-empty string. +Labels however cannot practically begin with an asterisk sign (*). String building is not performed on \fIlabel\fP, i.e. it is used verbatim. When a label is encountered, it is cached in a macro-invocation level @@ -2094,9 +2095,36 @@ 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. +Labels are also historically used as comments in TECO code. +. +.SS Comments .SCITECO_TOPIC comment -Labels also have another important role in \*(ST \(em they are used -as comments. +. +In addition to labels and unlike most classic TECO dialects, +\*(ST also supports true comments. +True comments are parsed faster than labels and do not +take up memory in goto tables. +.SCITECO_TOPIC "block comment" +One form of comments is the block comment: +.br +.BI !* comment *! +.br +Single exclamation marks (!) can be embedded in the \fIcomment\fP if they are not +following asterisk signs (unlike in goto-labels). +Block comments can span multiple lines. +They are analoguous to C's +.BI /* ... */ +comments. +.LP +.SCITECO_TOPIC "EOL comment" +The second form of real comments are end-of-line comments, +which are analogous to C++'s \fB//\fP comments: +.br +.BI !! comment +.LP +The idiom \(lq0<\fIcommands\fP>\(rq +is also sometimes useful to comment out large blocks of \*(ST code. +However, all \fIcommands\fP must still be syntactically correct. . .SS Loops .SCITECO_TOPIC < > loop -- cgit v1.2.3