RE: Icicles stealing keybindings

[Drew Adams <drew.adams@oracle.com>]

> > See the Icicles doc, section... (wait for it)... `Key Bindings'.
> 
> OK, understood.  I'll do my homework next time.
> 
> Now the question is: where is the manual?  I hit C-h i m Icicles RET
> and nothing happens.  I know of no other places to look for manuals...
> (ESR would get heart attack.)

Sorry, I have not written a TexInfo manual.  The (`finder-mode') doc
is  available anytime in Icicle mode using `M-?' from the minibuffer.
If you happen to have library `linkd.el' installed then this doc is
hyperlinked.  You can also consult it in files `icicles-doc[12].el'.

And you can (normally) also consult it on Emacs Wiki, at
http://www.emacswiki.org/Icicles.  I am told now that the wiki should
be back up soon - it has been down for maintenance for almost a month.

> Now, kidding aside: I use EmacsWiki as "the docs"; is there any
> better (e.g., offline) place?  (What you write below is not
> necessarily better for me, though I can live with it.)

"Better" is in the eye of the beholder. ;-)  The doc on Emacs Wiki
is pretty clear, I think.  It has the advantages of showing images
and being linked to other pages of the wiki.  Reading the doc in
Emacs has its own advantages, however, which I'm sure you're aware of.

> What would be great for me would be e.g. the docs in epub/mobi
> format, or at least a HTML file or a set of files, so that I can
> put it on my kindle and read while commuting. (In a pinch, a PDF
> would do, too.)

Sorry; someone other than I will need to provide that.  That should
not be a big deal to implement, but I won't be the one to do it.
Perhaps you will someday be able to browse the Wiki with your Kindle.

> > Hit `M-?' from the minibuffer, then click the link `[Icicles Doc,
> > Part 2]'.  If Emacs Wiki were not down currently then I would
> > point you also to http://www.emacswiki.org/Icicles_-_Key_Bindings
> > (I think that's the URL).
> 
> Wow.  I did what you wrote here, and found myself in a strange place
> called *Finder-package*.  I did C-h m, then jumped to the source
> file for that strange mode (C-h m told me that it was about package
> docs) and found out, that it was written by ESR himself.  I don't
> know what to make of it now...

`finder.el' is quite old.  It is possible that only I use it for doc.

Among other things, it presents the `Commentary' section of a file
in a form that is easy to read and navigate.  I put the full doc in 
`Commentary', so you have it available as part of the source code.
The ability to use `finder-mode' with it comes for free.

The `finder'-accessed doc of some of my libraries, such as Icicles
and Bookmark+, also provides for navigation using simple hyperlinks
provided by library `linkd.el', if you happen to have that installed.

> > It is trivial to remove that binding for Icicles or to assign a
> > different binding.  Again: option `icicle-top-level-key-bindings'.
> 
> Great, I didn't know about this option.
> 
> > You don't have to reinvent anything.  You just need to decide
> > what works for you.  Different people use different libraries
> > that might lead to different key conflicts.  And different
> > people have different preferences wrt keys.  It's up to you
> > what bindings you use.
> 
> Obviously.  I just thought someone had some experience.  There are
> bad keybindings, good ones and better ones.  I didn't want to use
> inferior ones.  And Icicles is so huge, I even don't know exactly
> what I need (since I don't know what's out there).

You can start with the default Icicles keybindings.  A fair amount
of thought and experience are behind them.  In general they do not
trample on existing key bindings.  (Binding `C-x SPC' is an
exception, now that it has been appropriated for vanilla Emacs.)

But everyone's needs and preferences are different, so you might
well want to change some of the default bindings.  I think it is
better to start from the defaults than to start from zero (e.g.,
`icicle-top-level-key-bindings' = ()), but it's certainly possible
to feel that doing that makes Icicles too alien or intrusive.

> > Sorry for your trouble.  Please spend a few minutes with
> > `Key Bindings' in the doc, and I think you might feel better.
> 
> It's not you who should be sorry.  (Though I miss an Info manual,
> frankly speaking.  They are so good.  It's not that they are old and
> bad and browsers are new and good.  It's that browsers are not yet at
> this technological level as the Info reader. ;-))

FWIW, I agree.  Info can be improved, of course, and there is
talk now in emacs-devel@gnu.org of trying to do so (make it more
usable in connection with proportional fonts, make it usable by
typical web browsers, etc.).  If you can, and you would like to,
help with that incipient effort, everyone would appreciate it.

[Normally, I would just point you to the email thread about this
for emacs-devel@gnu.org.  Unfortunately, this discussion has been
going on since 2014-12-05, and has ranged far afield.  The original
thread has branched a few times, and even when it has not branched
it has wandered all around Robinson's barn.  Anyway, if you are
interested, this is the starting point of the discussion:
http://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00347.html
And this is the latest message, as of today:
http://lists.gnu.org/archive/html/emacs-devel/2015-01/msg00025.html]

But the thing that is most important for the Emacs docs (and for
any doc) is the *content* - complete & correct (but also readable,
of course).  There too, there is always room for improvement.

Fortunately, throughout its long history Emacs has had the benefit
of a few people who took doc seriously.  Starting with Emacs (the
"self-documenting editor") itself.  (Is Emacs a person?)  And RMS.
And Eli Zaretskii.

Young blood is sorely needed for this too - not because the old
farts are wrong or out-of-date or doing a poor job, but because
no one hangs in there forever.  (There is now a long list of
outstanding doc bugs.)

To "get" Emacs is to understand the usefulness and power of a
program that communicates with you about itself, that opens itself
freely and completely.  It includes understanding the importance
software freedom and of, yup, doc.

It is no accident that Emacs was the *starting point* and remains
at the core of the "free" approach to using and developing software.
And it is no accident that RMS concentrated so much of his energy
on its ability to talk to you about itself - its doc, in particular.