proced-refine: confusing doc string

proced-refine: confusing doc string

[T. V. Raman]

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?

-- 
Best Regards,
--raman

      
Email:  raman@users.sf.net
WWW:    http://emacspeak.sf.net/raman/
AIM:    emacspeak       GTalk: tv.raman.tv@gmail.com
PGP:    http://emacspeak.sf.net/raman/raman-almaden.asc
Google: tv+raman 
IRC:    irc://irc.freenode.net/#emacs

Re: proced-refine: confusing doc string

[Lennart Borgman (gmail)]

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

Re: proced-refine: confusing doc string

[Jim Blandy]

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

Re: proced-refine: confusing doc string

[T. V. Raman]

This would definitely help.

I'm still at a loss to understand how proced-refine works --
perhaps because I'm running outside X? 

It's unclear how this thing is supposed to work on a text console.

>>>>> "Jim" == Jim Blandy <jimb@red-bean.com> writes:
    Jim> On Sun, Sep 28, 2008 at 12:47 PM, Lennart Borgman
    Jim> (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)?
    Jim> 
    Jim> It does --- but Raman is certainly not the only user
    Jim> reading it that way.  Should the docstring be more
    Jim> explicit?  Attached is what would make sense to me.

-- 
Best Regards,
--raman

      
Email:  raman@users.sf.net
WWW:    http://emacspeak.sf.net/raman/
AIM:    emacspeak       GTalk: tv.raman.tv@gmail.com
PGP:    http://emacspeak.sf.net/raman/raman-almaden.asc
Google: tv+raman 
IRC:    irc://irc.freenode.net/#emacs

Re: proced-refine: confusing doc string

[Jim Blandy]

On Mon, Sep 29, 2008 at 7:30 PM, T. V. Raman <raman@users.sf.net> wrote:
> This would definitely help.
>
> I'm still at a loss to understand how proced-refine works --
> perhaps because I'm running outside X?
>
> It's unclear how this thing is supposed to work on a text console.

For what it's worth, I had the same reaction.  I didn't get it until I
read the code and stared at the little "-+-" strings...

To be honest, I'm not sure that proced-refine is a very helpful
command as designed.  For example: clicking on a pid restricts the
display to processes with lesser pids?  Why?  Why not greater pids?
It seems like its behavior was driven more by the idea for its
implementation than vice versa.

Re: proced-refine: confusing doc string

[T. V. Raman]

Humor me, I still dont get it.

What little "+" signs? Are they perhaps done as an overlay (will
go stare at the code next) -- note that I cant stare at the
screen:-)



>>>>> "Jim" == Jim Blandy <jimb@red-bean.com> writes:
    Jim> On Mon, Sep 29, 2008 at 7:30 PM, T. V. Raman
    Jim> <raman@users.sf.net> wrote:
    >> This would definitely help.
    >> 
    >> I'm still at a loss to understand how proced-refine works
    >> -- perhaps because I'm running outside X?
    >> 
    >> It's unclear how this thing is supposed to work on a text
    >> console.
    Jim> 
    Jim> For what it's worth, I had the same reaction.  I didn't
    Jim> get it until I read the code and stared at the little
    Jim> "-+-" strings...
    Jim> 
    Jim> To be honest, I'm not sure that proced-refine is a very
    Jim> helpful command as designed.  For example: clicking on a
    Jim> pid restricts the display to processes with lesser pids?
    Jim> Why?  Why not greater pids?  It seems like its behavior
    Jim> was driven more by the idea for its implementation than
    Jim> vice versa.

-- 
Best Regards,
--raman

      
Email:  raman@users.sf.net
WWW:    http://emacspeak.sf.net/raman/
AIM:    emacspeak       GTalk: tv.raman.tv@gmail.com
PGP:    http://emacspeak.sf.net/raman/raman-almaden.asc
Google: tv+raman 
IRC:    irc://irc.freenode.net/#emacs