bug#7167: 23.2; w32-shell-execute doc

bug#7167: 23.2; w32-shell-execute doc

[Mirko Vukovic]

In `emacs -Q'

When executing describe function (C-c f on) w32-shell-execute I get the
following result:

w32-shell-execute is a built-in function in `C source code'.

[Missing arglist.  Please make a bug report.]

Not documented.

[back]


In GNU Emacs 23.2.1 (i386-mingw-nt5.1.2600)
 of 2010-05-08 on G41R2F1
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/xpm/include'

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: ENU
  value of $XMODIFIERS: nil
  locale-coding-system: cp1252
  default enable-multibyte-characters: t

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
C-h f w 3 2 - s h e l l <tab> <tab> e <tab> <return>
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo>
<help-echo> <help-echo> <help-echo> <help-echo> <menu-bar>
<help-menu> <send-emacs-bug-report>

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Making completion list...
Type C-x 1 to delete the help window.

Load-path shadows:
e:/program-files/emacs-23.2/site-lisp/remember/remember hides
e:/program-files/emacs-23.2/lisp/textmodes/remember

Features:
(shadow sort mail-extr message ecomplete rfc822 mml mml-sec
password-cache mm-decode mm-bodies mm-encode mailcap mail-parse rfc2231
rfc2047 rfc2045 qp ietf-drums mailabbrev nnheader gnus-util netrc
time-date mm-util mail-prsvr gmm-utils wid-edit mailheader canlock sha1
hex-util hashcash mail-utils emacsbug help-mode easymenu view help-fns
tooltip ediff-hook vc-hooks lisp-float-type mwheel dos-w32 disp-table
ls-lisp w32-win w32-vars tool-bar dnd fontset image fringe lisp-mode
register page menu-bar rfn-eshadow timer select scroll-bar mldrag mouse
jit-lock font-lock syntax facemenu font-core frame cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
loaddefs button minibuffer faces cus-face files text-properties overlay
md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process multi-tty emacs)

bug#7167: 23.2; w32-shell-execute doc

[Juanma Barranquero]

On Wed, Oct 6, 2010 at 16:46, Mirko Vukovic <mirko.vukovic@gmail.com> wrote:

> w32-shell-execute is a built-in function in `C source code'.
>
> [Missing arglist.  Please make a bug report.]
>
> Not documented.

I cannot reproduce this (neither 23.1, 23.2 nor the branch for 23.3 or
the trunk).

Perhaps a problem with the binary distribution. Where did you get that
Emacs binary?

    Juanma

bug#7167: 23.2; w32-shell-execute doc

[Christoph]

On 10/6/2010 12:27 PM, Juanma Barranquero wrote:

>> w32-shell-execute is a built-in function in `C source code'.
>>
>> [Missing arglist.  Please make a bug report.]
>>
>> Not documented.
>
> I cannot reproduce this (neither 23.1, 23.2 nor the branch for 23.3 or
> the trunk).

It works OK in the current trunk (r101822), but I can definitely 
reproduce this in 23.2. Binary distribution from the official site 
running on Windows 7. See details below.

In GNU Emacs 23.2.1 (i386-mingw-nt6.1.7600)
  of 2010-05-08 on G41R2F1
Windowing system distributor `Microsoft Corp.', version 6.1.7600
configured using `configure --with-gcc (3.4) --no-opt --cflags 
-Ic:/xpm/include'

Important settings:
   value of $LC_ALL: nil
   value of $LC_COLLATE: nil
   value of $LC_CTYPE: nil
   value of $LC_MESSAGES: nil
   value of $LC_MONETARY: nil
   value of $LC_NUMERIC: nil
   value of $LC_TIME: nil
   value of $LANG: ENU
   value of $XMODIFIERS: nil
   locale-coding-system: cp1252
   default enable-multibyte-characters: t

Major mode: Lisp Interaction

Minor modes in effect:
   tooltip-mode: t
   mouse-wheel-mode: t
   tool-bar-mode: t
   menu-bar-mode: t
   file-name-shadow-mode: t
   global-font-lock-mode: t
   font-lock-mode: t
   blink-cursor-mode: t
   auto-encryption-mode: t
   auto-compression-mode: t
   line-number-mode: t
   transient-mark-mode: t

Recent input:
M-x r e p o t - <backspace> <backspace> r t <tab>
<return>

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.

Load-path shadows:
None found.

Features:
(shadow sort mail-extr message ecomplete rfc822 mml easymenu mml-sec
password-cache mm-decode mm-bodies mm-encode mailcap mail-parse rfc2231
rfc2047 rfc2045 qp ietf-drums mailabbrev nnheader gnus-util netrc
time-date mm-util mail-prsvr gmm-utils wid-edit mailheader canlock sha1
hex-util hashcash mail-utils emacsbug tooltip ediff-hook vc-hooks
lisp-float-type mwheel dos-w32 disp-table ls-lisp w32-win w32-vars
tool-bar dnd fontset image fringe lisp-mode register page menu-bar
rfn-eshadow timer select scroll-bar mldrag mouse jit-lock font-lock
syntax facemenu font-core frame cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese hebrew greek
romanian slovak czech european ethiopic indian cyrillic chinese
case-table epa-hook jka-cmpr-hook help simple abbrev loaddefs button
minibuffer faces cus-face files text-properties overlay md5 base64
format env code-pages mule custom widget hashtable-print-readable
backquote make-network-process multi-tty emacs)

Christoph

bug#7167: 23.2; w32-shell-execute doc

[Christoph]

On 10/6/2010 9:42 PM, Christoph wrote:

> It works OK in the current trunk (r101822), but I can definitely
> reproduce this in 23.2. Binary distribution from the official site
> running on Windows 7. See details below.

Juanma, let me know if I can help troubleshoot this.

Christoph

bug#7167: 23.2; w32-shell-execute doc

[Juanma Barranquero]

[Sean, I've Cc:ed you because you're doing binary tarballs now]

On Thu, Oct 7, 2010 at 05:57, Christoph <cschol2112@googlemail.com> wrote:

> Juanma, let me know if I can help troubleshoot this.

I think it is an issue with the binary distribution of Emacs 23.2 for
Windows, not with 23.2 per se, because I have my own build of it and
the problem is not present.

Likely the fix will simply be to rebuild the official binary
distribution of 23.2.

    Juanma

bug#7167: 23.2; w32-shell-execute doc

[Lennart Borgman]

On Thu, Oct 7, 2010 at 12:15 PM, Juanma Barranquero <lekktu@gmail.com> wrote:
> [Sean, I've Cc:ed you because you're doing binary tarballs now]
>
> On Thu, Oct 7, 2010 at 05:57, Christoph <cschol2112@googlemail.com> wrote:
>
>> Juanma, let me know if I can help troubleshoot this.
>
> I think it is an issue with the binary distribution of Emacs 23.2 for
> Windows, not with 23.2 per se, because I have my own build of it and
> the problem is not present.
>
> Likely the fix will simply be to rebuild the official binary
> distribution of 23.2.

Then something must be broken in the official binary distribution.
Maybe it would be good to know what? Or maybe it is just not worth the
trouble?

Anyway should not new binaries with a new version number (say 23.2.1)
be uploaded then?

bug#7167: 23.2; w32-shell-execute doc

[Juanma Barranquero]

On Thu, Oct 7, 2010 at 12:44, Lennart Borgman <lennart.borgman@gmail.com> wrote:

> Then something must be broken in the official binary distribution.

Isn't that what I said?

> Maybe it would be good to know what? Or maybe it is just not worth the
> trouble?

Not worth the trouble, I think.

> Anyway should not new binaries with a new version number (say 23.2.1)
> be uploaded then?

Perhaps, but that's up to Jason and Sean, I think, because they are
the ones taking care of the binary tarballs.

    Juanma

bug#7167: 23.2; w32-shell-execute doc

[Lennart Borgman]

On Thu, Oct 7, 2010 at 12:46 PM, Juanma Barranquero <lekktu@gmail.com> wrote:
> On Thu, Oct 7, 2010 at 12:44, Lennart Borgman <lennart.borgman@gmail.com> wrote:
>
>> Then something must be broken in the official binary distribution.
>
> Isn't that what I said?

;-)

>> Maybe it would be good to know what? Or maybe it is just not worth the
>> trouble?
>
> Not worth the trouble, I think.
>
>> Anyway should not new binaries with a new version number (say 23.2.1)
>> be uploaded then?
>
> Perhaps, but that's up to Jason and Sean, I think, because they are
> the ones taking care of the binary tarballs.

Isn't it more general than that? Must we not make it clear that
unfortunately something went wrong with the upload of 23.2 and
therefore we make a new upload 23.2.1? At least I think that would
help the users.

bug#7167: 23.2; w32-shell-execute doc

[Juanma Barranquero]

On Thu, Oct 7, 2010 at 12:50, Lennart Borgman <lennart.borgman@gmail.com> wrote:

> Isn't it more general than that? Must we not make it clear that
> unfortunately something went wrong with the upload of 23.2 and
> therefore we make a new upload 23.2.1? At least I think that would
> help the users.

So far, the only trouble is that one specific function is lacking its
docstring. Hardly earthshaking.

Releasing a new 23.2 could be confusing, specially if 23.3 pretest is
about to start (Chong said).

    Juanma

bug#7167: 23.2; w32-shell-execute doc

[Lennart Borgman]

On Thu, Oct 7, 2010 at 12:56 PM, Juanma Barranquero <lekktu@gmail.com> wrote:
> On Thu, Oct 7, 2010 at 12:50, Lennart Borgman <lennart.borgman@gmail.com> wrote:
>
>> Isn't it more general than that? Must we not make it clear that
>> unfortunately something went wrong with the upload of 23.2 and
>> therefore we make a new upload 23.2.1? At least I think that would
>> help the users.
>
> So far, the only trouble is that one specific function is lacking its
> docstring. Hardly earthshaking.

It does not really matter to me, but can you ask yourself how you are
thinking here?

> Releasing a new 23.2 could be confusing, specially if 23.3 pretest is
> about to start (Chong said).

Yes, maybe. However the trouble could be worse so the possibility for
this must be made explicit IMO.

bug#7167: 23.2; w32-shell-execute doc

[Juanma Barranquero]

On Thu, Oct 7, 2010 at 13:53, Lennart Borgman <lennart.borgman@gmail.com> wrote:

> It does not really matter to me, but can you ask yourself how you are
> thinking here?

What are you suggesting? Be clear.

> Yes, maybe. However the trouble could be worse so the possibility for
> this must be made explicit IMO.

Again: explain yourself if you want to be understood.

    Juanma

bug#7167: 23.2; w32-shell-execute doc

[Jason Rumney]

Juanma Barranquero <lekktu@gmail.com> writes:

> On Thu, Oct 7, 2010 at 05:57, Christoph <cschol2112@googlemail.com> wrote:
>
>> Juanma, let me know if I can help troubleshoot this.
>
> I think it is an issue with the binary distribution of Emacs 23.2 for
> Windows, not with 23.2 per se, because I have my own build of it and
> the problem is not present.
>
> Likely the fix will simply be to rebuild the official binary
> distribution of 23.2.

It sounds like the problem could be a stale DOC file. Sean, did you run
make install after building, or did you just copy the exe files into the
bin directory by hand?

When I built the binaries, I always started from a fresh directory, and
used make install to ensure everything was in place.

It could also be caused by the recent changes to the install and
packaging targets for Windows failing to copy or package all the
required files.  I'm not sure if those changes went into the Emacs 23
branch, if so then they may need checking.

bug#7167: 23.2; w32-shell-execute doc

[Esa Peuha]

> So far, the only trouble is that one specific function is lacking its docstring.

It's a little more serious than that: all lisp functions defined in
every w32*.c file, except for those with names beginning with x, are
missing their docstrings. I didn't check functions from other files,
so some of their docstrings may be missing as well.

bug#7167: 23.2; w32-shell-execute doc

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Thu, 7 Oct 2010 12:15:55 +0200
> Cc: Sean Sieger <sean.sieger@gmail.com>, 7167@debbugs.gnu.org
> 
> [Sean, I've Cc:ed you because you're doing binary tarballs now]
> 
> On Thu, Oct 7, 2010 at 05:57, Christoph <cschol2112@googlemail.com> wrote:
> 
> > Juanma, let me know if I can help troubleshoot this.
> 
> I think it is an issue with the binary distribution of Emacs 23.2 for
> Windows, not with 23.2 per se, because I have my own build of it and
> the problem is not present.
> 
> Likely the fix will simply be to rebuild the official binary
> distribution of 23.2.

Not sure, because my binary, which I built myself, also has this
problem.

Will try to investigate tomorrow.

bug#7167: 23.2; w32-shell-execute doc

[Eli Zaretskii]

> From: Jason Rumney <jasonr@gnu.org>
> Date: Thu, 07 Oct 2010 22:18:12 +0800
> Cc: Christoph <cschol2112@googlemail.com>, Sean Sieger <sean.sieger@gmail.com>,
> 	7167@debbugs.gnu.org
> 
> It sounds like the problem could be a stale DOC file. Sean, did you run
> make install after building, or did you just copy the exe files into the
> bin directory by hand?

This is unlikely to be the problem: my binary was built in a fresh
directory and "make install"ed, and it also doesn't have this function
documented.

bug#7167: 23.2; w32-shell-execute doc

[Sean Sieger]

Jason Rumney <jasonr@gnu.org> writes:

    It sounds like the problem could be a stale DOC file. Sean, did you run
    make install after building, or did you just copy the exe files into the
    bin directory by hand?

I ran make install.

    When I built the binaries, I always started from a fresh directory, and
    used make install to ensure everything was in place.

While I don't delete /bin, I don't alter the course of make install.

    It could also be caused by the recent changes to the install and
    packaging targets for Windows failing to copy or package all the
    required files.  I'm not sure if those changes went into the Emacs 23
    branch, if so then they may need checking.

I think post 23.2.

bug#7167: 23.2; w32-shell-execute doc

[Sean Sieger]

    Likely the fix will simply be to rebuild the official binary
    distribution of 23.2.

So, is this worth a try?

bug#7167: 23.2; w32-shell-execute doc

[Eli Zaretskii]

> Date: Thu, 07 Oct 2010 20:12:47 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: cschol2112@googlemail.com, sean.sieger@gmail.com, 7167@debbugs.gnu.org
> 
> > From: Juanma Barranquero <lekktu@gmail.com>
> > Date: Thu, 7 Oct 2010 12:15:55 +0200
> > Cc: Sean Sieger <sean.sieger@gmail.com>, 7167@debbugs.gnu.org
> > 
> > [Sean, I've Cc:ed you because you're doing binary tarballs now]
> > 
> > On Thu, Oct 7, 2010 at 05:57, Christoph <cschol2112@googlemail.com> wrote:
> > 
> > > Juanma, let me know if I can help troubleshoot this.
> > 
> > I think it is an issue with the binary distribution of Emacs 23.2 for
> > Windows, not with 23.2 per se, because I have my own build of it and
> > the problem is not present.
> > 
> > Likely the fix will simply be to rebuild the official binary
> > distribution of 23.2.
> 
> Not sure, because my binary, which I built myself, also has this
> problem.
> 
> Will try to investigate tomorrow.

Found the problem.  There's nothing wrong with the Windows build
system per se.  The problem is that emacs-23.2 tarball comes with a
src/buildobj.h from a Unix system where it was tarred, which is
baaaaad, and not only on Windows.  This causes Make not to create
src/buildobj.h as suitable for the actual build on the target
platform, and the rest is history.

I've just installed a fix in the emacs-23 branch (revno 100091 and a
followup change in 100092) to exclude this file from the tarball.

To fix this locally, just remove src/buildobj.h and rebuild Emacs.

While at that, I would suggest that this code in help-fns.el:

      (let ((file (catch 'loop
		    (while t
		      (let ((pnt (search-forward (concat "\x1f" name "\n"))))
			(re-search-backward "\x1fS\\(.*\\)")
			(let ((file (match-string 1)))
			  (if (member file build-files)
			      (throw 'loop file)
			    (goto-char pnt))))))))
	(if (string-match "^ns.*\\(\\.o\\|obj\\)\\'" file)
	    (setq file (replace-match ".m" t t file 1))
	  (if (string-match "\\.\\(o\\|obj\\)\\'" file)
	      (setq file (replace-match ".c" t t file))))
	(if (string-match "\\.\\(c\\|m\\)\\'" file)
	    (concat "src/" file)
	  file)))))

be made smarter wrt the error message it displays when the function or
variable it looks for is found in etc/DOC, but the file in which it is
defined is not in build-files.  (This happens when you click or type
RET on the link to the source file where the function is defined.)
Currently, the error message, which comes from search-forward, is
quite cryptic for a naive user:

    Search failed: "^_Fw32-shell-execute
    "

It should at least mention the fact that the problem could be with
build-files, or, better, say that w32-shell-execute's definition is in
a file that is not in build-files.  Volunteers are welcome to make
this improvement.

bug#7167: 23.2; w32-shell-execute doc

[Lennart Borgman]

On Fri, Oct 8, 2010 at 11:52 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Thu, 07 Oct 2010 20:12:47 +0200
>> From: Eli Zaretskii <eliz@gnu.org>
>> Cc: cschol2112@googlemail.com, sean.sieger@gmail.com, 7167@debbugs.gnu.org
>>
>> > From: Juanma Barranquero <lekktu@gmail.com>
>> > Date: Thu, 7 Oct 2010 12:15:55 +0200
>> > Cc: Sean Sieger <sean.sieger@gmail.com>, 7167@debbugs.gnu.org
>> >
>> > [Sean, I've Cc:ed you because you're doing binary tarballs now]
>> >
>> > On Thu, Oct 7, 2010 at 05:57, Christoph <cschol2112@googlemail.com> wrote:
>> >
>> > > Juanma, let me know if I can help troubleshoot this.
>> >
>> > I think it is an issue with the binary distribution of Emacs 23.2 for
>> > Windows, not with 23.2 per se, because I have my own build of it and
>> > the problem is not present.
>> >
>> > Likely the fix will simply be to rebuild the official binary
>> > distribution of 23.2.
>>
>> Not sure, because my binary, which I built myself, also has this
>> problem.
>>
>> Will try to investigate tomorrow.
>
> Found the problem.  There's nothing wrong with the Windows build
> system per se.  The problem is that emacs-23.2 tarball comes with a
> src/buildobj.h from a Unix system where it was tarred, which is
> baaaaad, and not only on Windows.  This causes Make not to create
> src/buildobj.h as suitable for the actual build on the target
> platform, and the rest is history.

Very good.

What impact can this have other than what we know now?

bug#7167: 23.2; w32-shell-execute doc

[Ken Brown]

On 10/8/2010 5:52 AM, Eli Zaretskii wrote:
> Found the problem.  There's nothing wrong with the Windows build
> system per se.  The problem is that emacs-23.2 tarball comes with a
> src/buildobj.h from a Unix system where it was tarred, which is
> baaaaad, and not only on Windows.  This causes Make not to create
> src/buildobj.h as suitable for the actual build on the target
> platform, and the rest is history.
>
> I've just installed a fix in the emacs-23 branch (revno 100091 and a
> followup change in 100092) to exclude this file from the tarball.
>
> To fix this locally, just remove src/buildobj.h and rebuild Emacs.

This also fixes bug#7127.  I'll write a separate message about that.

Ken