unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: Stefan Monnier <monnier@IRO.UMontreal.CA>
Cc: rms@gnu.org, emacs-devel@gnu.org
Subject: Re: Undocumented hyperlinks in doc strings.
Date: 10 Oct 2003 13:23:28 -0400	[thread overview]
Message-ID: <jwvllrtggxm.fsf-monnier+emacs/devel@vor.iro.umontreal.ca> (raw)
In-Reply-To: <200310101531.h9AFVnX22383@raven.dms.auburn.edu>

>> but I made the double semicolons in the commented out code into
>> triple semicolons myself, because that is how (elisp)Comment Tips
>> wants code commented out.

>    Please don't.  It might be documented that way, but outline-minor-mode
>    behaves very poorly with them.  And it's very hard to "fix"
>    outline-minor-mode because it can't tell the difference between
>    the case where the three-semi-comment is used for a major heading or
>    for commented out code.  I think the doc should be fixed.

> But then we should not only change (elisp)Comment Tips, but also
> quantify the assertion:

>    * Indent each function with `C-M-q' (`indent-sexp') using the
>      default indentation parameters.

I don't understand what you mean here.
My recommendation is to use two semi-colons instead of three.
The indentation of those semi-colons is the same as normal code
and works just fine for commented-out code (this style is of
commenting-out is already used at many places).

One problem is that comment-region by default puts the comment markers
in column 0.  But setting comment-style to any value other than `plain'
addresses this issue.

> in (elisp)Coding Conventions, as well as change (probably plenty of)
> existing code.

Some of the code uses the documented convention while other uses
the convention that I propose.  I don't know which is more common,
but neither is "marginal".  We've lived with this "inconsistency"
without even thinking about it for many years, so I see no reason
to go and "fix" it all at once for the sake of it.  But I do turn
the three-semi to two-semi when I come across them with outline-minor-mode.

> See for instance "describe-text.el", lines 222 and
> following.  Note that three semicolons are currently recommended and
> used for _several_ purposes other than "major headings", see
> (elisp)Comment Tips.  The most important ones are for use
> _within a function_.

I know, and the difficulty to tell one case from the radically different
other is the reason why I think the doc is broken.

> The fact that we would get trouble with C-M-q if we follow your
> suggestion seems to be a real nuisance.

I have no idea what trouble you're referring to.  I use M-C-q on a regular
basis without any trouble whatsoever.

> Can outline-minor-mode not "see" that the commented out code is inside
> a function or other Lisp form?

It's pretty difficult and costly to do so (need to extend outline.el
so as to allow more than just regexps to specify headings).  Furthermore it
won't work right in the case where three-semi commented-out code code
is outside of a lisp form (pretty common) and it won't work right either
when a heading is inside a lisp form (not a real concern, but possible
and meaningful).

> commented out code outside functions (so using two semicolons _there_
> would not seem that bad) and, on the other, if one gets "really

Outside of functions, two-semi and three-semi behave just the same,
indentationwise, so it's really a non-issue.

> then _both_ outline-minor-mode and C-M-q will have problems and we get
> the "worst of both worlds".

C-M-q doesn't need to differentiate between major headings and other
comments, so as far as I know, it is completely unaffected by the
issue discussed here.  Unless I missed something, of course.


        Stefan

  parent reply	other threads:[~2003-10-10 17:23 UTC|newest]

Thread overview: 31+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2003-10-09  0:50 Undocumented hyperlinks in doc strings Luc Teirlinck
2003-10-09 21:16 ` Richard Stallman
2003-10-10  3:27   ` Luc Teirlinck
2003-10-10 14:14     ` Stefan Monnier
2003-10-10 15:31       ` Luc Teirlinck
2003-10-10 16:29         ` Luc Teirlinck
2003-10-10 17:23         ` Stefan Monnier [this message]
2003-10-10 18:21           ` Luc Teirlinck
2003-10-10 19:24             ` Stefan Monnier
2003-10-11 17:12       ` Richard Stallman
2003-10-14 21:03         ` Stefan Monnier
2003-10-15  1:38           ` Luc Teirlinck
2003-10-15 20:00             ` Richard Stallman
2003-10-15 23:52               ` Luc Teirlinck
2003-10-16 23:06                 ` Richard Stallman
2003-10-16 14:06             ` Richard Stallman
2003-10-17  3:32               ` Luc Teirlinck
2003-10-17 13:47                 ` Stefan Monnier
2003-10-18 23:06                   ` Richard Stallman
2003-10-19  1:14                     ` Luc Teirlinck
2003-10-20  1:48                       ` Richard Stallman
2003-10-20  2:24                         ` Luc Teirlinck
2003-10-20 14:44                           ` Stefan Monnier
2003-10-20 15:22                             ` Luc Teirlinck
2003-10-21 14:47                             ` Richard Stallman
2003-10-11  5:36     ` Richard Stallman
2003-10-12  3:34       ` Luc Teirlinck
2003-10-13  5:03         ` Richard Stallman
2003-10-14  3:23           ` Luc Teirlinck
2003-10-17 20:46             ` Richard Stallman
2003-10-17 23:30               ` Luc Teirlinck

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=jwvllrtggxm.fsf-monnier+emacs/devel@vor.iro.umontreal.ca \
    --to=monnier@iro.umontreal.ca \
    --cc=emacs-devel@gnu.org \
    --cc=rms@gnu.org \
    /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).