From: Luc Teirlinck <teirllm@dms.auburn.edu>
Cc: rms@gnu.org, emacs-devel@gnu.org
Subject: Re: Undocumented hyperlinks in doc strings.
Date: Fri, 10 Oct 2003 10:31:49 -0500 (CDT) [thread overview]
Message-ID: <200310101531.h9AFVnX22383@raven.dms.auburn.edu> (raw)
In-Reply-To: <jwvr81li3mb.fsf-monnier+emacs/devel@vor.iro.umontreal.ca> (message from Stefan Monnier on 10 Oct 2003 10:14:50 -0400)
Stefam Monnier wrote:
> 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.
in (elisp)Coding Conventions, as well as change (probably plenty of)
existing code. 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_.
The fact that we would get trouble with C-M-q if we follow your
suggestion seems to be a real nuisance. I would not immediately see
how to fix that problem either.
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.
Can outline-minor-mode not "see" that the commented out code is inside
a function or other Lisp form? I would guess that is pretty rare for
a major heading to occur in the middle of a function. The commented
out code in "describe-text.el" is _not_ inside a function. I do not
know whether this code yields problems for outline-minor-mode.
However, on the one hand, one is not going to call C-M-q easily on
commented out code outside functions (so using two semicolons _there_
would not seem that bad) and, on the other, if one gets "really
desperate" one can, in the worst case, place the commented out code
inside a call to `ignore'. But one could also start (and maybe end)
commented out code outside functions with some standard comment, so
outline-minor-mode (and actually a person reading through the file) can
easily recognize it for what it is.
Anyway, whatever is decided on this, I believe that it is important
that we all follow the _same_ conventions and that these conventions
are clearly and accurately documented. If we all "do are own thing"
then _both_ outline-minor-mode and C-M-q will have problems and we get
the "worst of both worlds".
Sincerely,
Luc.
next prev parent reply other threads:[~2003-10-10 15:31 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 [this message]
2003-10-10 16:29 ` Luc Teirlinck
2003-10-10 17:23 ` Stefan Monnier
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=200310101531.h9AFVnX22383@raven.dms.auburn.edu \
--to=teirllm@dms.auburn.edu \
--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).