unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
From: Drew Adams <drew.adams@oracle.com>
To: Noam Postavsky <npostavs@gmail.com>
Cc: 31623@debbugs.gnu.org
Subject: bug#31623: 27.0; Elisp manual, index entry "; in comment"
Date: Tue, 29 May 2018 17:38:49 -0700 (PDT)	[thread overview]
Message-ID: <4fc08e13-4c43-4f4b-a9ad-0ce221b9d4ea@default> (raw)
In-Reply-To: <877enmc846.fsf@gmail.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.





  reply	other threads:[~2018-05-30  0:38 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-05-28 14:35 bug#31623: 27.0; Elisp manual, index entry "; in comment" Drew Adams
2018-05-29 23:32 ` Noam Postavsky
2018-05-29 23:47   ` Drew Adams
2018-05-30  0:14     ` Noam Postavsky
2018-05-30  0:38       ` Drew Adams [this message]
2018-05-30  1:58         ` Noam Postavsky
2018-05-30  2:23           ` Drew Adams
2018-06-20 12:48           ` Noam Postavsky

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=4fc08e13-4c43-4f4b-a9ad-0ce221b9d4ea@default \
    --to=drew.adams@oracle.com \
    --cc=31623@debbugs.gnu.org \
    --cc=npostavs@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).