bug#4402: apropos-documentation and platform-specific docs

bug#4402: apropos-documentation and platform-specific docs

[Glenn Morris]

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.

bug#4402: apropos-documentation and platform-specific docs

[Eli Zaretskii]

> From: Glenn Morris <rgm@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.

bug#4402: apropos-documentation and platform-specific docs

[Glenn Morris]

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?

bug#4402: apropos-documentation and platform-specific docs

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: 4402@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.

bug#4402: apropos-documentation and platform-specific docs

[Stefan Monnier]

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

Processed: Re: bug#4402: apropos-documentation and platform-specific docs

[Emacs bug Tracking System]

Processing commands for control@emacsbugs.donarmstrong.com:

> retitle 4402 Merge all platform-specific functions
Bug #4402 [emacs] apropos-documentation and platform-specific docs
Changed bug title to 'Merge all platform-specific functions' from 'apropos-documentation and platform-specific docs'
> stop
Stopping processing here.

Please contact me if you need assistance.

Don Armstrong
(administrator, Emacs bugs database)

bug#4402: apropos-documentation and platform-specific docs

[Glenn Morris]

> Retitling this and leaving it open as a reminder.

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

bug#4402: apropos-documentation and platform-specific docs

[Stefan Monnier]

> 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