GNU bug report logs - #3740
documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 3740 in the body.
You can then email your comments to 3740 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: MON KEY <monkey <at> sandpframing.com>
To: emacs-pretest-bug <at> gnu.org
Subject: documentation of args to `documentation-property' differ 
	info<-->docstring on 23.0.92.1 thru 23.0.95
Date: Thu, 2 Jul 2009 14:24:08 -0400

pretests 23.0.92.1 thru 23.0.95

documentation of args to `documentation-property' differ info<-->help&src

C-h f documentation-property
=> "(documentation-property symbol prop &optional raw)"

(info "(elisp)Accessing Documentation")
=>  "-- Function: documentation-property symbol property &optional verbatim"

-----------------------------------------------
../emacs-23.0.95/info/elisp-5  @lines 2258-2261

"24.2 Access to Documentation Strings
====================================

 -- Function: documentation-property symbol property &optional verbatim"

------------------------------------------
../emacs-23.0.95/src/doc.c  @lines 475-476

"  (symbol, prop, raw)
     Lisp_Object symbol, prop, raw;"

Message #8 received at 3740 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 3740 <at> debbugs.gnu.org
Subject: Re: bug#3740: documentation of args to `documentation-property' differ info<-->docstring on 23.0.92.1 thru 23.0.95
Date: Thu, 02 Jul 2009 22:40:07 -0400

MON KEY wrote:

> documentation of args to `documentation-property' differ info<-->help&src
>
> C-h f documentation-property
> => "(documentation-property symbol prop &optional raw)"
>
> (info "(elisp)Accessing Documentation")
> =>  "-- Function: documentation-property symbol property &optional verbatim"

If your point is, they use different names for some of the arguments,
this is of no importance.

Message #13 received at 3740 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: MON KEY <monkey <at> sandpframing.com>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 3740 <at> debbugs.gnu.org
Subject: Re: bug#3740: documentation of args to `documentation-property' 
	differ info<-->docstring on 23.0.92.1 thru 23.0.95
Date: Fri, 3 Jul 2009 00:35:26 -0400

On Thu, Jul 2, 2009 at 10:40 PM, Glenn Morris<rgm <at> gnu.org> wrote:
>
> If your point is, they use different names for some of the arguments,
> this is of no importance.
>

Blech.

 I have no point other than to indicate that there is a discrepancy.

It is *important* enough that I noticed the discrepancy when trying to
_understand_ what the function does!

The discrepancy - however trivial it  may be to _you_ - is none the
less a discrepancy.

Surely you don't hold this view for _all_ functions.

Should one assume that consistent indication of the args to a function
is of no importance across the board - or does this apply only for
this particular inconsistency?

Some pigs are more equal than others i guess...

s_P

Message #18 received at 3740 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: MON KEY <monkey <at> sandpframing.com>, 3740 <at> debbugs.gnu.org
Subject: Re: bug#3740: documentation of args to `documentation-property' differ
 info<-->docstring on 23.0.92.1 thru 23.0.95
Date: Fri, 03 Jul 2009 08:46:46 +0200

> The discrepancy - however trivial it  may be to _you_ - is none the
> less a discrepancy.
>
> Surely you don't hold this view for _all_ functions.
>
> Should one assume that consistent indication of the args to a function
> is of no importance across the board - or does this apply only for
> this particular inconsistency?

The current Elisp reference manual features more than 500 such
discrepancies.  Most of them would have to be fixed by changing the
specification, not the manual.  Changing the specification means check
for name clashes, reindent code, refill doc-strings and comments,
recompile, rebuild.  Doing this manually would get people busy for quite
some time.

martin

Message #23 received at 3740 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: MON KEY <monkey <at> sandpframing.com>
To: martin rudalics <rudalics <at> gmx.at>
Cc: 3740 <at> debbugs.gnu.org
Subject: Re: bug#3740: documentation of args to `documentation-property' 
	differ info<-->docstring on 23.0.92.1 thru 23.0.95
Date: Fri, 3 Jul 2009 19:42:52 -0400

On Fri, Jul 3, 2009 at 2:46 AM, martin rudalics<rudalics <at> gmx.at> wrote:
> The current Elisp reference manual features more than 500 such
> {...}
> recompile, rebuild.  Doing this manually would get people busy for quite
> some time.

Sure, but this particular case is significant in a way that other +/-
499 might not be;
`documentation-property' relates to the documentation of documentation.

Me: "How shall I get at a symbol's documentation?"
Me to myself: "RTFM!"
Me: "Manual doesn't agree with source..."
Me to myself: "Hrmmm... well, FTFM!"

Getting to discrepancies like this one is _kinda_ important.

Again, in this _particular_ situation this is not simply a discrepancy
but a fundamental inconsistency w/re to Emacs.

I understand that this particular situation may pose a bootstrapping
issue. However, if that is the case then it certainly doesn't hold
that the 'discrepancy'  is of "no importance".

What exactly does it say that the one true self documenting editor
can't/won't correctly self document the very documentation of how it
self documents?

Actually - on second thought - disregard the previous rhetorical
question its not of any importance...

> martin
s_P

Message #26 received at 3740 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: MON KEY <monkey <at> sandpframing.com>
Cc: 3740 <at> debbugs.gnu.org,
        control <control <at> debbugs.gnu.org>
Subject: Re: bug#3740: documentation of args to `documentation-property'  differ info<-->docstring on 23.0.92.1 thru 23.0.95
Date: Sat, 04 Jul 2009 19:16:04 -0400

severity 3740 minor
tags 3740 wontfix
stop

MON KEY wrote:

> Surely you don't hold this view for _all_ functions.

Yep. When one writes a function, one tends to use short variable names
(`prop'), when one documents it in a manual, one might want to use
more descriptive argument names (`properties'). They're just dummy
variables, it doesn't matter to me what they are called.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.