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

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

[Drew Adams]

From the text of index entry "; in comment" I would expect a node that
talks about the use of `;' inside a comment.  I cannot imagine what
other sense someone might make of this index-entry text.

But the target of the index entry, node `Comments', does not seem to
say anything about a `;' character inside a comment.

Please consider fixing this somehow - not sure what was intended.
Perhaps the entry text needs to be changed.  Or perhaps it the entry is
not pointing at the correct node.  Or perhaps the node text needs to be
changed, to address whatever the entry is supposed to suggest.



In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32)
 of 2018-03-21
Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install -C 'CFLAGS=-O2 -static -g3''

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

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

> From the text of index entry "; in comment" I would expect a node that
> talks about the use of `;' inside a comment.  I cannot imagine what
> other sense someone might make of this index-entry text.
>
> But the target of the index entry, node `Comments', does not seem to
> say anything about a `;' character inside a comment.

As far as I can tell, it refers to this sentence:

      In Lisp, a semicolon (`;') starts a comment if it is not
    within a string or character constant.

So, if it is not "within a string or character constant" then the
semicolon is in a comment.

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

[Drew Adams]

> > From the text of index entry "; in comment" I would expect a node that
> > talks about the use of `;' inside a comment.  I cannot imagine what
> > other sense someone might make of this index-entry text.
> >
> > But the target of the index entry, node `Comments', does not seem to
> > say anything about a `;' character inside a comment.
> 
> As far as I can tell, it refers to this sentence:
> 
>     In Lisp, a semicolon (`;') starts a comment if it is not
>     within a string or character constant.
> 
> So, if it is not "within a string or character constant" then the
> semicolon is in a comment.

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".

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.)

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

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

> 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.

> 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.

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

[Drew Adams]

> > 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.

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

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

>> > 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".

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

I'm a bit puzzled then.  How would "; outside a comment" make sense for
a page which talks about comments?  That seems to be the opposite of
what it's about.

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

What do you think about the "(...) in lists" entry?

> Or perhaps you have a suggestion.

I don't really see a problem with the current one, but I guess "; for
commenting" (in the same vein as "' for quoting") could be okay.

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

[Drew Adams]

> >> > 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".
> 
> > But certainly the `;' that starts a comment is part of the
> > comment itself.  No one would doubt that, I think.
> 
> I'm a bit puzzled then.  How would "; outside a comment" make sense for
> a page which talks about comments?  That seems to be the opposite of
> what it's about.

That's not a great index entry either.  The target text
is not at all about `;' in text that is commented.  It
is only about `;' used as a comment-start char.

> > The entry should indicate something about the subject
> > indexed.  "; in comment" does not do that, for me, at
> > least.
> 
> What do you think about the "(...) in lists" entry?

Never noticed it.  At least it's not a character.

If I had to guess naively, I'd probably expect that to
take me to some text about nested lists.  IMO, it too
is a bad index entry.  It's not clear at all what someone
might be looking for who would find that a description
that might help her find what is sought.

> > Or perhaps you have a suggestion.
> 
> I don't really see a problem with the current one, but I guess "; for
> commenting" (in the same vein as "' for quoting") could be okay.

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

[Noam Postavsky]

tags 31623 fixed
close 31623 26.2
quit

Noam Postavsky <npostavs@gmail.com> writes:

> I guess "; for commenting" (in the same vein as "' for quoting") could
> be okay.

Pushed to emacs-26.

[1: 40e1db8ccd]: 2018-06-20 08:46:13 -0400
  Change index of ";" to better reflect it's usage (Bug#31623)
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=40e1db8ccd1239fc7da5ccd3f5f79017b2b44afc