From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail
From: Jan Synacek <jsynacek@redhat.com>
Newsgroups: gmane.emacs.help
Subject: Documentation for overriding-terminal-local-map is confusing?
Date: Mon, 25 May 2020 10:49:47 +0200
Message-ID: <m6fsgfotn4k.fsf@jsynacek-ntb.brq.redhat.com>
Mime-Version: 1.0
Content-Type: text/plain
Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202";
	logging-data="38318"; mail-complaints-to="usenet@ciao.gmane.io"
To: help-gnu-emacs@gnu.org
Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Mon May 25 10:50:24 2020
Return-path: <help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org>
Envelope-to: geh-help-gnu-emacs@m.gmane-mx.org
Original-Received: from lists.gnu.org ([209.51.188.17])
	by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org>)
	id 1jd8oS-0009t3-JY
	for geh-help-gnu-emacs@m.gmane-mx.org; Mon, 25 May 2020 10:50:24 +0200
Original-Received: from localhost ([::1]:39588 helo=lists1p.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.90_1)
	(envelope-from <help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org>)
	id 1jd8oR-0005AR-Lc
	for geh-help-gnu-emacs@m.gmane-mx.org; Mon, 25 May 2020 04:50:23 -0400
Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42440)
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <jsynacek@redhat.com>)
 id 1jd8o4-0005A5-8C
 for help-gnu-emacs@gnu.org; Mon, 25 May 2020 04:50:00 -0400
Original-Received: from us-smtp-1.mimecast.com ([205.139.110.61]:48058
 helo=us-smtp-delivery-1.mimecast.com)
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
 (Exim 4.90_1) (envelope-from <jsynacek@redhat.com>)
 id 1jd8o3-0006tF-9k
 for help-gnu-emacs@gnu.org; Mon, 25 May 2020 04:49:59 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;
 s=mimecast20190719; t=1590396597;
 h=from:from:reply-to:subject:subject:date:date:message-id:message-id:
 to:to:cc:mime-version:mime-version:content-type:content-type;
 bh=9V8DlaSFaU7+N5Pom0zzokI6FUw+8YAt2yUBl+H3Pq4=;
 b=TM1Nwi+CYF8Oegg2Oc3LgXt5z0FJuBWhtCZLdZ/rWb1LIkZgV49ueRHGIw2OeYG439UZBB
 1kk59uY9Qs2kF+FE5SV8kTqNC3oblIqxgZkMuWeqAb1Oi8hGNwjKpFmT8ZmyXIPF/ESNgU
 kEf3Pc+4GteLM60rKYGMJgUDg5lFvmI=
Original-Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com
 [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id
 us-mta-308-I8miVK6ONV6avF75MXg-sQ-1; Mon, 25 May 2020 04:49:56 -0400
X-MC-Unique: I8miVK6ONV6avF75MXg-sQ-1
Original-Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com
 [10.5.11.12])
 (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))
 (No client certificate requested)
 by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 473AA1005510
 for <help-gnu-emacs@gnu.org>; Mon, 25 May 2020 08:49:55 +0000 (UTC)
Original-Received: from jsynacek-ntb.brq.redhat.com (unknown [10.40.192.181])
 by smtp.corp.redhat.com (Postfix) with ESMTPS id 2ECAB60CD0
 for <help-gnu-emacs@gnu.org>; Mon, 25 May 2020 08:49:51 +0000 (UTC)
X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12
X-Mimecast-Spam-Score: 0
X-Mimecast-Originator: redhat.com
Received-SPF: pass client-ip=205.139.110.61; envelope-from=jsynacek@redhat.com;
 helo=us-smtp-delivery-1.mimecast.com
X-detected-operating-system: by eggs.gnu.org: First seen = 2020/05/25 02:40:56
X-ACL-Warn: Detected OS   = Linux 2.2.x-3.x [generic] [fuzzy]
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=0.001,
 DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,
 RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001,
 SPF_PASS=-0.001 autolearn=_AUTOLEARN
X-Spam_action: no action
X-BeenThere: help-gnu-emacs@gnu.org
X-Mailman-Version: 2.1.23
Precedence: list
List-Id: Users list for the GNU Emacs text editor <help-gnu-emacs.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/help-gnu-emacs>,
 <mailto:help-gnu-emacs-request@gnu.org?subject=unsubscribe>
List-Archive: <https://lists.gnu.org/archive/html/help-gnu-emacs>
List-Post: <mailto:help-gnu-emacs@gnu.org>
List-Help: <mailto:help-gnu-emacs-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/help-gnu-emacs>,
 <mailto:help-gnu-emacs-request@gnu.org?subject=subscribe>
Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org
Original-Sender: "help-gnu-emacs"
 <help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org>
Xref: news.gmane.io gmane.emacs.help:123127
Archived-At: <http://permalink.gmane.org/gmane.emacs.help/123127>

Hello,

I currently have this piece of elisp in my init.el:
...
(setf jsynacek-terminal-map (make-sparse-keymap))
(setf overriding-terminal-local-map jsynacek-terminal-map)
(define-key jsynacek-terminal-map (kbd "C-b") 'ido-switch-buffer)
(define-key jsynacek-terminal-map (kbd "C-o") 'find-file)
...

It works until I use isearch-forward, which resets
overriding-terminal-local-map. It took me a while to figure out, until I
noticed this in "22.9 Controlling the Active Keymaps" in the ELisp
manual:

"This variable is always local to the current terminal and cannot be
buffer-local.  *Note Multiple Terminals::.  It is used to implement
incremental search mode."

That basically means that the keymap is pretty much useless for
overriding anything, doesn't it? Because it always gets reset whenever
the user starts searching for something. Also, the rest of the manual
that mentions overriding-terminal-local-map kind of suggests that it's
supposed to be used exactly how I wanted to use it - to make one's own
global keybindings that work no matter what the current modes are.

So my questions are:

1) Is this actually a "bug" in the manual? That is, shouldn't the manual
be changed to be clearer? If yes, I can file a bug report.

2) What is the proper way to make my own keymap that overrides
everything? I know that the 'use-package/bind-key' package does this by
creating a minor mode and then using emulation-mode-map-alists, but the
variable's documentation doesn't even remotely suggest to use it that
way.

Regards,
Jan