Re: Icicles stealing keybindings

[Marcin Borkowski]

On 2015-01-03, at 19:34, Drew Adams <drew.adams@oracle.com> wrote:

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

Well, for read-only access it sometimes works, sometimes not.

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

Yes, it's clear - but requires internet access.

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

Again: you don't need to be sorry!  I'll try to sit down and find the
right set of options for wget to download only the Icicles-related pages
from the wiki (I guess I could also leverage the fact that Emacs Wiki
runs on Oddmuse, which means I can easily get the list of all pages and
filter by the string "Icicles").  Then, converting to epub/mobi is easy
with calibri.

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

Wow.  That sounds really interesting.  So do I get it right that finder
just formats the docstrings and/or comments?  Wow.  I'll look into it
someday.

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

That's what I meant: I assume that the defaults are thought-out, and
don't want to mess with them until I know Icicles better.

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

See below.

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

I've read much of this thread.  It was fascinating, for some values of
"fascinating".

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

Yes, and see below, too.

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

Yes.  I consider this a huge advantage of Emacs.  (I've read most of the
Emacs manual, though it was 15 years ago or so, the "Elisp Intro", and
some parts of Elisp manual.)

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

Is it available somewhere online?

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

Those remarks are /very/ interesting.  I will share this with a few of
my friends and students.

Coming back to the "If you can, and you would like to, help with that
incipient effort, everyone would appreciate it" and "There too, there is
always room for improvement" parts, here are my thoughts.

I'd love to, especially with the docs.  (Also, possibly with coding,
though I'm only a hobbyist programmer.)  I like writing (and tinkering
with what I wrote).  (I don't want to boast too much, so I'l try to keep
the boasting part short: I have a blog updated weekly (currently mostly
about Emacs), I wrote two master's theses and one doctoral dissertation,
my first book (in English, on mathematics) is currently under peer
review, my second book (in Polish, on LaTeX, with a coauthor) is
currently being written, and I have plans to write a third one (again in
English).  So I guess that while I'm not G.K. Chesterton, still my
credentials as far as writing goes /might/ be above the median.)

I could even learn bzr, though now that Emacs is in git, it would be
much easier for me (especially with Magit).  I mean: this or that
versioning system isn't a big deal.

But - and this is a very big "but" - there is a huge barrier to entry,
in my case probably insurmountable.  The FSF copyright agreement.  Most
probably, I won't sign it /ever/, for various reasons.  One is that the
text of the agreement is not available online.  I strongly oppose such
anti-openness (and find it very strange, especially that FSF claims that
it is about openness), and may not sign it /just because of this/.
Another one is that I am not sure whether the agreement is even valid
under my jurisdiction.  (American and Polish - in general, European -
copyright laws are much different, though IANAL.)  Yet another one (much
less important) is that (assuming the ATM unlikely scenario that I leave
academia and start working in IT) I am not at all sure whether having
signed the FSF papers would not decrease my hiring chances.

Regards,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University