GNU bug report logs - #4402
Merge all platform-specific functions

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 4402 in the body.
You can then email your comments to 4402 AT debbugs.gnu.org in the normal way.

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

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

From: Glenn Morris <rgm <at> gnu.org>
To: bug-gnu-emacs <at> gnu.org
Subject: apropos-documentation and platform-specific docs
Date: Fri, 11 Sep 2009 03:01:04 -0400

On GNU/Linux:
emacs -Q
M-x apropos-documentation nextstep

returns various matches, including things like:

x-create-frame
  Function: Make a new Nextstep window, called a "frame" in Emacs terms.
[...]

The one-line summary is incorrect, since it is the version specific to
the NS build, not the build currently running.

The problem is caused by the DOC file containing three sets of
doc-strings for Fx-create-frame, extracted from w32fns.c, xfns.c, and
nsfns.m.

This made me wonder, why does the DOC file in my GNU/Linux build
contain information extracted from Nextstep and Windows files that is
never going to be relevant? Perhaps it's so that one can in principle
share DOC files between different builds? This doesn't seem like a big
advantage to me. I doubt (m)any people have ever shared the DOC file
between any of these platforms. The size of DOC is a negligible part of
a current Emacs installation.

The standard solution to this kind of thing seems to be that where
functions/variables have multiple, platform-specific definitions, each
should have the same, unified doc-string. This is a bit of a pain.

Only putting the relevant files into the DOC file would eliminate this
issue.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>, 4402 <at> debbugs.gnu.org
Subject: Re: bug#4402: apropos-documentation and platform-specific docs
Date: Fri, 11 Sep 2009 12:02:37 +0300

> From: Glenn Morris <rgm <at> gnu.org>
> Date: Fri, 11 Sep 2009 03:01:04 -0400
> Cc: 
> 
> The problem is caused by the DOC file containing three sets of
> doc-strings for Fx-create-frame, extracted from w32fns.c, xfns.c, and
> nsfns.m.
> 
> This made me wonder, why does the DOC file in my GNU/Linux build
> contain information extracted from Nextstep and Windows files that is
> never going to be relevant? Perhaps it's so that one can in principle
> share DOC files between different builds? This doesn't seem like a big
> advantage to me. I doubt (m)any people have ever shared the DOC file
> between any of these platforms. The size of DOC is a negligible part of
> a current Emacs installation.

DOC is an architecture-independent file, so it must include the doc
strings of all symbols.

> The standard solution to this kind of thing seems to be that where
> functions/variables have multiple, platform-specific definitions, each
> should have the same, unified doc-string. This is a bit of a pain.
> 
> Only putting the relevant files into the DOC file would eliminate this
> issue.

There are other solutions, but they need some infrastructure.  See
past discussions of this issue a couple of months ago.

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

From: Glenn Morris <rgm <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 4402 <at> debbugs.gnu.org
Subject: Re: bug#4402: apropos-documentation and platform-specific docs
Date: Fri, 11 Sep 2009 14:05:32 -0400

Eli Zaretskii wrote:

> DOC is an architecture-independent file, so it must include the doc
> strings of all symbols.

My question is, why must DOC be architecture independent?
There are certianly drawbacks to this, so what's the benefit?

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 4402 <at> debbugs.gnu.org, bug-gnu-emacs <at> gnu.org
Subject: Re: bug#4402: apropos-documentation and platform-specific docs
Date: Fri, 11 Sep 2009 15:04:00 -0400

> x-create-frame
>   Function: Make a new Nextstep window, called a "frame" in Emacs terms.
> [...]

Yes.  Someone needs to move the DEFUN of x-create-frame to
a platform-independent file.  Maybe it can be renamed to something that
doesn't include the misleading "x-" prefix.  If we ever want to be able
to run an Emacs session with both X11 and ns frames (and/or X11 and
w32), this kind of work will be necessary anyway.

Same thing goes for x-popup-menu and many others.

Any help in this direction is welcome.  It can be done little by little.


        Stefan

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 4402 <at> debbugs.gnu.org
Subject: Re: bug#4402: apropos-documentation and platform-specific docs
Date: Sat, 12 Sep 2009 11:55:47 +0300

> From: Glenn Morris <rgm <at> gnu.org>
> Cc: 4402 <at> emacsbugs.donarmstrong.com
> Date: Fri, 11 Sep 2009 14:05:32 -0400
> 
> Eli Zaretskii wrote:
> 
> > DOC is an architecture-independent file, so it must include the doc
> > strings of all symbols.
> 
> My question is, why must DOC be architecture independent?
> There are certianly drawbacks to this, so what's the benefit?

The main benefit is that it can be installed only once for several
different architectures, like all the Lisp files.

Another benefit is that the doc strings are available on all
platforms, no matter if the doc string is read from a Lisp file or
from DOC.  This is handy when, e.g., one writes an emulation for a
platform-specific function on another platform.  It also provides a
common base for discussing interfaces and doc strings.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 4402 <at> debbugs.gnu.org, Glenn Morris <rgm <at> gnu.org>
Subject: Re: bug#4402: apropos-documentation and platform-specific docs
Date: Sat, 12 Sep 2009 15:45:55 -0400

>> > DOC is an architecture-independent file, so it must include the doc
>> > strings of all symbols.
>> My question is, why must DOC be architecture independent?
>> There are certianly drawbacks to this, so what's the benefit?

Actually, I can't think of many drawbacks.  Most of the problems we face
in this respect are just the tip of the iceberg, where the rest of the
iceberg is the inconsistency we have in the different implementations of
"the same" function/variable.
If we fix the real underlying problems, then there are no problems with
the DOC file.


        Stefan

Message #36 received at 4402-quiet <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 4402-quiet <at> debbugs.gnu.org
Subject: Re: bug#4402: apropos-documentation and platform-specific docs
Date: Sun, 13 Sep 2009 21:12:02 -0400

retitle 4402 Merge all platform-specific functions
stop

Stefan Monnier wrote:

> Most of the problems we face in this respect are just the tip of the
> iceberg, where the rest of the iceberg is the inconsistency we have
> in the different implementations of "the same" function/variable. If
> we fix the real underlying problems, then there are no problems with
> the DOC file.

Retitling this and leaving it open as a reminder.

Message #39 received at 4402 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 4402 <at> debbugs.gnu.org
Subject: Re: bug#4402: apropos-documentation and platform-specific docs
Date: Sun, 03 Dec 2017 22:05:16 -0500

> Retitling this and leaving it open as a reminder.

It hasn't been of any use. Closing as wontfix.

Previous Next

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