Undocumented hyperlinks in doc strings.

Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Why does `default' get a hyperlink in the documentation string of
`fringe-mode'?  Is this a bug or a "feature"? `default' is not defined
as a variable nor as a function, nor is it preceded by `info node' or
`Info node', hence it is not covered by the list of possibilities
described in (elisp)Documentation Tips.  It is extremely important
that this list be completely exhaustive and accurate if we want
package authors to write good documentation strings.

If the reason would be that `default' is a face, then apart from the
lack of documentation (which could easily be fixed), I would also have
the less easily fixed objection that faces just tend to have extremely
common names such as `default', `mouse', `menu', `region', `button'
`border', `fringe', `bold', and countless equally common ones, that
are used for tons of other purposes.  Systematically having to write
`symbol' in front of them would be a lot more of a nuisance than for
variables or functions, simply because the situation occurs so much
more frequently.

"Fake" hyperlinks like the one for `default' in the documentation
string below are distracting and confusing.  It misleadingly suggests
that if you follow it, you will get more information about what the
value `default' means.  Instead you get to stare at completely
unrelated face documentation.

(defun fringe-mode (&optional mode)
  "Toggle appearance of fringes on all frames.
Valid values for MODE include `none', `default', `left-only',
`right-only', `minimal' and `half'.  MODE can also be a cons cell
where the integer in car will be used as left fringe width and the
integer in cdr will be used as right fringe width. If MODE is not
specified, the user is queried.
It applies to all frames that exist and frames to be created in the
future.
If you want to set appearance of fringes on the selected frame only,
see `set-fringe-style'."

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

    If the reason would be that `default' is a face, then apart from the
    lack of documentation (which could easily be fixed), I would also have
    the less easily fixed objection that faces just tend to have extremely
    common names such as `default', `mouse', `menu', `region', `button'
    `border', `fringe', `bold', and countless equally common ones, that
    are used for tons of other purposes.

Perhaps it would be a good idea not to make a hyperlink to a face
name unless the word "face" precedes or follows the face name.
Would you like to implement that change?

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

   Perhaps it would be a good idea not to make a hyperlink to a face
   name unless the word "face" precedes or follows the face name.
   Would you like to implement that change?

What about the diff below?  It also changes `help-xref-symbol-regexp',
because that variable is used with emacs-lisp-mode-syntax-table,
meaning that newlines do not count as whitespace.  As a consequence,
preceding a variable, function or face by `symbol', `variable' and the
like has no effect if the word is separated from the symbol by a
newline.  This means that a simple M-q can easily enable or disable
several hyperlinks.  This does not seem good.  The change in
`help-xref-symbol-regexp' treats newlines as any other whitespace.
The exact specs for face hyperlinks would be:
preceded by "face" or followed by whitespace (including newline),
"face" and then a non word constituent character.

The diff below also makes the comments in `help-make-xrefs' more in
line with (elisp)Comment Tips.  Most of this was done for me by C-M-q,
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.

If you agree with the diff below, I could commit it and adjust the
documentation in several places of the Elisp manual, documentation
strings and the NEWS accordingly.


===File ~/help-mode-diff====================================
cd ~/emacscvsdir/emacs/lisp/
diff -c /home/teirllm/help-mode.old.el /home/teirllm/emacscvsdir/emacs/lisp/help-mode.el
*** /home/teirllm/help-mode.old.el	Tue Sep  2 07:33:28 2003
--- /home/teirllm/emacscvsdir/emacs/lisp/help-mode.el	Thu Oct  9 21:17:17 2003
***************
*** 213,219 ****
  		    "\\(function\\|command\\)\\|"
  		    "\\(face\\)\\|"
  		    "\\(symbol\\)\\|"
! 		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)\\s-+\\)?"
  		    ;; Note starting with word-syntax character:
  		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
    "Regexp matching doc string references to symbols.
--- 213,220 ----
  		    "\\(function\\|command\\)\\|"
  		    "\\(face\\)\\|"
  		    "\\(symbol\\)\\|"
! 		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
! 		    "[ \t\n]+\\)?"
  		    ;; Note starting with word-syntax character:
  		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
    "Regexp matching doc string references to symbols.
***************
*** 342,352 ****
                           (sym (intern-soft data)))
                      (if sym
                          (cond
!                          ((match-string 3) ; `variable' &c
                            (and (boundp sym) ; `variable' doesn't ensure
                                          ; it's actually bound
                                 (help-xref-button 8 'help-variable sym)))
!                          ((match-string 4) ; `function' &c
                            (and (fboundp sym) ; similarly
                                 (help-xref-button 8 'help-function sym)))
  			 ((match-string 5) ; `face'
--- 343,353 ----
                           (sym (intern-soft data)))
                      (if sym
                          (cond
!                          ((match-string 3)  ; `variable' &c
                            (and (boundp sym) ; `variable' doesn't ensure
                                          ; it's actually bound
                                 (help-xref-button 8 'help-variable sym)))
!                          ((match-string 4)   ; `function' &c
                            (and (fboundp sym) ; similarly
                                 (help-xref-button 8 'help-function sym)))
  			 ((match-string 5) ; `face'
***************
*** 354,365 ****
  			       (help-xref-button 8 'help-face sym)))
                           ((match-string 6)) ; nothing for `symbol'
  			 ((match-string 7)
! ;; this used:
! ;; 			   #'(lambda (arg)
! ;; 			       (let ((location
! ;; 				      (find-function-noselect arg)))
! ;; 				 (pop-to-buffer (car location))
! ;; 				 (goto-char (cdr location))))
  			  (help-xref-button 8 'help-function-def sym))
                           ((and (boundp sym) (fboundp sym))
                            ;; We can't intuit whether to use the
--- 355,366 ----
  			       (help-xref-button 8 'help-face sym)))
                           ((match-string 6)) ; nothing for `symbol'
  			 ((match-string 7)
! ;;; this used:
! ;;; 			  #'(lambda (arg)
! ;;; 			      (let ((location
! ;;; 				     (find-function-noselect arg)))
! ;;; 				(pop-to-buffer (car location))
! ;;; 				(goto-char (cdr location))))
  			  (help-xref-button 8 'help-function-def sym))
                           ((and (boundp sym) (fboundp sym))
                            ;; We can't intuit whether to use the
***************
*** 370,376 ****
  			 ((fboundp sym)
  			  (help-xref-button 8 'help-function sym))
  			 ((facep sym)
! 			  (help-xref-button 8 'help-face sym)))))))
                ;; An obvious case of a key substitution:
                (save-excursion
                  (while (re-search-forward
--- 371,378 ----
  			 ((fboundp sym)
  			  (help-xref-button 8 'help-function sym))
  			 ((facep sym)
! 			  (if (save-match-data (looking-at "[ \t\n]*face\\W"))
! 			      (help-xref-button 8 'help-face sym))))))))
                ;; An obvious case of a key substitution:
                (save-excursion
                  (while (re-search-forward

Diff finished at Thu Oct  9 21:26:20
============================================================

Re: Undocumented hyperlinks in doc strings.

[Stefan Monnier]

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


        Stefan

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

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.

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

>From my earlier message:

   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.

I did not mean to be cynical, I just forgot to properly check.  Of
course it yields problems.  (It is a pretty extreme example.)

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Stefan Monnier]

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

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Stefan Monnier wrote:

   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.

Well at least _something_ needs to be changed to the current
";; this used:" commented out code fragment in `help-make-xrefs', if
it is to become "C-M-q invariant".   Just go to the beginning of the
`help-make-xrefs' defun and do C-M-q.  I doubt that the result is what
you really want.

Maybe:

			 ((match-string 7)
                          ;; this used:
                          ;; #'(lambda (arg)
                          ;;     (let ((location
                          ;;            (find-function-noselect arg)))
                          ;;       (pop-to-buffer (car location))
                          ;;       (goto-char (cdr location))))
                          (help-xref-button 8 'help-function-def sym))



   But I do turn the three-semi to two-semi when I come across them
   with outline-minor-mode.

If you just do that mechanically, without checking that the result is
"C-M-q" invariant, and then somebody else mechanically applies C-M-q to
the function, the result is not going to look good.  In the case of
`help-make-xrefs' such a mechanical change appears to have been made.
I believe this should be fixed one way or the other.  The current
indentation is a "C-M-q hazard".

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Stefan Monnier]

> Well at least _something_ needs to be changed to the current
> ";; this used:" commented out code fragment in `help-make-xrefs', if

Well, yes, they need to be indented properly.

> If you just do that mechanically, without checking that the result is
> "C-M-q" invariant, and then somebody else mechanically applies C-M-q to
> the function, the result is not going to look good.  In the case of

Of course, when turning 3-semi to 2-semi, you also need to rework
the indentation.  The two styles are different not just in the number of
semi-colon used, obviously.


        Stefan

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

      This means that a simple M-q can easily enable or disable
    several hyperlinks.  This does not seem good.  The change in
    `help-xref-symbol-regexp' treats newlines as any other whitespace.

Thanks for noticing and fixing this bug.  Please install your change.

Meanwhile, it might be another bug to allow more than one whitespace
character between words like `function' and the function name.
Multiple spaces never happen in normal text, only when there is
a sort of deliberate paragraph breaking or tabular structure.
In those cases, going across paragraphs or fields would probably
be a mistake.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

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

Three or more semicolons are the convention for comments that should
start at the margin, and that is our standard way of commenting out
code.  Like anything, it could be changed, but that is a rather
heavy change to make and I would hesitate to do it on account of
outline-minor-mode.

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

	 This means that a simple M-q can easily enable or disable
       several hyperlinks.  This does not seem good.  The change in
       `help-xref-symbol-regexp' treats newlines as any other whitespace.

   Thanks for noticing and fixing this bug.  Please install your change.

   Meanwhile, it might be another bug to allow more than one whitespace
   character between words like `function' and the function name.
   Multiple spaces never happen in normal text, only when there is
   a sort of deliberate paragraph breaking or tabular structure.
   In those cases, going across paragraphs or fields would probably
   be a mistake.

and:

   Three or more semicolons are the convention for comments that should
   start at the margin, and that is our standard way of commenting out
   code.  Like anything, it could be changed, but that is a rather
   heavy change to make and I would hesitate to do it on account of
   outline-minor-mode.

That leaves two questions to be addressed before I install my change.

In as far as the first one goes, one could replace the occurrences of
[ \t\n]+ and [ \t\n]* (the latter probably would have to be changed to
[ \t\n]+ anyway, for consistency) in my patch by [ \n].  (If one does
not allow multiple spaces, it seems consistent not to allow tab
either.)  That would mean that the author would have to be careful
about "space related sloppiness" like trailing whitespace or an
inadvertent inappropriate double space inside a sentence.  _As long as_
the author is careful to check his documentation strings with a C-h v
or C-h f (I always do, but I do not know about other people) that
would be an advantage, because the lack of hyperlink would immediately
point out the problem.

In as far as the second goes, I infer from your response that you
prefer the three semi-colon solution of my original patch over the two
semi-colon re-indentation I proposed in a reply to Stefan.  (I do not
believe that the _current_ two semi-colon indentation makes sense,
since it is "C-M-q instable".)

Just in case, what about a convention to follow ;;; by a single space
if one wants the line two be considered a "heading line" by
outline-minor-mode and by at least two spaces if one wants it to be
considered a "body line".  The three semi-colons are mostly important
for commented out code _inside_ a function and apart from an initial
comment (;;; this used: , in the code at issue) and possibly commented
out parts of the documentation string, at least two spaces usually
follow the semi-colons anyway.  So, in the code in question, one just
would have to replace:

;;; this used:

with:

;;;  this used:

without any other change to the original three semi-colon solution.

With:

";;;;* [^ \t\n]\\|(" instead of the current ";;;;* \\|(" as
outline-regexp in emacs-lisp-mode, none of the commented out code
would be considered a heading line by outline-minor-mode.

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

    In as far as the first one goes, one could replace the occurrences of
    [ \t\n]+ and [ \t\n]* (the latter probably would have to be changed to
    [ \t\n]+ anyway, for consistency) in my patch by [ \n].  (If one does
    not allow multiple spaces, it seems consistent not to allow tab
    either.)  That would mean that the author would have to be careful
    about "space related sloppiness" like trailing whitespace or an
    inadvertent inappropriate double space inside a sentence.

That is true.  I am not sure which approach would actually do a better job
in practice.

    Just in case, what about a convention to follow ;;; by a single space
    if one wants the line two be considered a "heading line" by
    outline-minor-mode and by at least two spaces if one wants it to be
    considered a "body line".

That might work.  If you use M-x comment-region on code within a
function, there will normally be at least three spaces after the
semicolons.  However, if you use M-x comment-region to comment out
top-level code, there may sometimes be just one space.  Still, making
outlines use this convention might be a good improvement in outline
processing on Lisp files.

(I think that outline processing on Lisp files is a rather obscure
issue.)

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

       In as far as the first one goes, one could replace the occurrences of
       [ \t\n]+ and [ \t\n]* (the latter probably would have to be changed to
       [ \t\n]+ anyway, for consistency) in my patch by [ \n].  (If one does
       not allow multiple spaces, it seems consistent not to allow tab
       either.)  That would mean that the author would have to be careful
       about "space related sloppiness" like trailing whitespace or an
       inadvertent inappropriate double space inside a sentence.

   That is true.  I am not sure which approach would actually do a better job
   in practice.

I would be leaning toward keeping [ \t\n]+, although this is a close
call and I am not really sure either.

There is some more strange behavior in connection with these
hyperlinks.  Evaluate

(defvar sillyvar nil
  "Documents the strange behavior of `button'.
Also, the symbol `tool-bar-mode' and dynamic `use-mouse-action'.")

and do C-h v sillyvar.  Then in the *Help* buffer click with mouse-2 on
`button'.

The behavior in the next paragraph seems deliberate.  I just describe
it in detail, in case it would not be.

In spite of my patch, we now see the face documentation of `button'.
That is because, in the absence of a hyperlink, mouse-2 is bound to
`help-follow-mouse' which will follow and list all available
documentation regardless of any convention.  `help-make-xrefs' is not
involved here.  Mouse-2 also will follow `tool-bar-mode' in spite of
the `symbol' in front of it.  (The `symbol' prevents the making of a
hyperlink for the following symbol, but does not actually prevent
mouse-2 from listing all available documentation for that symbol.)
Mouse-2 will also follow the following `and', viewing it as the lisp
special form.

All the above is probably deliberate, but now things get more
"exotic".  In the face documentation of `button' click on [back].  Of
course, we get the doc string of sillyvar back, but it has changed.
Previously, `button' and `use-mouse-action' were not underlined,
because they were not hyperlinks, but now they are underlined.  One
can check that neither `button' not `use-mouse-action' are defined as
variables, before clicking once more on `button' with mouse-2 and
getting:

button's value is 
#<marker
(moves after insertion)
at 20 in *Help*>

Not documented as a variable.

[back]

What happens is that button is not defined as a global variable.
However, when clicking on a hyperlink, mouse-2 is bound to
`push-button', whose code contains:

    (let ((button (button-at (or pos (point)))))
      (if (not button)
        nil
	(button-activate button use-mouse-action)
	t))))

`button' and `use-mouse-action' now are dynamically bound.  When we
clicked on `back' in the face documentation `button' and
`use-mouse-action' were dynamically `boundp' when `help-make-xrefs'
was deciding whether a hyperlink should be made for them.  In the
*Help* buffer they were not boundp any more, but once we actually
clicked on the hyperlink, `button' was boundp again, and its dynamic
binding got displayed.

`button' being a text property, we can not just avoid to use it in
documentation strings.  What about replacing:

                      ((boundp sym)
	               (help-xref-button 8 'help-variable sym))

by:

                      ((and (boundp sym)
                            (not (string= sym "button")))
		       (help-xref-button 8 'help-variable sym))

That would still make a hyperlink for: the variable `button' 
but not for a mere: `button'.

`button' appears to be the only real problem.  I do not believe that
`use-mouse-action' is likely to actually occur in hyperlinks.  Hence,
it might not be worth worrying about.

Out of curiosity one can click on the `use-mouse-action' hyperlink
anyway and get:

use-mouse-action's value is t

Not documented as a variable.

[back]

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Stefan Monnier]

> Three or more semicolons are the convention for comments that should
> start at the margin, and that is our standard way of commenting out
> code.

I know it is the convention.  I'm not sure what you mean by
"our standard", tho.

> Like anything, it could be changed, but that is a rather
> heavy change to make

I see no evidence that it is heavy.  Lots of Emacs code
already uses a different convention and this has not been
a problem (which I also take as evidence that it's a convention
superior to the offical one).

> and I would hesitate to do it on account of
> outline-minor-mode.

It's not just a problem for outline-minor-mode.  It's a fundamental problem
that the convention leads to ambiguities that only a human being
can resolve.  Luckily this convention is not often used in code, and is
rarely used by packages (can't think of any other than outline-minor-mode
and lisp-mnt).


        Stefan

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Stefan Monnier wrote:

   It's a fundamental problem that the convention leads to ambiguities
   that only a human being can resolve.

That could be mended by a slight change in the current standard
(which, to me, means: "as recommended in the Elisp manual") way of
commenting out code, which I proposed in an earlier message: follow
the semicolons by a single space if the line is meant to be a heading
line and by at least two spaces otherwise.  Anyway, in as far as I am
concerned, one could stay with the current standard as is, or add my
proposed modification, or change to your proposed convention, I do not
mind either way, as long as the actual chosen standard is accurately
and clearly documented in the Elisp manual.

I want to concentrate on the commented out code in `help-make-xrefs'
which according to me is should simply be deleted:

                         ((match-string 7)
! ;;; this used:
! ;;;                     #'(lambda (arg)
! ;;;                         (let ((location
! ;;;                                (find-function-noselect arg)))
! ;;;                           (pop-to-buffer (car location))
! ;;;                           (goto-char (cdr location))))
                          (help-xref-button 8 'help-function-def sym))

The "commented out code" is actually not code "commented out in
place", but the old second argument to `help-xref-button', which, at
the time, also required an extra fourth argument.  This got replaced
in revision 1.232 to help.el by the current second argument
'help-function-def.  I believe the "commented out code" has been
obsolete for more than two years by now.  Why keep it?  If we
systematically kept old code around like this and never deleted it,
source files would quickly become bloated and hard to read.

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

It is not unusual to comment out code that was replaced.
Whether it is worth keeping depends on details.  Maybe it would
be just as well to delete that comment, but I would not say all
such comments should always be deleted.

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

   It is not unusual to comment out code that was replaced.
   Whether it is worth keeping depends on details.  Maybe it would
   be just as well to delete that comment, but I would not say all
   such comments should always be deleted.

Is this commenting out instead of deletion done for historical record
or because one was not sure about the change and because hence there
is the possibility that one might want to sooner or later revert to
the original code?  If the former, one could keep the code in
question, after maybe pointing out more clearly that the code was the
old alternative to 'help-function-def.  Otherwise, the
`define-button-type' for 'help-function-def contains a modified
version of that code, with a comment explaining why that modification
was necessary.

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

    That could be mended by a slight change in the current standard
    (which, to me, means: "as recommended in the Elisp manual") way of
    commenting out code, which I proposed in an earlier message: follow
    the semicolons by a single space if the line is meant to be a heading
    line and by at least two spaces otherwise.

That convention, in itself, would not hurt anything.  But if we wanted
to follow it all the time, what exactly would we make comment-region
do, for Lisp code?  Would we make it insert two spaces always?  Two
spaces, when given an arg of 3?  And what would uncomment-region do?
If we make it try to remove two spaces (when there are two),
then it would uncomment all the existing commented-out code wrong.

I am not saying that these answer have to be perfect, but we need
to pick answers.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

    Is this commenting out instead of deletion done for historical record
    or because one was not sure about the change and because hence there
    is the possibility that one might want to sooner or later revert to
    the original code?

Both sorts of things are done as normal practice.

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

       That could be mended by a slight change in the current standard
       (which, to me, means: "as recommended in the Elisp manual") way of
       commenting out code, which I proposed in an earlier message: follow
       the semicolons by a single space if the line is meant to be a heading
       line and by at least two spaces otherwise.

   That convention, in itself, would not hurt anything.  But if we wanted
   to follow it all the time, what exactly would we make comment-region
   do, for Lisp code?  Would we make it insert two spaces always?  Two
   spaces, when given an arg of 3?  And what would uncomment-region do?
   If we make it try to remove two spaces (when there are two),
   then it would uncomment all the existing commented-out code wrong.

   I am not saying that these answer have to be perfect, but we need
   to pick answers.

The three semicolons seem to be mainly important for commented out
code _inside_ functions, to prevent C-M-q from messing things up
badly.  If it would be considered OK to use two semicolons for
commenting out entire top-level forms, then I believe we would not
even need to worry about comment-region or uncomment-region.  Indeed
the only line that would not automatically get the two spaces anyway
would appear to be the introductory line, like

;; this used:

in the example we have been looking at.

This line has to be written in manually and deleted manually after
uncommenting anyway.  People would only have to type an extra space at
the beginning of that one line they have to type in anyway.

If using three semicolons for commented out entire top level forms
would be important, then things would get more complicated.

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Stefan Monnier]

> The three semicolons seem to be mainly important for commented out
> code _inside_ functions, to prevent C-M-q from messing things up
> badly.  If it would be considered OK to use two semicolons for
> commenting out entire top-level forms, then I believe we would not
> even need to worry about comment-region or uncomment-region.  Indeed
> the only line that would not automatically get the two spaces anyway
> would appear to be the introductory line, like

We're getting somewhere.


        Stefan


PS: When I started this thread, I hesitated because we'd been through that
    discussion already and it got stuck.  Thank you for your constructive
    suggestions.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

    `button' being a text property, we can not just avoid to use it in
    documentation strings.  What about replacing:

			  ((boundp sym)
			   (help-xref-button 8 'help-variable sym))

    by:

			  ((and (boundp sym)
				(not (string= sym "button")))
			   (help-xref-button 8 'help-variable sym))

Perhaps it should test that the variable has documentation
as a variable.  That would be cleaner.  Would that do the job?

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

   Perhaps it should test that the variable has documentation
   as a variable.  That would be cleaner.  Would that do the job?

Yes:

                         ((and
			   (boundp sym)
			   (documentation-property sym
						   'variable-documentation))
			  (help-xref-button 8 'help-variable sym))

seems to work well.  It would still make a hyperlink for the variable
if explicitly preceded by the word "variable", so the author could
still make hyperlinks for undocumented  variables in (I would guess
extremely uncommon) situations where this might actually be desirable.

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

      If it would be considered OK to use two semicolons for
    > commenting out entire top-level forms, then I believe we would not
    > even need to worry about comment-region or uncomment-region.

That might be a good solution.  However, users won't all
remember to do it manually.  Is there a way to make comment-region
decide this automatically?

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

   That might be a good solution.  However, users won't all
   remember to do it manually.  Is there a way to make comment-region
   decide this automatically?

Currently, comment-region inserts, by default, in emacs-lisp-mode, two
semicolons and one space at the margin.  With the current convention,
one has to remember to give it a numeric argument of 3 when commenting
out code.  With the proposed new convention, that would only be
necessary when commenting out code _inside_ a function.  Apart from
that the only extra thing to remember would be to leave the extra one
space for the introductory: "this used: " type of sentence, if
present.  I guess it might be feasible to make comment-region insert
three semicolons by default when commenting out code _inside_ a
function with semicolons at the margin (since with two semicolons
C-M-q would mess things up in this situation), but even without that I
believe that comment-region in its present form would interact better
with the new proposed convention that with the current one (because an
explicit numeric argument would be needed less often).

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

      I guess it might be feasible to make comment-region insert
    three semicolons by default when commenting out code _inside_ a
    function with semicolons at the margin (since with two semicolons
    C-M-q would mess things up in this situation),

Want to try to do that?

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

	 I guess it might be feasible to make comment-region insert
       three semicolons by default when commenting out code _inside_ a
       function with semicolons at the margin (since with two semicolons
       C-M-q would mess things up in this situation),

   Want to try to do that?

I will take a look at it.

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Stefan Monnier]

> 	 I guess it might be feasible to make comment-region insert
>        three semicolons by default when commenting out code _inside_ a
>        function with semicolons at the margin (since with two semicolons
>        C-M-q would mess things up in this situation),
>    Want to try to do that?
> I will take a look at it.

The only way I can think of that won't make newcomment.el's code
even more complex (and significantly more ugly) is to accept
expressions (rather than just numbers) for comment-add.

Then the expression could use syntax-ppss or some such trick to
decide whther to evaluate to 1 or 2.


        Stefan

Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Stefan Monnier wrote:

   The only way I can think of that won't make newcomment.el's code
   even more complex (and significantly more ugly) is to accept
   expressions (rather than just numbers) for comment-add.

   Then the expression could use syntax-ppss or some such trick to
   decide whther to evaluate to 1 or 2.

Could you take a look at it?  Since you are the maintainer of
newcomment.el it would be easier for you since you are familiar with
the code.  (I am not at all.)  I took an initial look at it and it
seems indeed more complicated than I thought.  If it seems too complex
for you as the maintainer, it is certainly going to be too complex for
me.

Sincerely,

Luc.

Re: Undocumented hyperlinks in doc strings.

[Richard Stallman]

    The only way I can think of that won't make newcomment.el's code
    even more complex (and significantly more ugly) is to accept
    expressions (rather than just numbers) for comment-add.

Using user-specified expressions is ugly, and we would have to mark
the variable risky, which is undesirable for an existing option
that was not risky before.

It would be better to add a new variable comment-add-function
and use that, if non-nil, rather than comment-add.