Re: Marking lisp expressions

[Gavin Smith]

On Sun, Jan 26, 2020 at 4:18 AM Jean-Christophe Helary
<address@hidden> wrote:
> I'm looking for a way to mark lisp expressions so that the html output (for 
> now?) can have some sort of syntax coloring. I'm now using the following 
> mapping:
>
> functions → @command
> arguments → @var
> constants → @strong (for now only "t" and "()")
> comments → @r
>
> With the modified HTML.pm that I use (the small patch that I sent the other 
> day that adds different classes to identical tags) I have:
>
> 'command'     => 'code class="command"'
> 'var'         => 'var'
> 'strong'      => 'strong'
> 'r'           => 'span class="roman"'
>
> I can isolate constants (@strong) with the css selectors because they are 
> inside lisp blocks (or marked with an extra @code when within explanatory 
> text), hence @strong is not ideal.
>
> Here is some sample marking:
>
> @lisp
> (@command{defun} @var{subst} (@var{x y z})
>   (@command{cond} ((@command{atom} @var{z})
>          (@command{cond} ((@command{eq} @var{z y}) @var{x})
>                (@command{'}@strong{t} @var{z})))
>         (@command{'}@strong{t} (@command{cons} (@command{subst} @var{x y} 
> (@command{car} @var{z}))
>                   (@command{subst} @var{x y} (@command{cdr} @var{z}))))))
> @end lisp


> My questions are
>
> 1) are there better semantic markers for arguments, constants and comments ?

@var would only be correctly used for arguments in the definition of a
function (x, y and z in the definition of subst in your example), not
for the use of a function. (These are sometimes called parameters
rather than arguments.) As you say, the others are not really exact
matches.

> 2) if not, would it be acceptable to create a few more semantic markers that 
> correspond to "arguments", "constants" and "comments" ?

I doubt that this is the best approach to syntax highlighting. It
requires significant effort in marking up code examples. Moreover, the
list of categories may be unending.

I looked at some syntax highlighting configuration files for a couple
of languages (in vim). For C, categories include:

statement, label, conditional, loop keyword, to-do comment, regular
comment, strings, escape syntax in string, various markers for
incorrect syntax, operators, types, storage classes, constant symbols,
preprocessor conditionals, other preprocessor directives, and probably
more

You can easily imagine that other languages have different categories,
e.g. Perl might have a category for regular expressions.

I wonder if there should be some way of specifying the language of an
@example block. For example,

@example elisp
(defun subst (x y z)
  (cond ((atom z)
         (cond ((eq z y) x)
               ('t z)))
        ('t (cons (subst x y (car z))
                  (subst x y (cdr z))))))
@end example

producing a marker in the HTML output that could be used by a syntax
highlighter.