[drew.adams@oracle.com: links in Help buffer aren't always correct]

[drew.adams@oracle.com: links in Help buffer aren't always correct]

[Richard Stallman]

Would someone please DTRT about this, then ack?

------- Start of forwarded message -------
From: "Drew Adams" <drew.adams@oracle.com>
To: "Emacs-Pretest-Bug" <emacs-pretest-bug@gnu.org>
Date: Mon, 28 Nov 2005 08:58:08 -0800
X-Brightmail-Tracker: AAAAAQAAAAI=
X-Whitelist: TRUE
Subject: links in Help buffer aren't always correct
Sender: emacs-pretest-bug-bounces+rms=gnu.org@gnu.org
X-Spam-Checker-Version: SpamAssassin 2.63 (2004-01-11) on monty-python
X-Spam-Level: 
X-Spam-Status: No, hits=0.0 required=5.0 tests=none autolearn=no version=2.63

For example, C-h f buffer-list shows this text:

 buffer-list is a built-in function in `C source code'.
 (buffer-list &optional frame)

 Return a list of all existing live buffers.
 If the optional arg frame is a frame, we return the buffer list
 in the proper order for that frame: the buffers in frame's `buffer-list'
 frame parameter come first, followed by the rest of the buffers.

 [back]

The text "buffer-list" in the last sentence is linked to the help for the
`buffer-list' function, not the `buffer-list' frame parameter. Either there
should be no link here (if there is no way to show help on the parameter) or
the link should point to help on the frame parameter.

In GNU Emacs 22.0.50.1 (i386-mingw-nt5.1.2600)
 of 2005-06-26 on NONIQPC
X server distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc
(3.3) --cflags -I../../jpeg-6b-3/include -I../../libpng-1.2.8/include -I../.
./tiff-3.6.1-2/include -I../../xpm-nox-4.2.0/include -I../../zlib-1.2.2/incl
ude'



_______________________________________________
emacs-pretest-bug mailing list
emacs-pretest-bug@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-pretest-bug
------- End of forwarded message -------

Re: [drew.adams@oracle.com: links in Help buffer aren't always correct]

[Kevin Rodgers]

Richard Stallman wrote:
> Would someone please DTRT about this, then ack?
> 
> ------- Start of forwarded message -------
> From: "Drew Adams" <drew.adams@oracle.com>
> To: "Emacs-Pretest-Bug" <emacs-pretest-bug@gnu.org>
> Date: Mon, 28 Nov 2005 08:58:08 -0800
> X-Brightmail-Tracker: AAAAAQAAAAI=
> X-Whitelist: TRUE
> Subject: links in Help buffer aren't always correct
> Sender: emacs-pretest-bug-bounces+rms=gnu.org@gnu.org
> X-Spam-Checker-Version: SpamAssassin 2.63 (2004-01-11) on monty-python
> X-Spam-Level: 
> X-Spam-Status: No, hits=0.0 required=5.0 tests=none autolearn=no version=2.63
> 
> For example, C-h f buffer-list shows this text:
> 
>  buffer-list is a built-in function in `C source code'.
>  (buffer-list &optional frame)
> 
>  Return a list of all existing live buffers.
>  If the optional arg frame is a frame, we return the buffer list
>  in the proper order for that frame: the buffers in frame's `buffer-list'
>  frame parameter come first, followed by the rest of the buffers.

I think it would be better to say:
   the buffers in FRAME's `buffer-list' frame parameter come first,
or:
   the buffers in the frame's `buffer-list' frame parameter come first,
or:
   the buffers in its `buffer-list' frame parameter come first,

>  [back]
> 
> The text "buffer-list" in the last sentence is linked to the help for the
> `buffer-list' function, not the `buffer-list' frame parameter. Either there
> should be no link here (if there is no way to show help on the parameter) or
> the link should point to help on the frame parameter.

Since there is no describe-frame-parameter command, and the phrase
"frame paramter" follows the quoted symbol (unlike the phrases listed
in help-xref-symbol-regexp, which precede quoted symbols), we can avoid
hyperlinking such phrases by changing help-make-xrefs in help-mode.el
from:

               ;; Quoted symbols
               (save-excursion
                 (while (re-search-forward help-xref-symbol-regexp nil t)
                   (let* ((data (match-string 8))
                          (sym (intern-soft data)))
                     (if sym

to:

               ;; Quoted symbols
               (save-excursion
                 (while (re-search-forward help-xref-symbol-regexp nil t)
                   (let* ((data (match-string 8))
                          (sym (intern-soft data)))
                     (if (and sym
                              (save-match-data
                                (not (looking-at "[ \t\n]+frame 
parameter"))))

-- 
Kevin Rodgers

RE: [drew.adams@oracle.com: links in Help buffer aren't alwayscorrect]

[Drew Adams]

    > The text "buffer-list" in the last sentence is linked to the
    > help for the `buffer-list' function, not the `buffer-list' frame
    > parameter. Either there should be no link here (if there is no
    > way to show help on the parameter) or
    > the link should point to help on the frame parameter.

    Since there is no describe-frame-parameter command, and the phrase
    "frame paramter" follows the quoted symbol (unlike the phrases listed
    in help-xref-symbol-regexp, which precede quoted symbols), we can avoid
    hyperlinking such phrases by changing help-make-xrefs in help-mode.el
    from:

                   ;; Quoted symbols
                   (save-excursion
                     (while (re-search-forward
    help-xref-symbol-regexp nil t)
                       (let* ((data (match-string 8))
                              (sym (intern-soft data)))
                         (if sym

    to:

                   ;; Quoted symbols
                   (save-excursion
                     (while (re-search-forward
    help-xref-symbol-regexp nil t)
                       (let* ((data (match-string 8))
                              (sym (intern-soft data)))
                         (if (and sym
                                  (save-match-data
                                    (not (looking-at "[ \t\n]+frame
    parameter"))))

I agree with the intention, but have doubts about the implementation - it
seems fragile, depending as it does on the exact text in the doc string. If
someone writes "frame parameter `buffer-list'" instead of "the `buffer-list'
frame parameter" then it won't work correctly. Likewise, if someone writes a
French doc string for a function or var that refers to a frame parameter.

But I guess the same could be said for the use of `help-xref-symbol-regexp',
generally. Given that we do use `help-xref-symbol-regexp' in a way that
depends on the exact doc-string text, wouldn't it be better to add the
doc-string convention to always precede the specific name by the type, so,
for instance, this doc string would say "frame parameter `buffer-list'"?
Then, "frame parameter could be added to `help-xref-symbol-regexp'.

There may not be a `describe-frame-parameter' function, but the
`help-make-xrefs' code could use a preceding "frame parameter" to link to
the Info section describing the `buffer-list' parameter. Or, at the very
least, it could test for preceding "frame parameter" in order to do nothing
(add no link) if it is present.

Re: [drew.adams@oracle.com: links in Help buffer aren't alwayscorrect]

[Kevin Rodgers]

Drew Adams wrote:
 > There may not be a `describe-frame-parameter' function, but the
 > `help-make-xrefs' code could use a preceding "frame parameter" to link to
 > the Info section describing the `buffer-list' parameter. Or, at the very
 > least, it could test for preceding "frame parameter" in order to do 
nothing
 > (add no link) if it is present.

Here's a start, cobbled together from describe-variable and your idea of
linking to the Info node:

(defun describe-frame-parameter (parameter &optional frame)
   "Display the full documentation of frame PARAMETER (a symbol) in FRAME.
If FRAME is nil, describe the selected frame's parameter value."
   (interactive
    (let* ((enable-recursive-minibuffers t)
           (default-param (symbol-at-point))
           (param-alist (frame-parameters nil))
           (param-name
            (completing-read (if (assq default-param param-alist)
                                 (format "Describe parameter (default %s): "
                                         default-param)
                               "Describe parameter: ")
                             obarray
                             (lambda (p) (assq p param-alist))
                             t nil nil
                             (if default-param (symbol-name 
default-param)))))
      (list (if (equal param-name "")
                default-param
              (intern param-name)))))
   (if (null frame)
       (setq frame (selected-frame)))
   (if (null parameter)
       (message "You did not specify a frame parameter")
     (with-output-to-temp-buffer "*Help*"
       (prin1 parameter)
       (princ "'s value is ")
       (terpri)
       (let ((param-value (frame-parameter frame parameter)))
         (with-current-buffer standard-output
           (let ((from (point)))
             (pp param-value)
             ;; (help-xref-on-pp from (point))
             (if (< (point) (+ from 20))
                 (save-excursion
                   (goto-char from)
                   (delete-char -1))))))
       (terpri)
       (terpri)
       (princ "Documentation (see Info node `(elisp)Window Frame 
Parameters'):")
       (terpri)
       (save-excursion
         (save-window-excursion
           (Info-goto-node "(elisp)Window Frame Parameters")
           (princ (buffer-substring
                   (re-search-forward (concat "^`" (symbol-name 
parameter) "'"))
                   (1- (or (re-search-forward "^`" nil t) 
(point-max))))))))))

-- 
Kevin Rodgers

Re: [drew.adams@oracle.com: links in Help buffer aren't alwayscorrect]

[Kevin Rodgers]

Kevin Rodgers wrote:
 >            (completing-read (if (assq default-param param-alist)
 >                                 (format "Describe parameter (default 
%s): "
 >                                         default-param)
 >                               "Describe parameter: ")
 >                             obarray
 >                             (lambda (p) (assq p param-alist))
 >                             t nil nil
 >                             (if default-param (symbol-name 
default-param)))))

It probably makes more sense to complete on the frame parameter alist
(with no predicate) than the entire obarray (with a predicate to check
the alist):

            (completing-read (if (assq default-param param-alist)
                                 (format "Describe parameter (default %s): "
                                         default-param)
                               "Describe parameter: ")
                             (mapcar (lambda (assoc)
                                       (list (symbol-name (car assoc))))
                                     param-alist)
                             nil t nil nil
                             (if default-param (symbol-name default-param)))

-- 
Kevin Rodgers

Re: [drew.adams@oracle.com: links in Help buffer aren't alwayscorrect]

[Richard M. Stallman]

describe-frame-parameter seems to work usefully, but it has one
problem: its completion list is incomplete.

RE: [drew.adams@oracle.com: links in Help buffer aren'talwayscorrect]

[Drew Adams]

    describe-frame-parameter seems to work usefully, but it has one
    problem: its completion list is incomplete.

Do you mean because it iterates only over the parameters of the selected
frame?

It might also include user-defined parameters that won't be documented in
Info. Perhaps it should instead iterate over an explicit list of all of the
Info-documented (built-in) frame parameters.

Perhaps too, the doc string should mention that it only works on documented
built-in frame parameters, not user-defined parameters.

I noticed too that in emacs -q, M-x describe-frame-parameter RET
cursor-color gives an error because Info-find-node is not defined
(autoloaded).

Re: [drew.adams@oracle.com: links in Help buffer aren'talwayscorrect]

[Kevin Rodgers]

Drew Adams wrote:
>     describe-frame-parameter seems to work usefully, but it has one
>     problem: its completion list is incomplete.
> 
> Do you mean because it iterates only over the parameters of the selected
> frame?
> 
> It might also include user-defined parameters that won't be documented in
> Info. Perhaps it should instead iterate over an explicit list of all of the
> Info-documented (built-in) frame parameters.

I'm sure that's what he means.  But by analogy, `M-x describe-variable'
doesn't complete on void symbols, and it is well understood that an
unset frame parameter's value is effectively void: frame-parameter
actually returns nil, but it means the parameter has no effect.

So why provide completion on all documented frame parameters?  So that
the user can simply type ? at the prompt to see the entire list of frame
parameters.  That would be really useful, if there was also a
set-frame-parameter command.

And if there were a define-frame-parameter function and/or defframeparam
macro that would maintain a global list (or obarray) of frame
parameters, it would allow `M-x describe-frame-parameter' and `M-x
set-frame-parameter' to reliably complete over both documented and
user-defined frame parameters.

> Perhaps too, the doc string should mention that it only works on documented
> built-in frame parameters, not user-defined parameters.

That seems like the right thing to do, unless we define a global
list (or obarray) of frame parameters to complete over.

> I noticed too that in emacs -q, M-x describe-frame-parameter RET
> cursor-color gives an error because Info-find-node is not defined
> (autoloaded).

Good point.  I think that since Info-goto-node displays the *Info*
buffer, it should be declared as an (interactive) command, and
therefore that it should be autoloaded.

-- 
Kevin Rodgers

RE: [drew.adams@oracle.com: links in Help bufferaren'talwayscorrect]

[Drew Adams]

    And if there were a define-frame-parameter function and/or defframeparam
    macro that would maintain a global list (or obarray) of frame
    parameters, it would allow `M-x describe-frame-parameter' and `M-x
    set-frame-parameter' to reliably complete over both documented and
    user-defined frame parameters.

Yes, that would be useful: letting users document user-defined params with a
doc string. (After the release... waiting for godot... after the release...)

Re: [drew.adams@oracle.com: links in Help buffer aren'talwayscorrect]

[Stefan Monnier]

> Good point.  I think that since Info-goto-node displays the *Info*
> buffer, it should be declared as an (interactive) command, and
> therefore that it should be autoloaded.

Use the `info' function, that's what it's for.


        Stefan

Re: [drew.adams@oracle.com: links in Help buffer aren'talwayscorrect]

[Richard M. Stallman]

    > Perhaps too, the doc string should mention that it only works on documented
    > built-in frame parameters, not user-defined parameters.

That goes without saying, since the point of the command is to show
the documentation, and only frame parameters with standard meanings
have standard documentation.

    Good point.  I think that since Info-goto-node displays the *Info*
    buffer, it should be declared as an (interactive) command, and
    therefore that it should be autoloaded.

It is already interactive.  However, programs normally do this
job by calling `info' or `info-other-window'.  They are autoloaded.

Re: [drew.adams@oracle.com: links in Help buffer aren'talwayscorrect]

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Wed, 14 Dec 2005 14:48:04 -0800

Drew, could you please do something about your #$%^&* mailer? Look how
it butchers the Subject lines when it thinks they are too long: it
removes whitespace and splices words, which makes it a pain to read
and use "C-c C-n" in Rmail.

bad mailer Subject meddling (was: links in Help buffer aren't always correct)

[Drew Adams]

    -----Original Message-----
    Subject: Re: [drew.adams@oracle.com: links in Help
    bufferaren'talwayscorrect]

    Drew, could you please do something about your #$%^&* mailer? Look how
    it butchers the Subject lines when it thinks they are too long: it
    removes whitespace and splices words, which makes it a pain to read
    and use "C-c C-n" in Rmail.

Sorry, I don't know how to fix that in Outlook. I use Outlook 2000, for
various reasons related to work. It's old, but still a very common (the most
common?) email client in use. I don't defend it, but it's the one I use.

If it produces brain-dead subject lines, but it is a very common mailer,
maybe Rmail's C-c C-n could somehow deal with it by adding extra
intelligence to handle the retarded output ;-)?  No flames please - I don't
even know what C-c C-n does, and I'm not proposing that good, free programs
bend to the idiosyncrasies of bad MS products.  I can also try to remember
to edit the Subject line, to shorten it - but that will mess up sorting
messages by Subject. Another alternative is, sad to say, using the Delete
key on posts from Drew.

Another problem I noticed with Outlook, BTW, is that even if I set the
format explicitly to "plain text", when I reply to a Unicode post the result
appears formatted. In that case, at least, I found a workaround (provided I
notice it in time): explicitly change the encoding of the message from
Unicode.

On a related subject: Unlike the posts to emacs-devel, bug reports get the
original sender's email address (e.g. "[drew.adams@oracle.com]") prepended
to the subject line, as in this one (but I removed that). That makes the
subject much longer (m u c h  longer, in some cases). Is that "feature"
really necessary or a good idea?

Re: bad mailer Subject meddling (was: links in Help buffer aren't always correct)

[Alfred M. Szmidt]

   If it produces brain-dead subject lines, but it is a very common mailer,
   maybe Rmail's C-c C-n could somehow deal with it by adding extra
   intelligence to handle the retarded output ;-)?  No flames please - I don't
   even know what C-c C-n does,

C-c C-n moves to the next message with the same subject.  What would
be nice is if C-c C-n (and C-c C-p) would move thread-wise based on
Message-ID, and then based on the subject.

   On a related subject: Unlike the posts to emacs-devel, bug reports get the
   original sender's email address (e.g. "[drew.adams@oracle.com]") prepended
   to the subject line, as in this one (but I removed that). That makes the
   subject much longer (m u c h  longer, in some cases). Is that "feature"
   really necessary or a good idea?

It happens when one forwards a message from rmail to someone (in this
case, emacs-devel).

Re: bad mailer Subject meddling (was: links in Help buffer aren't always correct)

[Richard M. Stallman]

Now is the wrong time to install new features,
but we could put this into a branch that we use for Rmail improvements,
if someone wants to implement it.

Re: bad mailer Subject meddling (was: links in Help buffer aren't always correct)

[Eli Zaretskii]

> From: "Alfred M\. Szmidt" <ams@gnu.org>
> Date: Thu, 15 Dec 2005 19:47:45 +0100
> Cc: emacs-devel@gnu.org
> 
> What would be nice is if C-c C-n (and C-c C-p) would move
> thread-wise based on Message-ID, and then based on the subject.

I think this would require a total rewrite of the current code;
patches welcome (although they probably won't be released with v22.1 ;-)

I committed small changes to C-c C-n just a few days ago to fix some
problems with following tricky subjects, like those which had "Re:"
not at the beginning, and those that are broken into multiple lines in
arbitrary places.

Re: bad mailer Subject meddling (was: links in Help buffer aren't always correct)

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Thu, 15 Dec 2005 07:39:25 -0800
> 
> Sorry, I don't know how to fix that in Outlook. I use Outlook 2000, for
> various reasons related to work. It's old, but still a very common (the most
> common?) email client in use. I don't defend it, but it's the one I use.

Perhaps you could try Emacs, if only for posting to Emacs-related
forums.

> If it produces brain-dead subject lines, but it is a very common mailer,
> maybe Rmail's C-c C-n could somehow deal with it by adding extra
> intelligence to handle the retarded output ;-)?

I thought about that, but eventually rejected the idea: it could cause
too many errors due to wrong matches.

> I don't even know what C-c C-n does

It finds the next message with the same subject.

> On a related subject: Unlike the posts to emacs-devel, bug reports get the
> original sender's email address (e.g. "[drew.adams@oracle.com]") prepended
> to the subject line

That's how Emacs formats forwarded messages.

Re: [drew.adams@oracle.com: links in Help buffer aren'talwayscorrect]

[Richard M. Stallman]

	describe-frame-parameter seems to work usefully, but it has one
	problem: its completion list is incomplete.

    Do you mean because it iterates only over the parameters of the selected
    frame?

I wasn't sure exactly what it does, but it certainly omits many
standard frame parameter names.  I don't think whether the selected
frame has a setting for a particular frame parameter ought to affect
whether I can complete its name.

    It might also include user-defined parameters that won't be documented in
    Info. Perhaps it should instead iterate over an explicit list of all of the
    Info-documented (built-in) frame parameters.

I think that is the best thing to do.  Or else get that from the
manual too.

Re: [drew.adams@oracle.com: links in Help buffer aren'talwayscorrect]

[Kevin Rodgers]

[-- Attachment #1: Type: text/plain, Size: 1689 bytes --]

Richard M. Stallman wrote:
> 	describe-frame-parameter seems to work usefully, but it has one
> 	problem: its completion list is incomplete.
> 
>     Do you mean because it iterates only over the parameters of the selected
>     frame?
> 
> I wasn't sure exactly what it does, but it certainly omits many
> standard frame parameter names.  I don't think whether the selected
> frame has a setting for a particular frame parameter ought to affect
> whether I can complete its name.
> 
>     It might also include user-defined parameters that won't be documented in
>     Info. Perhaps it should instead iterate over an explicit list of all of the
>     Info-documented (built-in) frame parameters.
> 
> I think that is the best thing to do.  Or else get that from the
> manual too.

OK, the attached version addresses all the points that have been raised:

* It defines a global list of documented frame parameters, which is
   initialized from the manual (using info, not Info-goto-node), and
   which can be augmented with user-defined parameters.

* The global list is actually an alist mapping parameters to their doc
   strings, so the doc strings are only extracted once from the manual
   and cached there.

* Completion uses the union of the documented frame parameters and any
   other parameters set in the selected frame.  The symbol at point is
   only provided as a default if it's a member of that union.

* The Info xrefs and indentation have been removed from the doc string,
   and it's been reformatted (filled) to account for that.

* Like variables, undocumented frame parameters are described as "not
   documented" and there's no link to the manual.

Enjoy!
-- 
Kevin

[-- Attachment #2: describe-frame-parameter.el --]
[-- Type: application/emacs-lisp, Size: 4265 bytes --]

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel