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.

1 files changed, 31 insertions, 3 deletions

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