Using Emacs' help system

Using Emacs' help system

[deech]

Hi all,
I'm making a more concerted attempt to use the Emacs help system but ran into a case where I was forced to use Google. 

I wanted to get the character count in a region. At the `M-x apropos` prompt I tried all variations of `character`, `char`, `number` and `count` without results. A quick Google search showed that I needed `count-word-region`. My question is how could I have used the help system to get there? 

-deech

Re: Using Emacs' help system

[Dan Espen]

deech <aditya.siram@gmail.com> writes:

> Hi all,
> I'm making a more concerted attempt to use the Emacs help system but ran into a case where I was forced to use Google. 
>
> I wanted to get the character count in a region. At the `M-x apropos`
> prompt I tried all variations of `character`, `char`, `number` and
> count` without results. A quick Google search showed that I needed
> count-word-region`. My question is how could I have used the help
> system to get there?

You were looking for "character count".
Character doesn't work but count does.

I'd still expect Google to produce a better result.

-- 
Dan Espen

Re: Using Emacs' help system

[Chris F.A. Johnson]

On 2013-02-10, deech wrote:
> Hi all,
> I'm making a more concerted attempt to use the Emacs help system but ran into a case where I was forced to use Google. 
>
> I wanted to get the character count in a region. At the `M-x apropos` prompt I tried all variations of `character`, `char`, `number` and `count` without results. A quick Google search showed that I needed `count-word-region`. My question is how could I have used the help system to get there? 

  'M-x apropos region' gives 'count-lines-region' as one of the possibilities.

-- 
   Chris F.A. Johnson                          <http://cfajohnson.com>
   Author:                                     =======================
   Pro Bash Programming: Scripting the GNU/Linux Shell (2009, Apress)
   Shell Scripting Recipes: A Problem-Solution Approach (2005, Apress)

Re: Using Emacs' help system

[Aidan Gauland]

deech <aditya.siram@gmail.com> writes:
> I wanted to get the character count in a region. At the `M-x apropos`
> prompt I tried all variations of `character`, `char`, `number` and
> count` without results. A quick Google search showed that I needed
> count-word-region`. My question is how could I have used the help
> system to get there?

I think this is a case of obscure naming.  That function doesn't mention
in its docstring that it returns a character count as well.

–Aidan

Re: Using Emacs' help system

[Dan Espen]

Aidan Gauland <aidalgol@no8wireless.co.nz> writes:

> deech <aditya.siram@gmail.com> writes:
>> I wanted to get the character count in a region. At the `M-x apropos`
>> prompt I tried all variations of `character`, `char`, `number` and
>> count` without results. A quick Google search showed that I needed
>> count-word-region`. My question is how could I have used the help
>> system to get there?
>
> I think this is a case of obscure naming.  That function doesn't mention
> in its docstring that it returns a character count as well.>

Is that a typo above?
I find count-words, not count-word.

in 24.1.1 I see:

  count-words-region is an interactive compiled Lisp function.

  It is bound to M-=.

  (count-words-region START END)

  Count the number of words in the region.
  If called interactively, print a message reporting the number of
  lines, words, and chars in the region.
  If called from Lisp, return the number of words between positions
  START and END.

Seems to mention characters.


-- 
Dan Espen

Re: Using Emacs' help system

[Aidan Gauland]

Dan Espen <despen@verizon.net> writes:
> Aidan Gauland <aidalgol@no8wireless.co.nz> writes:
>> I think this is a case of obscure naming.  That function doesn't mention
>> in its docstring that it returns a character count as well.
>
> in 24.1.1 I see:
>
>   count-words-region is an interactive compiled Lisp function.
>
>   It is bound to M-=.
>
>   (count-words-region START END)
>
>   Count the number of words in the region.
>   If called interactively, print a message reporting the number of
>   lines, words, and chars in the region.
>   If called from Lisp, return the number of words between positions
>   START and END.
>
> Seems to mention characters.

Oh, so it does.  Guess it was a case of user error. :)

RE: Using Emacs' help system

[Drew Adams]

> > I wanted to get the character count in a region.
> > A quick Google search showed that I needed
> > count-word-region`.  My question is how could I have
> > used the help system to get there?
> 
> I think this is a case of obscure naming.

Bad naming, I'd say.  It wouldn't hurt to at least create alias commands with
"characters" (or "chars") and "lines" in the names: `count-chars-region',
`count-lines-region'.

Oh, guess what?  There is an alias `count-lines-region' (but none for chars).
Why for lines?  Not because someone thought it would be a good idea to create
such an alias.

No, the alias for lines is there only because `count-lines-region' was the
original command (goes way back), and it's now been declared obsolete.  As long
as it is still supported it has the right to an alias.

It also wouldn't hurt Emacs Lisp to have functions that did just those things,
returning the count of chars and lines, respectively.  `count-word-region'
always returns the number of words.  This is a false economy.

FWIW, I've had a command `count-chars-in-region' for years (long before
`count-words-region), which I use also in Lisp.  And I've always had an alias
for it: `region-length'.

Why the alias?  Again, discoverability - depends on how you are thinking about
things.  (We don't have a function named `count-elements-list' - we call the
function `length'.)

> That function doesn't mention in its docstring that it
> returns a character count as well.

The command name doesn't tell you that it counts characters, but its doc string
does, actually:

,----
| count-words-region is an interactive compiled Lisp function in
| `simple.el'.
| 
| It is bound to M-=.
| 
| (count-words-region START END &optional ARG)
| 
| Count the number of words in the region.
| If called interactively, print a message reporting the number of
| lines, words, and characters in the region (whether or not the
                ^^^^^^^^^^^^^^
| region is active); with prefix ARG, report for the entire buffer
| rather than the region.
| 
| If called from Lisp, return the number of words between positions
| START and END.
`----

You might think that `C-h d character count' would find this command.  But it
does not, because "count" is only in the function name and "character" is only
in the doc string.

But even `C-h d character number' (the keyword order is not important) does not
work - I'm not sure why.  Someone will no doubt enlighten us.

However, using this regexp does work:

C-h d number\(.\|
\)*char

(That's a newline char after the |, inserted using `C-q C-j'.)

Bottom lines: (a) This is not a great doc string, at least from the point of
view of discoverability.  (b) A command name should reflect the action of
counting characters - e.g., an alias `count-chars-region'.

This too might help with this kind of search:
http://www.emacswiki.org/Icicles_-_A_Propos_d'Apropos#Documentation-AproposMulti
-Commands

Re: Using Emacs' help system

[Jambunathan K]

deech <aditya.siram@gmail.com> writes:

> Hi all,
> I'm making a more concerted attempt to use the Emacs help system but
> ran into a case where I was forced to use Google.
>
> I wanted to get the character count in a region. At the `M-x apropos`
> prompt I tried all variations of `character`, `char`, `number` and
> count` without results. A quick Google search showed that I needed
> count-word-region`. My question is how could I have used the help
> system to get there?

Three methods

C-h d count


C-h r
i count


C-h r
M-x icomplete-mode RET
I count

> -deech
>

-- 

Re: Using Emacs' help system

[Barry Margolin]

In article <mailman.19549.1360546899.855.help-gnu-emacs@gnu.org>,
 "Drew Adams" <drew.adams@oracle.com> wrote:

> The command name doesn't tell you that it counts characters, but its doc 
> string
> does, actually:

But apropos doesn't show the whole doc string, just the first line. 
Since neither the name nor the first line of documentation suggests that 
this would be the command he wants, he wouldn't have any reason to click 
on it to see the full doc.

-- 
Barry Margolin, barmar@alum.mit.edu
Arlington, MA
*** PLEASE post questions in newsgroups, not directly to me ***

RE: Using Emacs' help system

[Drew Adams]

> Three methods
> 
> C-h d count
> 
> C-h r
> i count
> 
> C-h r
> M-x icomplete-mode RET
> I count

Good suggestions.

But the `M-x icomplete-mode RET' is unnecessary/irrelevant for `I count RET'.
(And Icomplete does not show completions for `I count'.)


Perhaps you meant to say 4 methods, the 4th being this?

M-x icomplete-mode RET
M-x count

Which is essentially the same as `M-x count TAB', which shows only commands
starting with `count'.  (In this case, that's enough.)

Re: Using Emacs' help system

[Jambunathan K]

"Drew Adams" <drew.adams@oracle.com> writes:

>> Three methods
>> 
>> C-h d count
>> 
>> C-h r
>> i count
>> 
>> C-h r
>> M-x icomplete-mode RET
>> I count
>
> Good suggestions.
>
> But the `M-x icomplete-mode RET' is unnecessary/irrelevant for `I count RET'.
> (And Icomplete does not show completions for `I count'.)

It is amazing what `icomplete-mode' does to discoverability.

I have a gripe about icomplete-mode.  It talks to you only when you
key-in something.

> Perhaps you meant to say 4 methods, the 4th being this?
>
> M-x icomplete-mode RET
> M-x count
>
> Which is essentially the same as `M-x count TAB', which shows only commands
> starting with `count'.  (In this case, that's enough.)

It depends on what hat when one wears - a true explorer has no goal.
Everything he comes across just gets noted in his journal and gets
passed on.

Serendipity has it's own usefulness and benefits.

Re: Using Emacs' help system

[Jambunathan K]

> (And Icomplete does not show completions for `I count'.)

It does.

-- 

RE: Using Emacs' help system

[Drew Adams]

> > (And Icomplete does not show completions for `I count'.)
> 
> It does.

Not with emacs -Q and no other configuring, at least not in the latest MS
Windows build I have, from 2013-02-08.

Likewise for Emacs 24.2 and 23.4.  Likewise for Emacs 22.3 for `i' (there is no
`I' for Emacs 22).

emacs -Q
C-h r
M-x icomplete-mode RET ; turn it on
I count

No icompletions shown.
None shown no matter what input you type to `I'.

Re: Using Emacs' help system

[Jambunathan K]

"Drew Adams" <drew.adams@oracle.com> writes:

>> > (And Icomplete does not show completions for `I count'.)
>> 
>> It does.
>
> Not with emacs -Q and no other configuring, at least not in the latest MS
> Windows build I have, from 2013-02-08.
>
> Likewise for Emacs 24.2 and 23.4.  Likewise for Emacs 22.3 for `i' (there is no
> `I' for Emacs 22).
>
> emacs -Q
> C-h r
> M-x icomplete-mode RET ; turn it on
> I count
>
> No icompletions shown.
> None shown no matter what input you type to `I'.

The magic is in this snippet.

    (eval-after-load 'icomplete
      (setq icomplete-with-completion-tables t))

The option is so useful, it should be `t' by default.

RE: Using Emacs' help system

[Drew Adams]

> > The command name doesn't tell you that it counts 
> > characters, but its doc string does, actually:
> 
> But apropos doesn't show the whole doc string, just the first line. 
> Since neither the name nor the first line of documentation 
> suggests that this would be the command he wants, he wouldn't
> have any reason to click on it to see the full doc.

1. I've already agreed that both the command name and the doc string could be
improved (and I suggested how).

2. I specifically mentioned command `apropos-documentation' (`C-h d'), which
_does_ take the whole doc string into account, unlike `apropos',
`apropos-command' etc.

RE: Using Emacs' help system

[Drew Adams]

> >> > (And Icomplete does not show completions for `I count'.)
> >>
> >> It does.
> >
> > Not with emacs -Q and no other configuring, at least not in 
> > the latest MS Windows build I have, from 2013-02-08.
> >
> > Likewise for Emacs 24.2 and 23.4.  Likewise for Emacs 22.3 
> > for `i' (there is no `I' for Emacs 22).
> >
> > emacs -Q
> > C-h r
> > M-x icomplete-mode RET ; turn it on
> > I count
> >
> > No icompletions shown.
> > None shown no matter what input you type to `I'.
> 
> The magic is in this snippet.
>     (eval-after-load 'icomplete
>       (setq icomplete-with-completion-tables t))
> The option is so useful, it should be `t' by default.

1. Yes, I know about `icomplete-with-completion-tables', which is why I
mentioned "emacs -Q and no other configuring".  You mentioned no settings,
perhaps misleading folks who might otherwise be interested in your suggestion.

2. That "so useful option" is not an option (defcustom).  It is a defvar (a
supposedly "internal" variable).  (A nitpick, but someone might try `M-x
customize-option', so we might as well be accurate.)

3. As you know, I happen to agree that `t' should be the default value for
`icomplete-with-completion-tables'.  And it should be a user option.  At a
minimum, value `t' should be documented.  I filed an enhancement request/bug
report about it - so far, no response.
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11654
http://lists.gnu.org/archive/html/emacs-devel/2008-05/msg01841.html

4. All of this said, `M-x count TAB' shows you the same thing Icomplete shows
you.  Nothing magical here.  At best, after some configuration, Icomplete just
shows you the (same) available completions.  It simply shows them in the
minibuffer instead of the `*Completions*' window.

5. Being able to complete a command-name prefix is helpful only when the keyword
you try happens to be the prefix.  If the command were named `word-count-region'
instead of `count-words-region' and you tried `count' then you would be out of
luck.

Yes, there are some configurations (e.g. option `completion-styles') you can use
to get around that limitation too.  But it is a limitation all the same.  And if
you do work around it then it is not so quick to get back to only prefix
completion.

6. Apropos completion, and progressively narrowing the completion set, can help.
Not magic either, but useful.
http://www.emacswiki.org/emacs/EmacsNewbieWithIcicles#FindCommands

Re: Using Emacs' help system

[Oleksandr Gavenko]

On 2013-02-11, Jambunathan K wrote:

> The magic is in this snippet.
>
>     (eval-after-load 'icomplete
>       (setq icomplete-with-completion-tables t))
>
> The option is so useful, it should be `t' by default.

Interesting settings... I try on "M-x man" and "C-x C-f" and found that some
times *Completions* buffer more valuable then icomplete, but if there are only
a few suggestions then icomplete is better.

Seems that "eval-after-load" unnecessary in your snippet:

 * icomplete.el introduced is 1993 with ";;;autoload".
 * icomplete-with-completion-tables was added in 2006 as "defvar".

-- 
Best regards!