GNU bug report logs - #8297
expand self-documentation to show where things are redefined, etc

Message received at 8297 <at> debbugs.gnu.org:

Received: (at 8297) by debbugs.gnu.org; 23 Mar 2011 08:59:48 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Mar 23 04:59:48 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Q2Jut-0005b0-8m
	for submit <at> debbugs.gnu.org; Wed, 23 Mar 2011 04:59:47 -0400
Received: from mo-p00-ob.rzone.de ([81.169.146.160])
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <fb@HIDDEN>) id 1Q2Jup-0005ai-68
	for 8297 <at> debbugs.gnu.org; Wed, 23 Mar 2011 04:59:44 -0400
DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; t=1300870777; l=2488;
	s=domk; d=streitblatt.de;
	h=Content-Transfer-Encoding:Content-Type:In-Reply-To:References:
	Subject:To:MIME-Version:From:Date:X-RZG-CLASS-ID:X-RZG-AUTH;
	bh=0TGQFAilRC9SaIw8aFdsPx3Nez0=;
	b=VYwSvx66db+I1uLUzxOfIMK6JD9RQXQZTbcFAKGQhjBDBeELQuG+b4Ld0LGTYJUZOAG
	Yf2VkZoqq0LYs/QW7UupD24Pry+08H1tArh8rvAlGl1HWxF1H0f2q0IZ+yPi6bPbY56Dt
	V5z1nl/saQKDXcoIdmtTYFIoBOVNcYS1jB8=
X-RZG-AUTH: :KmALZ0mpdbGonPxw7gDkop508XQjelhLxGYn4B74/jTNdrjLjuwMuuiy8j0BYXGgeN5xhQ==
X-RZG-CLASS-ID: mo00
Received: from [192.168.2.100] (p5499481F.dip.t-dialin.net [84.153.72.31])
	by post.strato.de (jimi mo5) (RZmta 25.8) with ESMTPA id Y02858n2N7icF5
	for <8297 <at> debbugs.gnu.org>; Wed, 23 Mar 2011 09:59:36 +0100 (MET)
Message-ID: <4D89B679.3030804@HIDDEN>
Date: Wed, 23 Mar 2011 09:59:37 +0100
From: Florian Beck <fb@HIDDEN>
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US;
	rv:1.9.2.14) Gecko/20110223 Thunderbird/3.1.8
MIME-Version: 1.0
To: 8297 <at> debbugs.gnu.org
Subject: Re: bug#8297: Request: Better Emacs self-documentation for
	customization
References: <4D854552.6000509@HIDDEN>
	<jwvtyewgn3a.fsf-monnier+emacs@HIDDEN>
In-Reply-To: <jwvtyewgn3a.fsf-monnier+emacs@HIDDEN>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Spam-Score: -4.6 (----)
X-Debbugs-Envelope-To: 8297
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/pipermail/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -3.9 (---)

On 03/21/2011 11:00 PM, Stefan Monnier wrote:

> Note that for your case, another option is to use a defadvice, and
> indeed defadvice should also add a hyperlink to the advice.

Right. So that one is not so urgent. It is only that I already have 
quite some redefined functions (from the emacs source or from 
third-party packages) and finding the original definition can be 
surprisingly difficult.

>
>>   - 'describe-variable', on the other hand, remembers the original
>> definition, but doesn't remember the place where I changed the value.
>
> That might turn out to be more difficult to track, but at least for some
> simple cases (e.g. when the vlue is changed via `custom' functions rather
> than via `setq') that should definitely be doable.  If the var was set
> via `setq' it's more difficult since `setq' is a very low-level
> primitive that needs to run fast.

Understood. Again, unfortunatly `setq' is what I have. Perhaps an 
old-fashioned but definitly valid way of customizing.

> But maybe we could somehow handle
> `setq' outside of functions in a special way (these shouldn't impact
> performance since they can't be in loops).

That would be great indeed.

>
>>   - `describe-key' only provides a link to the function, not to the place the
>> key was defined.
>
> That's also more difficult because OT1H `define-key' does not get much
> information (it can check load-file-name, but it doesn't know the line
> number, nor the name of the map it receives and neither does it know
> reliably what the key description looks like in the source file, so it's
> hard to do a regexp-search), and OTOH there's no place currently to
> store that information, tho I guess we could keep it in some side
> hash-table.

This one, on the other hand, is a major annoyance. Say, I use 
`global-set-key' to customize a key binding. I continue working with my 
emacs session, maybe for day. But the next time I start emacs, the 
binding is overwritten, because I defined the same key in some other file.

>
>> Obviously, this is not easy, because evaluations don't necessarily
>> have a fixed place and key bindings can be defined in many ways. Regardless,
>> I think this is something on which Emacs could improve.
>
> Agreed.  It's not high on my todo list, but I'll be happy to take
> patches for those.  For defadvice it should be pretty easy, and for
> function re-definitions it shouldn't be too hard either.
>
>
>          Stefan
>
>
>
>

Message received at 8297 <at> debbugs.gnu.org:

Received: (at 8297) by debbugs.gnu.org; 22 Mar 2011 06:59:39 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Mar 22 02:59:39 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Q1vZ4-0000iq-Mm
	for submit <at> debbugs.gnu.org; Tue, 22 Mar 2011 02:59:38 -0400
Received: from mail-ey0-f172.google.com ([209.85.215.172])
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <lennart.borgman@HIDDEN>) id 1Q1vZ1-0000ic-Vl
	for 8297 <at> debbugs.gnu.org; Tue, 22 Mar 2011 02:59:36 -0400
Received: by eye13 with SMTP id 13so1681037eye.3
	for <8297 <at> debbugs.gnu.org>; Mon, 21 Mar 2011 23:59:30 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;
	h=domainkey-signature:mime-version:in-reply-to:references:from:date
	:message-id:subject:to:cc:content-type:content-transfer-encoding;
	bh=8Hj/OYKvXPivK/I9mdBtNxa0LGluAwqoS7koxGSp07s=;
	b=nc6O/bdkqZKqxAg/XA4tAk+iYwP+AGvQF+F0Nwx4w8YS2VdzP0CUZn6EG3LmT/a5aT
	QKnxiKv5wnBap04WTM6etpHlN/jdEQkm/KdzHYM3ZoCQCmgb+1pv6i8lqzunBMFxMSP+
	Wxb2R3DIG16cVrgqGhuKAQnYx1aFOVeCEsvyo=
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma;
	h=mime-version:in-reply-to:references:from:date:message-id:subject:to
	:cc:content-type:content-transfer-encoding;
	b=TJ0vYj/dqb2/Z9zEl/tRr9ihTPXtlDT7+Fk+DNq2MM1KM74iap38fhIPpMzRaeagrc
	4pnF4LYBzjautcT1Ym/3rils85mHXzw72RohJ+qbJ/F4K+gQOj60FQdWFekFt6iS/aBK
	GYrXFaumfzQ6iBvKkWUvWr5/ajNCFQ9dPAJW8=
Received: by 10.213.13.194 with SMTP id d2mr2487583eba.96.1300777170151; Mon,
	21 Mar 2011 23:59:30 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.213.22.6 with HTTP; Mon, 21 Mar 2011 23:59:10 -0700 (PDT)
In-Reply-To: <jwvtyewgn3a.fsf-monnier+emacs@HIDDEN>
References: <4D854552.6000509@HIDDEN>
	<jwvtyewgn3a.fsf-monnier+emacs@HIDDEN>
From: Lennart Borgman <lennart.borgman@HIDDEN>
Date: Tue, 22 Mar 2011 07:59:10 +0100
Message-ID: <AANLkTin9e9wuPD81+x_A7wjy6oenjMBx6WCjoeHM4VLT@HIDDEN>
Subject: Re: bug#8297: Request: Better Emacs self-documentation for
	customization
To: Stefan Monnier <monnier@HIDDEN>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
X-Spam-Score: -3.6 (---)
X-Debbugs-Envelope-To: 8297
Cc: Florian Beck <fb@HIDDEN>, 8297 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/pipermail/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -3.6 (---)

On Mon, Mar 21, 2011 at 11:00 PM, Stefan Monnier
<monnier@HIDDEN> wrote:
>
>> =C2=A0- `describe-key' only provides a link to the function, not to the =
place the
>> key was defined.
>
> That's also more difficult because OT1H `define-key' does not get much
> information (it can check load-file-name, but it doesn't know the line
> number, nor the name of the map it receives and neither does it know
> reliably what the key description looks like in the source file, so it's
> hard to do a regexp-search), and OTOH there's no place currently to
> store that information, tho I guess we could keep it in some side
> hash-table.

That would be good.

I have a hack that at least try to guess the map where a key is
defined. This is the function `describe-key-and-map-briefly' in
ourcomments-util.el in nXhtml. (It is a replacement for
`describe-key-briefly'.)

Message received at 8297 <at> debbugs.gnu.org:

Received: (at 8297) by debbugs.gnu.org; 22 Mar 2011 00:24:54 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Mar 21 20:24:52 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Q1pP2-0006b6-K3
	for submit <at> debbugs.gnu.org; Mon, 21 Mar 2011 20:24:52 -0400
Received: from ironport2-out.teksavvy.com ([206.248.154.181]
	helo=ironport2-out.pppoe.ca)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <monnier@HIDDEN>)
	id 1Q1pP1-0006ap-0W; Mon, 21 Mar 2011 20:24:51 -0400
X-IronPort-Anti-Spam-Filtered: true
X-IronPort-Anti-Spam-Result: AvsEAP6Ih01Ld/X5/2dsb2JhbAClRHiITbsxhWMElWk
X-IronPort-AV: E=Sophos;i="4.63,222,1299474000"; d="scan'208";a="97489519"
Received: from 75-119-245-249.dsl.teksavvy.com (HELO ceviche.home)
	([75.119.245.249])
	by ironport2-out.pppoe.ca with ESMTP/TLS/ADH-AES256-SHA;
	21 Mar 2011 20:24:45 -0400
Received: by ceviche.home (Postfix, from userid 20848)
	id B8161662C8; Mon, 21 Mar 2011 18:00:09 -0400 (EDT)
From: Stefan Monnier <monnier@HIDDEN>
To: Florian Beck <fb@HIDDEN>
Subject: Re: bug#8297: Request: Better Emacs self-documentation for
	customization
Message-ID: <jwvtyewgn3a.fsf-monnier+emacs@HIDDEN>
References: <4D854552.6000509@HIDDEN>
Date: Mon, 21 Mar 2011 18:00:09 -0400
In-Reply-To: <4D854552.6000509@HIDDEN> (Florian Beck's message of "Sun, 
	20 Mar 2011 01:07:46 +0100")
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Score: -2.0 (--)
X-Debbugs-Envelope-To: 8297
Cc: 8297 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/pipermail/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -2.0 (--)

severity 8297 wishlist
thanks

> What I would like is for Emacs to track my customisations:

>  - When I redefine an Emacs function I would like a link to the
> previous/original definition, `describe-function' only provides a link to
> the current one.

I'd like to improve the support for redefinition of functions, indeed.
I'm more interested in getting unload-feature to work more reliably, but
it could work for this as well: basically remember the
previous definitions.

Note that for your case, another option is to use a defadvice, and
indeed defadvice should also add a hyperlink to the advice.

>  - 'describe-variable', on the other hand, remembers the original
> definition, but doesn't remember the place where I changed the value.

That might turn out to be more difficult to track, but at least for some
simple cases (e.g. when the vlue is changed via `custom' functions rather
than via `setq') that should definitely be doable.  If the var was set
via `setq' it's more difficult since `setq' is a very low-level
primitive that needs to run fast.  But maybe we could somehow handle
`setq' outside of functions in a special way (these shouldn't impact
performance since they can't be in loops).

>  - `describe-key' only provides a link to the function, not to the place the
> key was defined.

That's also more difficult because OT1H `define-key' does not get much
information (it can check load-file-name, but it doesn't know the line
number, nor the name of the map it receives and neither does it know
reliably what the key description looks like in the source file, so it's
hard to do a regexp-search), and OTOH there's no place currently to
store that information, tho I guess we could keep it in some side
hash-table.

> Obviously, this is not easy, because evaluations don't necessarily
> have a fixed place and key bindings can be defined in many ways. Regardless,
> I think this is something on which Emacs could improve.

Agreed.  It's not high on my todo list, but I'll be happy to take
patches for those.  For defadvice it should be pretty easy, and for
function re-definitions it shouldn't be too hard either.


        Stefan

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 20 Mar 2011 01:05:43 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Mar 19 21:05:43 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Q175S-00059k-Rj
	for submit <at> debbugs.gnu.org; Sat, 19 Mar 2011 21:05:43 -0400
Received: from eggs.gnu.org ([140.186.70.92])
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <fb@HIDDEN>) id 1Q16C8-0003ux-Oy
	for submit <at> debbugs.gnu.org; Sat, 19 Mar 2011 20:08:33 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <fb@HIDDEN>) id 1Q16C2-00078W-IO
	for submit <at> debbugs.gnu.org; Sat, 19 Mar 2011 20:08:27 -0400
X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE, 
	T_DKIM_INVALID autolearn=unavailable version=3.3.1
Received: from lists.gnu.org ([199.232.76.165]:44763)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <fb@HIDDEN>) id 1Q16C1-00077T-LD
	for submit <at> debbugs.gnu.org; Sat, 19 Mar 2011 20:08:26 -0400
Received: from [140.186.70.92] (port=38448 helo=eggs.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.43) id 1Q16Bj-0001nh-Rd
	for bug-gnu-emacs@HIDDEN; Sat, 19 Mar 2011 20:08:10 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <fb@HIDDEN>) id 1Q16BR-000741-JJ
	for bug-gnu-emacs@HIDDEN; Sat, 19 Mar 2011 20:07:50 -0400
Received: from mo-p00-ob.rzone.de ([81.169.146.162]:52565)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <fb@HIDDEN>) id 1Q16BR-00073h-7y
	for bug-gnu-emacs@HIDDEN; Sat, 19 Mar 2011 20:07:49 -0400
DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; t=1300579667; l=794;
	s=domk; d=streitblatt.de;
	h=Content-Transfer-Encoding:Content-Type:Subject:To:MIME-Version:From:
	Date:X-RZG-CLASS-ID:X-RZG-AUTH;
	bh=zA1LJEnpkJxUNnopOsmt9J1tON0=;
	b=ocdh/KE5ZuEgViIou6VDW131dOwkGSGbRQxfEdBgOkzeYweFV2kM9idv9kBotBkwntI
	Zcr/7/mt5fCotnlaTBa6QBuovRRUeSoQa0MDXtYNgLPVWgNWaMhTeebZOqfUUeQePwGvz
	uyXjYJXfRZ3ISnhVKUG9YGqCB0GJY9tJlz4=
X-RZG-AUTH: :KmALZ0mpdbGonPxw7gDkop508XQjelhLxGYn4B74/jTNdrjLjuwMuuiy8j0BYX6h4QCrsg==
X-RZG-CLASS-ID: mo00
Received: from [192.168.2.100] (p5499534E.dip.t-dialin.net [84.153.83.78])
	by post.strato.de (mrclete mo10) (RZmta 25.8)
	with ESMTPA id 9068a6n2JMYJwk for <bug-gnu-emacs@HIDDEN>;
	Sun, 20 Mar 2011 01:07:46 +0100 (MET)
Message-ID: <4D854552.6000509@HIDDEN>
Date: Sun, 20 Mar 2011 01:07:46 +0100
From: Florian Beck <fb@HIDDEN>
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US;
	rv:1.9.2.14) Gecko/20110223 Thunderbird/3.1.8
MIME-Version: 1.0
To: bug-gnu-emacs@HIDDEN
Subject: Request: Better Emacs self-documentation for customization
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta)
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2)
X-Received-From: 199.232.76.165
X-Spam-Score: -6.6 (------)
X-Debbugs-Envelope-To: submit
X-Mailman-Approved-At: Sat, 19 Mar 2011 21:05:41 -0400
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/pipermail/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -6.6 (------)

Emacs integrates any function I write into its documentation; the help 
function provides a link to the source.

What I would like is for Emacs to track my customisations:

  - When I redefine an Emacs function I would like a link to the 
previous/original definition, `describe-function' only provides a link 
to the current one.
  - 'describe-variable', on the other hand, remembers the original 
definition, but doesn't remember the place where I changed the value.
  - `describe-key' only provides a link to the function, not to the 
place the key was defined.

Obviously, this is not easy, because evaluations don't necessarily have 
a fixed place and key bindings can be defined in many ways. Regardless, 
I think this is something on which Emacs could improve.

-- 
Florian Beck