Documentation for ido-mode is not very enlightening

Documentation for ido-mode is not very enlightening

[era]

This is the text of a bug which I filed against Ubuntu originally.
See https://bugs.launchpad.net/ubuntu/+source/emacs22/+bug/180130
The Ubuntu emacs22 maintainer suggested I report it here instead.
Sorry if this ends up with duplicates or something.

Here's the documentation string for the function "ido-mode":

  ido-mode is a variable defined in `ido.el'.
  Its value is nil

  Documentation:
  Determines for which functional group (buffer and files) ido behavior
  should be enabled. The following values are possible:
  - `buffer': Turn only on ido buffer behavior (switching, killing,
    displaying...)
  - `file': Turn only on ido file behavior (finding, writing, inserting...)
  - `both': Turn on ido buffer and file behavior.
  - `nil': Turn off any ido switching.

  Setting this variable directly does not take effect;
  use either M-x customize or the function `ido-mode'.

  You can customize this variable.

  [back]

Browsing the source file ido.el (provided you have the elisp source
package installed) reveals a lengthy commentary about what this mode
does and how to invoke it .... in comments. It would be beneficial if
this description could be available directly or indirectly as
user-accessible documentation.


In GNU Emacs 22.1.1 (i486-pc-linux-gnu, GTK+ Version 2.12.0)
 of 2007-11-06 on terranova, modified by Ubuntu
Windowing system distributor `The X.Org Foundation', version 11.0.10300000
configured using `configure  '--build' 'i486-linux-gnu' '--host' 'i486-linux-gnu' '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib' '--localstatedir=/var' '--infodir=/usr/share/info' '--mandir=/usr/share/man' '--with-pop=yes' '--enable-locallisppath=/etc/emacs22:/etc/emacs:/usr/local/share/emacs/22.1/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/22.1/site-lisp:/usr/share/emacs/site-lisp:/usr/share/emacs/22.1/leim' '--with-x=yes' '--with-x-toolkit=gtk' 'build_alias=i486-linux-gnu' 'host_alias=i486-linux-gnu' 'CFLAGS=-DDEBIAN -DSITELOAD_PURESIZE_EXTRA=5000 -g -O2''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_DK.UTF-8
  locale-coding-system: utf-8
  default-enable-multibyte-characters: t

Major mode: Text

Minor modes in effect:
  display-time-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  unify-8859-on-encoding-mode: t
  utf-translate-cjk-mode: t
  auto-compression-mode: t
  line-number-mode: t

Recent input:
<help-echo> C-x b 0 0 <tab> <backspace> <backspace> 
C-g C-x C-f . e m <tab> . <tab> a u <tab> <return> 
<down> <down> <down> v <escape> x g l o <tab> s e <tab> 
<return> C-c C-f f i n d - f i l e - a <tab> <return> 
C-x ( C-x C-g C-x ( C-c C-f <return> C-x b <return> 
<down> <down> C-x ) C-x e <escape> 0 C-x e C-x k <return> 
C-x k <return> C-x 4 b e m <tab> <return> C-x 5 b 0 
0 <tab> <return> <switch-frame> <switch-frame> <switch-frame> 
<switch-frame> <escape> x r e p o r t - e m <tab> 
<return>

Recent messages:
Starting new Ispell process...
Note: file is write protected
uncompressing morse.el.gz...done
Note: file is write protected [2 times]
uncompressing ido.el.gz...done
Note: file is write protected [2 times]
uncompressing README.gz...done
Note: file is write protected [2 times]
line-move-1: End of buffer
Loading emacsbug...done

Re: Documentation for ido-mode is not very enlightening

[martin rudalics]

 > Here's the documentation string for the function "ido-mode":
 >
 >   ido-mode is a variable defined in `ido.el'.

Hmmm... This is the doc-string for the _variable_ `ido-mode'.
Please try C-h f RET ido-mode RET instead.

Re: Documentation for ido-mode is not very enlightening

[era eriksson]

martin rudalics <rudalics <at> gmx.at> writes:
>  > Here's the documentation string for the function "ido-mode":
>  >
>  >   ido-mode is a variable defined in `ido.el'.
> 
> Hmmm... This is the doc-string for the _variable_ `ido-mode'.
> Please try C-h f RET ido-mode RET instead.

Right you are.  That does not change the fundamental problem: if you don't know
what ido-mode is, it won't help you find out.

  ido-mode is an interactive autoloaded Lisp function in `ido'.
  (ido-mode &optional arg)

  Toggle ido speed-ups on or off.
  With arg, turn ido speed-up on if arg is positive, off otherwise.
  Turning on ido-mode will remap (via a minor-mode keymap) the default
  keybindings for the `find-file' and `switch-to-buffer' families of
  commands to the ido versions of these functions.
  However, if arg arg equals 'files, remap only commands for files, or
  if it equals 'buffers, remap only commands for buffer switching.
  This function also adds a hook to the minibuffer.

What's an "ido speed-up"?  What are "ido versions" of the find-file functions? 
If you are terminally curious, you might try it out, but you should not assume
your users have indefinite time and patience.  For many users, the amount of
modes and features you could try out at one point or another is overwhelming,
and those with obscure or hard-to-find features are going to go undiscovered by
most users, and waste the time of many who try them out only to find the
features are not useful to them.

Even just the following very brief introduction from the beginning of the
"Comments" section in the ido.el source would help a lot:

  Ido - interactive do - switches between buffers and opens files and
  directories with a minimum of keystrokes. 

Like I wrote in my original report, it would be even better if the entire
comments section of the source file could be turned into documentation.  It's
fairly detailed and comprehensive.

/* era */

-- 
If this were a real .signature, it would suck less.  Well, maybe not.

Re: Documentation for ido-mode is not very enlightening

[martin rudalics]

 > What's an "ido speed-up"?  What are "ido versions" of the find-file functions?
 > If you are terminally curious, you might try it out, but you should not assume
 > your users have indefinite time and patience.  For many users, the amount of
 > modes and features you could try out at one point or another is overwhelming,
 > and those with obscure or hard-to-find features are going to go undiscovered by
 > most users, and waste the time of many who try them out only to find the
 > features are not useful to them.
 >
 > Even just the following very brief introduction from the beginning of the
 > "Comments" section in the ido.el source would help a lot:
 >
 >   Ido - interactive do - switches between buffers and opens files and
 >   directories with a minimum of keystrokes.
 >
 > Like I wrote in my original report, it would be even better if the entire
 > comments section of the source file could be turned into documentation.  It's
 > fairly detailed and comprehensive.

Sorry, I don't use ido and don't know what it does.  I fully agree with
your remarks but am afraid that the Emacs development team doesn't have
the necessary ressources to fill your needs.

How about writing a patch giving all the details you consider essential?
You could try copying the style of a minor mode you like and whose
doc-string you consider adequate.  You might even consider writing an
Info node for this - I think Kim would agree and give you any help you
need.

Re: Documentation for ido-mode is not very enlightening

[Jason Rumney]

era eriksson wrote:
> Like I wrote in my original report, it would be even better if the entire
> comments section of the source file could be turned into documentation.  It's
> fairly detailed and comprehensive.
>   
C-h p ("Find Emacs Packages" on the Help menu) does that.

Re: Documentation for ido-mode is not very enlightening

[era eriksson]

Jason Rumney <jasonr <at> gnu.org> writes:
> era eriksson wrote:
> > Like I wrote in my original report, it would be even better if the entire
> > comments section of the source file could be turned into documentation.  It's
> > fairly detailed and comprehensive.
> >   
> C-h p ("Find Emacs Packages" on the Help menu) does that.

With all due respect, even finding ido-mode in there proved to be harder than I
would normally be willing to spend on a researching a mode I don't have any idea
about.  The use case "user would benefit from this functionality and goes
looking for something like it" might be served by Finder, but I'm arguing for
the use case "user comes across a comment about this weirdly named mode, and
idly wonders what it does".

I hadn't realized that Finder actually extracts the Commentary into proper
human-readable documentation, though; thanks for the tip.  Now if only that
could be linked from the mode help maybe ...?

Anyhow, on a Debian-based system, the .el sources are even somewhat unlikely to
be installed; the Ubuntu emacs22 base installation doesn't "recommend" or even
"suggest" the emacs22-el add-on package which contains the elisp files.  (I
believe the situation is similar on Debian itself.)

/* era */

-- 
If this were a real .signature, it would suck less.  Well, maybe not.

Re: Documentation for ido-mode is not very enlightening

[Stefan Monnier]

> Anyhow, on a Debian-based system, the .el sources are even somewhat
> unlikely to be installed; the Ubuntu emacs22 base installation doesn't
> "recommend" or even "suggest" the emacs22-el add-on package which
> contains the elisp files.  (I believe the situation is similar on
> Debian itself.)

Please report this as a bug (to Ubuntu and/or Debian).


        Stefan

Re: Documentation for ido-mode is not very enlightening

[era eriksson]

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
> > Anyhow, on a Debian-based system, the .el sources are even somewhat
> > unlikely to be installed; the Ubuntu emacs22 base installation doesn't
> > "recommend" or even "suggest" the emacs22-el add-on package which
> > contains the elisp files.  (I believe the situation is similar on
> > Debian itself.)
> 
> Please report this as a bug (to Ubuntu and/or Debian).

Seems I was sloppy; the emacs22-common package on Ubuntu does Suggest: emacs22-el

The user might still opt not to install the elisp files, but I guess more and
more packaging tools are installing even suggested packages by default.

(For those unfamiliar with Debian's and thus Ubuntu's dependency handling, there
are three levels, from Depends: through Recommends: to Suggests: going from
unconditional to informational -- the Debian Policy documents this in more
detail; http://www.debian.org/doc/debian-policy/ch-relationships.html

You can examine Debian's package dependencies on-line starting e.g. at
http://packages.debian.org/sid/emacs22-common if you are interested.)

You could still argue that there ought to be some sort of wrapper for the Finder
so that users are made aware that they lack a dependency if they don't have the
.el files, but I digress already.

/* era */

-- 
If this were a real .signature, it would suck less.  Well, maybe not.

Re: Documentation for ido-mode is not very enlightening

[Stefan Monnier]

> You could still argue that there ought to be some sort of wrapper for
> the Finder so that users are made aware that they lack a dependency if
> they don't have the .el files, but I digress already.

Yes, you could report this as a bug to Debian: when using
a functionality that requires the .el files (like jumping to the source
file or using finder-commentary), catch the error and replace it with
a message explaining that the user needs to install the
emacs*-el package.


        Stefan

RE: Documentation for ido-mode is not very enlightening

[Drew Adams]

> > You could still argue that there ought to be some sort of 
> > wrapper for the Finder so that users are made aware that
> > they lack a dependency if
> > they don't have the .el files, but I digress already.
> 
> Yes, you could report this as a bug to Debian: when using
> a functionality that requires the .el files (like jumping to 
> the source
> file or using finder-commentary), catch the error and replace it with
> a message explaining that the user needs to install the
> emacs*-el package.

Maybe the byte-compiler should preserve the Commentary, since some runtime
code depends on it? ;-) 

Half-kidding. There's also a large variation in the amount and quality of
Commentary doc. This feature is of only limited value.

Re: Documentation for ido-mode is not very enlightening

[Stefan Monnier]

>> > You could still argue that there ought to be some sort of 
>> > wrapper for the Finder so that users are made aware that
>> > they lack a dependency if
>> > they don't have the .el files, but I digress already.
>> 
>> Yes, you could report this as a bug to Debian: when using
>> a functionality that requires the .el files (like jumping to 
>> the source
>> file or using finder-commentary), catch the error and replace it with
>> a message explaining that the user needs to install the
>> emacs*-el package.

> Maybe the byte-compiler should preserve the Commentary, since some runtime
> code depends on it? ;-) 

> Half-kidding. There's also a large variation in the amount and quality of
> Commentary doc. This feature is of only limited value.

If by "this feature" you mean finder-commentary, I somewhat agree.
But the feature to jump to the source code OTOH is very important to
encourage people to contribute.


        Stefan

RE: Documentation for ido-mode is not very enlightening

[Drew Adams]

> > Maybe the byte-compiler should preserve the Commentary, 
> > since some runtime code depends on it? ;-) 
> 
> > Half-kidding. There's also a large variation in the amount 
> > and quality of Commentary doc. This feature is of only limited value.
>
> If by "this feature" you mean finder-commentary, I somewhat agree.
> But the feature to jump to the source code OTOH is very important to
> encourage people to contribute.

I agree.

I meant only that it is not an ideal substitute for doc in another form, and
that YMMV in terms of the helpfulness of a particular Commentary.

I also think that it's useful to put :link '(emacs-commentary-link LIBRARY)
in  defcustom's, defgroup's, and defface's. That's another way to give users
a way to get to the Commentary (it uses finder-commentary). And a developer
who takes the trouble of adding such a :link is likely to spend more time
trying to make the Commentary useful.

This is is why I was only half-kidding. Ideally, a runtime command such as
finder-commentary would have everything it needs, even from a byte-compiled
file. But I agree that a simple error message is probably TRT thing now, if
the source file is missing.

Another area for possible improvement might be some rudimentary Commentary
navigation and other commands (keys) in Finder mode. `finder-select' could
also be improved a bit perhaps. And we might even want to come up with some
guidelines for writing Commentary that would facilitate using Finder mode.

Not a high priority, but maybe something to think about in our spare time.
;-) It is definitely true that useful info is often in the source-code
Commentary. Ido mode is apparently one example.