Re: proced-refine: confusing doc string

["Jim Blandy" <jimb@red-bean.com>]

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

On Sun, Sep 28, 2008 at 12:47 PM, Lennart Borgman (gmail)
<lennart.borgman@gmail.com> wrote:
> T. V. Raman wrote:
>> The proced-refine command has the following  as part of its doc
>> string:
>>
>> <cite>
>> If point is on the attribute ATTR, this command compares the value of ATTR
>> of every process with the value of ATTR of the process at the position
>> of point.  One can select processes for which the value of ATTR is
>> \"less than\", \"equal\", and / or \"larger\" than ATTR of the process
>> point is on.
>>
>> </cite>
>>
>> The initial sentence talks about point being in the header, the
>> latter half talks about the  process that point is on. How can
>> point be in both places at once?
>
> Doesn't it mean the column ATTR (or however it is layed out, I do not know)?

It does --- but Raman is certainly not the only user reading it that
way.  Should the docstring be more explicit?  Attached is what would
make sense to me.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: jimb.proced-refine-doc.patch --]
[-- Type: text/x-diff; name=jimb.proced-refine-doc.patch, Size: 2037 bytes --]

It seems like there's no need to repeat details of proced-refine's
behavior in the proced-mode docstring.

The 'proced-refine' docstring should be clearer about exactly where
point needs to be.

The phrase 'at the position of point' is redundant; Emacs
documentation simply says, 'at point'.

2008-09-29  Jim Blandy  <jimb@red-bean.com>

	* proced.el (proced-mode, proced-refine): Doc fixes.

diff --git a/lisp/proced.el b/lisp/proced.el
--- a/lisp/proced.el
+++ b/lisp/proced.el
@@ -551,11 +551,9 @@ to change the sort scheme.  The current 
 to change the sort scheme.  The current sort scheme is indicated in the
 mode line, using \"+\" or \"-\" for ascending or descending sort order.
 
-An existing Proced listing can be refined by typing \\[proced-refine]
-with point on the attribute of a process.  If point is on the attribute ATTR,
-this compares the value of ATTR of every process with the value of ATTR
-of the process at the position of point.  See `proced-refine' for details.
-Refining an existing listing does not update the variable `proced-filter'.
+You can drop processes from the list based on their attribute
+values by typing \\[proced-refine].  See `proced-refine' for
+details.
 
 The attribute-specific rules for formatting, filtering, sorting, and refining
 are defined in `proced-grammar-alist'.
@@ -884,9 +882,9 @@ This list includes CPID unless OMIT-CPID
   "Refine Proced listing by comparing with the attribute value at point.
 Optional EVENT is the location of the Proced field.
 
-If point is on the attribute ATTR, this command compares the value of ATTR
-of every process with the value of ATTR of the process at the position
-of point.  One can select processes for which the value of ATTR is
+If point is on a process's value for the attribute ATTR, this command compares the value of ATTR
+of every process with the value of ATTR of the process at
+point.  One can select processes for which the value of ATTR is
 \"less than\", \"equal\", and / or \"larger\" than ATTR of the process
 point is on.