bug#31623: 27.0; Elisp manual, index entry "; in comment"

[Drew Adams <drew.adams@oracle.com>]

> > OK, if you say so. ;-)  I was thinking more about "in"
> > meaning after `comment-start'.  But yes, I guess that's
> > what was intended.
> >
> > If that's the intention then I think it might be clearer
> > if the index entry were "; outside a comment" or maybe
> > "; not in a comment".
> 
> A later sentence in `(elisp) Comments' has:
> 
>     The Lisp reader discards comments; they do not become part of the
>     Lisp objects which represent the program within the Lisp system.
> 
> The discarded comment includes the leading ";", so I don't think it
> makes sense to treat the comment starter as being outside the comment.

Of course.  I didn't mean anything different.

My point was that seeing an index entry "; in comment" I
thought it likely referred to a `;' char in the commented
text.  I did not think that it was likely to be about the
places where a `;' char is considered to be a `comment-start'
char.

But certainly the `;' that starts a comment is part of the
comment itself.  No one would doubt that, I think.

> > In any case, that statement is not really true: a semicolon
> > does not always start a comment in Lisp whenever it is not
> > within a string or a character constant.  There is also the
> > case of it being escaped in a symbol name.  E.g.,
> >
> > (setq a\;b  42)
> >
> > (Dunno whether there are additional cases - perhaps not.)
> 
> I think not.  So add "unescaped"?
> 
>     In Lisp, an unescaped semicolon (`;') starts a comment
>     if it is not within a string or character constant.

Fine by me.  Thanks in advance for making that change.

But I really think the index entry leaves something to
be desired - which is what this bug report is about.

The entry should indicate something about the subject
indexed.  "; in comment" does not do that, for me, at
least.

In the case of the intended indexing, it's about where
`;' can start a Lisp comment - or more precisely, in
which contexts it does _not_ start a comment.

Someone looking that up might look for an entry such
as just ";" (you'd expect the subject to cover what
`;' can be used for in Lisp - which it does: comment
start, char constant, escaped char).

Or perhaps an entry such as "; as comment start" (but
that doesn't really suggest that the text will also
talk about other contexts for `;').

Or perhaps an entry such as "; used for commenting".

Or perhaps you have a suggestion.