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

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

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

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]

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

[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

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

[Kevin Rodgers]

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

"Richard M. Stallman" <rms@gnu.org> wrote:
> It looks like this code extracts the list of frame parameter names
> when it is _loaded_.  That is inconvenient.  Could you 
> do that when the function is called for the first time?
...
> replace-regexp is meant for users; could you please write a simple
> while loop instead?

Sure, this version fixes both concerns.
-- 
Kevin

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com 

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 2803423440-describe-frame-parameter.el --]
[-- Type: text/x-emacs-lisp; name="describe-frame-parameter.el", Size: 4608 bytes --]

(defvar frame-parameter-docstring-alist nil
  "List of (PARAMETER . DOC-STRING) associations.")

(defun default-frame-parameter-docstring-alist ()
  "Return the default value of `frame-parameter-docstring-alist'."
  (save-excursion
    (save-window-excursion
      (let ((alist '())
            (pop-up-frames nil))
        (info "(elisp)Window Frame Parameters")
        (goto-char (point-min))
        (while (re-search-forward "^`\\(\\sw\\(?:\\sw\\|\\s_\\)*\\)'$" nil t)
          (let* ((parameter (intern (match-string 1)))
                 (infostring
                  (buffer-substring (1+ (point))
                                    (1- (or (re-search-forward "^`" nil t)
                                            (point-max)))))
                 (case-fold-search t)
                 (xref-regexp
                  "\\(?: (\\|; see \\)?\\*note[ \t\n]*\\(?:[^:]*\\)::[).]")
                 (xref-or-indent-regexp
                  (format "\\(%s\\)\\|\\(\n +\\)" xref-regexp))
                 (docstring
                  ;; delete Info xrefs and indentation, then reformat:
                  (with-temp-buffer
                    (insert infostring)
                    (goto-char (point-min))
                    (while (re-search-forward xref-or-indent-regexp nil t)
                      (cond ((and (match-beginning 1) (match-end 1))
                             (replace-match "" t t))
                            ((and (match-beginning 2) (match-end 2))
                             (replace-match "\n" t t))))
                    (fill-region (point-min) (point-max))
                    (buffer-string))))
            (setq alist
                  (cons (cons parameter docstring)
                        alist))
            ;; move to matched backquote at bol:
            (backward-char 1)))
        (nreverse alist)))))

(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))
          ;; in Emacs 21.4 there are 41 documented frame parameters; 83
          ;; is the smallest prime that's at least twice that:
          (param-table (let ((table (make-vector 83 0)))
                         (mapc (lambda (assoc)
                                 (intern (symbol-name (car assoc)) table))
                               (or frame-parameter-docstring-alist
                                   (setq frame-parameter-docstring-alist
                                         (default-frame-parameter-docstring-alist))))
                         (mapc (lambda (assoc)
                                 (intern (symbol-name (car assoc)) table))
                               (frame-parameters nil))
                         table))
          (param-name
           (progn
             ;; make sure the default is a frame parameter:
             (setq default-param
                   (intern-soft (symbol-name default-param) param-table))
             ;; complete on both documented frame parameters and
             ;; user-defined parameters that may be set:
             (completing-read (if default-param
                                  (format "Describe parameter (default %s): "
                                          default-param)
                                "Describe parameter: ")
                              param-table
                              nil 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")
    (let ((value (frame-parameter frame parameter))
          (docstring (cdr (assq parameter frame-parameter-docstring-alist))))
      (with-output-to-temp-buffer "*Help*"
        (prin1 parameter)
        (princ "'s value is ")
        (terpri)
        (with-current-buffer standard-output
          (let ((from (point)))
            (pp value)
            ;; (help-xref-on-pp from (point))
            (if (< (point) (+ from 20))
                (save-excursion
                  (goto-char from)
                  (delete-char -1)))))
        (terpri)
        (terpri)
        (princ "Documentation:")
        (terpri)
        (if docstring
            (princ docstring)
          (princ "not documented as a frame parameter."))))))

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

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

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

[Kevin Rodgers]

"Richard M. Stallman" <rms@gnu.org> wrote:
> Could you please send the change log entry?

Of course, sorry about that:

2005-12-19  Kevin Rodgers  <ihs_4664@ihs.com>

	* help.el (describe-frame-parameter): New command.
	(frame-parameter-docstring-alist): New variable.
	(default-frame-parameter-docstring-alist): New function.


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com 

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

[Kevin Rodgers]

Kevin Rodgers wrote:
 > "Richard M. Stallman" <rms@gnu.org> wrote:
 >
 >>It looks like this code extracts the list of frame parameter names
 >>when it is _loaded_.  That is inconvenient.  Could you
 >>do that when the function is called for the first time?
 >
 > ...
 >
 >>replace-regexp is meant for users; could you please write a simple
 >>while loop instead?
 >
 >
 > Sure, this version fixes both concerns.

According to Stefan, the following can be simplified in Emacs 22:

 >           ;; in Emacs 21.4 there are 41 documented frame parameters; 83
 >           ;; is the smallest prime that's at least twice that:
 >           (param-table (let ((table (make-vector 83 0)))
 >                          (mapc (lambda (assoc)
 >                                  (intern (symbol-name (car assoc)) 
table))
 >                                (or frame-parameter-docstring-alist
 >                                    (setq frame-parameter-docstring-alist
 > 
(default-frame-parameter-docstring-alist))))
 >                          (mapc (lambda (assoc)
 >                                  (intern (symbol-name (car assoc)) 
table))
 >                                (frame-parameters nil))
 >                          table))

To just:

           (param-table
            (mapcar (lambda (assoc) (symbol-name (car assoc)))
                    (nconc (frame-parameters nil)
                           (or frame-parameter-docstring-alist
                               (setq frame-parameter-docstring-alist
 
(default-frame-parameter-docstring-alist))))))

-- 
Kevin

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

[Stefan Monnier]

> According to Stefan, the following can be simplified in Emacs 22:

And if not, I think it deserves a bug report,


        Stefan

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

[Kevin Rodgers]

Another small simplification:

 >                  (xref-or-indent-regexp
 >                   (format "\\(%s\\)\\|\\(\n +\\)" xref-regexp))
...
 >                     (while (re-search-forward xref-or-indent-regexp 
nil t)
 >                       (cond ((and (match-beginning 1) (match-end 1))
 >                              (replace-match "" t t))
 >                             ((and (match-beginning 2) (match-end 2))
 >                              (replace-match "\n" t t))))

could be:

                  (xref-or-indent-regexp
                   (concat xref-regexp "\\|^ +"))
...
                     (while (re-search-forward xref-or-indent-regexp nil t)
                       (replace-match "" t t)

-- 
Kevin

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

[Eli Zaretskii]

> From: Kevin Rodgers <ihs_4664@yahoo.com>
> Date: Fri, 23 Dec 2005 10:07:02 -0700
> 
> Another small simplification:
> 
>  >                  (xref-or-indent-regexp
>  >                   (format "\\(%s\\)\\|\\(\n +\\)" xref-regexp))
> ...
>  >                     (while (re-search-forward xref-or-indent-regexp 
> nil t)
>  >                       (cond ((and (match-beginning 1) (match-end 1))
>  >                              (replace-match "" t t))
>  >                             ((and (match-beginning 2) (match-end 2))
>  >                              (replace-match "\n" t t))))
> 
> could be:
> 
>                   (xref-or-indent-regexp
>                    (concat xref-regexp "\\|^ +"))
> ...
>                      (while (re-search-forward xref-or-indent-regexp nil t)
>                        (replace-match "" t t)

Could you please send "diff -c" or "diff -u" style patches instead?
It is a PITA to apply such changes by hand, and on top of that, manual
patching runs a greater risk of introducing bugs.

TIA