Documentation fix

Documentation fix

[Po Lu]

Would someone who can please install the following change to emacs-29?
Savannah seems to be down again.

2023-04-07  Po Lu  <luangruo@yahoo.com>

	* doc/lispref/frames.texi (Drag and Drop): Fix
	description of `x-dnd-direct-save-function'.

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 9083b4b01c9..fd3bf67cf9f 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -4177,19 +4177,25 @@ Drag and Drop
   However, @code{x-dnd-types-alist} does not handle a special kind of
 drop sent by a program that wants Emacs to tell it where to save a
 file in a specific location determined by the user.  These drops are
-instead handled by a function that is the value of the variable
-@code{x-dnd-direct-save-function}.  This function should accept two arguments.
-If the first argument is non-@code{nil}, then the second argument is a
-file name to save (with leading directories) that the other
-program recommends, and the
-function should return the full file name under which it should be
-saved.  After the function completes, Emacs will ask the other program
-to save the file under the name that was returned, and if the file was
-successfully saved, call the function again with the first argument
-set to a non-@code{nil} value and the second argument set to the file
-name that was returned.  The function should then perform whatever
-action is appropriate (i.e., opening the file or refreshing a
-directory listing.)
+instead handled by a function determined by the variable
+@code{x-dnd-direct-save-function}.  This function is essentially two
+functions in one---its first argument is a boolean which tells it what
+operations to perform.
+
+  When the drop takes place, the function is first called with its
+first argument set to a non-@code{nil} value, and its second argument
+set to a file name that the file should be saved under; this file name
+does not contain the directory under which the file should be saved.
+
+  The function should return the complete file name under which the
+file should be saved, including the directory where it should be
+saved, under which Emacs will ask the other program to save the file.
+
+  If the file was successfully saved, the function is called again,
+this time with the first argument set to @code{nil}, and the second
+argument set to the file name that was returned.  The function should
+then perform whatever action is appropriate (i.e., opening the file or
+refreshing a directory listing.)
 
 @cindex initiating drag-and-drop
   On capable window systems, Emacs also supports dragging contents

Re: Documentation fix

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Date: Fri, 07 Apr 2023 20:04:43 +0800
> 
> Would someone who can please install the following change to emacs-29?
> Savannah seems to be down again.

It isn't down from here.

> +instead handled by a function determined by the variable
> +@code{x-dnd-direct-save-function}.  This function is essentially two
> +functions in one---its first argument is a boolean which tells it what
> +operations to perform.
> +
> +  When the drop takes place, the function is first called with its
> +first argument set to a non-@code{nil} value, and its second argument
> +set to a file name that the file should be saved under; this file name
> +does not contain the directory under which the file should be saved.

Does this mean the function gets on the basename of the file, without
any leading directories?  Or does it mean something else?

> +  The function should return the complete file name under which the
> +file should be saved, including the directory where it should be
> +saved, under which Emacs will ask the other program to save the file.

How would the function know what is the "right" directory to save the
file?  Without some hints to that effect, this documentation is not
very useful, IMO.

> +  If the file was successfully saved,

And if not?

>                                        the function is called again,
> +this time with the first argument set to @code{nil}, and the second
> +argument set to the file name that was returned.  The function should
> +then perform whatever action is appropriate (i.e., opening the file or
> +refreshing a directory listing.)             ^^^^

I guess, you mean "e.g." there.

More importantly, I don't understand why would Emacs need to do
anything with the file at all.  As a matter of fact, I don't think I
understand the purpose of this protocol at all, and I don't see it
clarified in the manual.  Can you explain what is this used for?
Without such explanation, this documentation lacks context without
which the information makes no sense.

Thanks.

Re: Documentation fix

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> Does this mean the function gets on the basename of the file, without
> any leading directories?  Or does it mean something else?

Yes.

>> +  The function should return the complete file name under which the
>> +file should be saved, including the directory where it should be
>> +saved, under which Emacs will ask the other program to save the file.
>
> How would the function know what is the "right" directory to save the
> file?  Without some hints to that effect, this documentation is not
> very useful, IMO.

How about:

  For example, a function defined for Dired buffers may want to return
  the directory containing the file under the position of the drop.

>> +  If the file was successfully saved,
>
> And if not?

Emacs never gets a reply from the program performing the drop, and thus
cannot do anything.

>>                                        the function is called again,
>> +this time with the first argument set to @code{nil}, and the second
>> +argument set to the file name that was returned.  The function should
>> +then perform whatever action is appropriate (i.e., opening the file or
>> +refreshing a directory listing.)             ^^^^
>
> I guess, you mean "e.g." there.

Yes, sorry.

> More importantly, I don't understand why would Emacs need to do
> anything with the file at all.  As a matter of fact, I don't think I
> understand the purpose of this protocol at all, and I don't see it
> clarified in the manual.  Can you explain what is this used for?
> Without such explanation, this documentation lacks context without
> which the information makes no sense.

It allows a program to drop files into a file manager, such as Dired,
and directly save the file into the directory that is currently open in
the file manager's window.

This is a three-step process:

  1. The program performing the drop sends the name of a file to Emacs,
  such as gen_sqrtab.c.

  2. Emacs replies with the file name under which the file should be
  saved.  If it's dropped on top of a Dired buffer visiting
  /export/home/user/Documents, for example, Emacs should reply with
  /export/home/user/Documents/gen_sqrtab.c.

  3. If saving the file is successful, the program performing the drop
  notifies Emacs, at which point the Dired buffer is reverted.

This protocol is mainly supported by web browsers and GTK based file
managers, and now Emacs as well.

Re: Documentation fix

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: emacs-devel@gnu.org
> Date: Fri, 07 Apr 2023 21:37:30 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Does this mean the function gets on the basename of the file, without
> > any leading directories?  Or does it mean something else?
> 
> Yes.
> 
> >> +  The function should return the complete file name under which the
> >> +file should be saved, including the directory where it should be
> >> +saved, under which Emacs will ask the other program to save the file.
> >
> > How would the function know what is the "right" directory to save the
> > file?  Without some hints to that effect, this documentation is not
> > very useful, IMO.
> 
> How about:
> 
>   For example, a function defined for Dired buffers may want to return
>   the directory containing the file under the position of the drop.
> 
> >> +  If the file was successfully saved,
> >
> > And if not?
> 
> Emacs never gets a reply from the program performing the drop, and thus
> cannot do anything.
> 
> >>                                        the function is called again,
> >> +this time with the first argument set to @code{nil}, and the second
> >> +argument set to the file name that was returned.  The function should
> >> +then perform whatever action is appropriate (i.e., opening the file or
> >> +refreshing a directory listing.)             ^^^^
> >
> > I guess, you mean "e.g." there.
> 
> Yes, sorry.
> 
> > More importantly, I don't understand why would Emacs need to do
> > anything with the file at all.  As a matter of fact, I don't think I
> > understand the purpose of this protocol at all, and I don't see it
> > clarified in the manual.  Can you explain what is this used for?
> > Without such explanation, this documentation lacks context without
> > which the information makes no sense.
> 
> It allows a program to drop files into a file manager, such as Dired,
> and directly save the file into the directory that is currently open in
> the file manager's window.
> 
> This is a three-step process:
> 
>   1. The program performing the drop sends the name of a file to Emacs,
>   such as gen_sqrtab.c.
> 
>   2. Emacs replies with the file name under which the file should be
>   saved.  If it's dropped on top of a Dired buffer visiting
>   /export/home/user/Documents, for example, Emacs should reply with
>   /export/home/user/Documents/gen_sqrtab.c.
> 
>   3. If saving the file is successful, the program performing the drop
>   notifies Emacs, at which point the Dired buffer is reverted.
> 
> This protocol is mainly supported by web browsers and GTK based file
> managers, and now Emacs as well.

Thanks.  I rewrote the documentation of the XDS support, please take a
look and tell if I made any mistakes.

Re: Documentation fix

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks.  I rewrote the documentation of the XDS support, please take a
> look and tell if I made any mistakes.

No, you didn't.  Thanks.

Documentation fix

[Robert Klein]

Hi,

there are two typos which causes compile to fail.  Patch below.

PS: Probably there should be a comma after the “example”.  Sorry, my
English not so good is...

Best regards
Robert





From 355901f48b9b81e9d5509f2df66e4f25eb23adae Mon Sep 17 00:00:00 2001
From: Robert Klein <roklein@roklein.de>
Date: Mon, 15 May 2017 08:31:19 +0200
Subject: [PATCH] Fix typos in Documentation

---
 doc/org.texi | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index d233001..d8173e7 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -11367,8 +11367,8 @@ The URL for the up link of exported HTML pages
(@code{org-html-link-up}). @cindex #+HTML_MATHJAX
 @vindex org-html-mathjax-options
 Options for MathJax (@code{org-html-mathjax-options}).  MathJax is
used to -typeset @LaTeX{} math in HTML documents.  @xref{Math
formatting in HTML -export} for an example.
+typeset @LaTeX{} math in HTML documents.  For an example @pxref{Math
+formatting in HTML export}. 
 
 @item HTML_HEAD
 @cindex #+HTML_HEAD
@@ -12198,7 +12198,7 @@ environments.  @code{:spread} has no effect if
@code{:width} is not set. @vindex org-latex-tables-booktabs
 @vindex org-latex-tables-centered
 All three commands are toggles.  @code{:booktabs} brings in modern
-typesetting enhancements to regular tables.  The @code {booktabs}
package has +typesetting enhancements to regular tables.  The
@code{booktabs} package has to be loaded through
@code{org-latex-packages-alist}.  @code{:center} is for centering the
table.  @code{:rmlines} removes all but the very first horizontal line
made of ASCII characters from "table.el" tables only.
-- 
2.6.6

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Robert Klein <roklein@roklein.de> writes:

> there are two typos which causes compile to fail.  Patch below.

Thank you.

>  Options for MathJax (@code{org-html-mathjax-options}).  MathJax is
> used to -typeset @LaTeX{} math in HTML documents.  @xref{Math
> formatting in HTML -export} for an example.
> +typeset @LaTeX{} math in HTML documents.  For an example @pxref{Math
> +formatting in HTML export}.

I don't get this one. It looks valid Texinfo to me. Also, "make info"
doesn't return any error here.

> -typesetting enhancements to regular tables.  The @code {booktabs}
> package has +typesetting enhancements to regular tables.  The
> @code{booktabs} package has to be loaded through
> @code{org-latex-packages-alist}.  @code{:center} is for centering the
> table.  @code{:rmlines} removes all but the very first horizontal line
> made of ASCII characters from "table.el" tables only.

Fixed.

Regards,

-- 
Nicolas Goaziou

Re: Documentation fix

[Robert Klein]

Hallo,

On Mon, 15 May 2017 08:42:42 +0200
Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> Hello,
> 
> Robert Klein <roklein@roklein.de> writes:
> 
> > there are two typos which causes compile to fail.  Patch below.
> 
> Thank you.
> 
> >  Options for MathJax (@code{org-html-mathjax-options}).  MathJax is
> > used to -typeset @LaTeX{} math in HTML documents.  @xref{Math
> > formatting in HTML -export} for an example.
> > +typeset @LaTeX{} math in HTML documents.  For an example
> > @pxref{Math +formatting in HTML export}.
> 
> I don't get this one. It looks valid Texinfo to me. Also, "make info"
> doesn't return any error here.

Ahh, well, on second look it only was a warning:

org.texi:11371: warning: `.' or `,' must follow @xref, not `f'.

Best regards
Robert

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Robert Klein <roklein@roklein.de> writes:

> Ahh, well, on second look it only was a warning:
>
> org.texi:11371: warning: `.' or `,' must follow @xref, not `f'.

Oddly, I don't get this warning when using "make info". Anyway, I added
the missing comma. Thank you.

Regards,

-- 
Nicolas Goaziou

Re: Documentation fix

[Colin Baxter]

>>>>> "Nicolas" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

    Nicolas> Hello, Robert Klein <roklein@roklein.de> writes:

    >> Ahh, well, on second look it only was a warning:
    >> 
    >> org.texi:11371: warning: `.' or `,' must follow @xref, not `f'.

    Nicolas> Oddly, I don't get this warning when using "make
    Nicolas> info". Anyway, I added the missing comma. Thank you.

    Nicolas> Regards,

    Nicolas> -- Nicolas Goaziou


It's depends on your version of makeinfo. For example with makeinfo (GNU
texinfo) 4.13, there are no warnings; however, with texi2any (GNU
texinfo) 6.0, as well as the above `.' or `,' warning, there are
multiple `@table has text but no @item' warnings. The docs still make ok, though.

Best wishes,
Colin.

-- 
--
Colin Baxter
m43cap@yandex.com
GnuPG fingerprint: 68A8 799C 0230 16E7 BF68  2A27 BBFA 2492 91F5 41C8

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Colin Baxter <m43cap@yandex.com> writes:

>>>>>> "Nicolas" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>     Nicolas> Hello, Robert Klein <roklein@roklein.de> writes:
>
>     >> Ahh, well, on second look it only was a warning:
>     >> 
>     >> org.texi:11371: warning: `.' or `,' must follow @xref, not `f'.
>
>     Nicolas> Oddly, I don't get this warning when using "make
>     Nicolas> info". Anyway, I added the missing comma. Thank you.
>
>     Nicolas> Regards,
>
>     Nicolas> -- Nicolas Goaziou
>
>
> It's depends on your version of makeinfo. For example with makeinfo (GNU
> texinfo) 4.13, there are no warnings; however, with texi2any (GNU
> texinfo) 6.0, as well as the above `.' or `,' warning, there are
> multiple `@table has text but no @item' warnings. The docs still make
> ok, though.

I see, thanks. Could you send the warnings, or better, a patch, so as to
fix them?

Regards,

-- 
Nicolas Goaziou

Re: Documentation fix

[Colin Baxter]

[-- Attachment #1: Type: text/plain, Size: 839 bytes --]

Dear Nicolas,

>>>>> "Nicolas" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

    Nicolas> I see, thanks. Could you send the warnings, or better, a
    Nicolas> patch, so as to fix them?

    Nicolas> Regards,

    Nicolas> -- Nicolas Goaziou


I have attached the warnings when making the documentation using
texi2any (GNU texinfo) 6.0, and a patch for the two '@itemx should not
begin @table' warnings. I am no expert on makeinfo and I just removed
the 'x' from 'itemx', so the patch is trivial. 

I'm not having any luck with the multiple warning: '@table has text but
no @item' warnings. They don't make much sense to me.

Since the docs make satisfactorily with the warnings, perhaps a note in
the documentation might suffice, to the effect that later versions of
texinfo may produce ignorable  warnings.

Best wishes,

Colin.


[-- Attachment #2: /home/redknight/git/org-mode/warnings.txt --]
[-- Type: message/external-body, Size: 101 bytes --]

[-- Attachment #3: /home/redknight/git/org-mode/itemx.patch --]
[-- Type: message/external-body, Size: 102 bytes --]

[-- Attachment #4: Type: text/plain, Size: 110 bytes --]



-- 
--
Colin Baxter
m43cap@yandex.com
GnuPG fingerprint: 68A8 799C 0230 16E7 BF68  2A27 BBFA 2492 91F5 41C8

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Colin Baxter <m43cap@yandex.com> writes:

> I have attached the warnings when making the documentation using
> texi2any (GNU texinfo) 6.0, and a patch for the two '@itemx should not
> begin @table' warnings. I am no expert on makeinfo and I just removed
> the 'x' from 'itemx', so the patch is trivial. 
>
> I'm not having any luck with the multiple warning: '@table has text but
> no @item' warnings. They don't make much sense to me.
>
> Since the docs make satisfactorily with the warnings, perhaps a note in
> the documentation might suffice, to the effect that later versions of
> texinfo may produce ignorable  warnings.

I'm unable to open the document you sent. I looks like they are not
properly attached to the mail. Could you send them again?

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

Re: Documentation fix

[Colin Baxter]

Dear Nicolas,

>>>>> "NG" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

    NG> Hello, Colin Baxter <m43cap@yandex.com> writes:

    >> I have attached the warnings when making the documentation using
    >> texi2any (GNU texinfo) 6.0, and a patch for the two '@itemx
    >> should not begin @table' warnings. I am no expert on makeinfo and
    >> I just removed the 'x' from 'itemx', so the patch is trivial.
    >> 
    >> I'm not having any luck with the multiple warning: '@table has
    >> text but no @item' warnings. They don't make much sense to me.
    >> 
    >> Since the docs make satisfactorily with the warnings, perhaps a
    >> note in the documentation might suffice, to the effect that later
    >> versions of texinfo may produce ignorable warnings.

    NG> I'm unable to open the document you sent. I looks like they are
    NG> not properly attached to the mail. Could you send them again?

    NG> Regards,

    NG> -- Nicolas Goaziou 0x80A93738

Sorry about my previous email.

I've appended (inline) the warnings associated with the documentation output
of 'make all', removing extraneous output.

---- Begin --------
org-version: 9.0.7 (release_9.0.7-478-g30ceb5)
makeinfo --no-split org.texi -o org
makeinfo --html --number-sections --no-split -o org.html org.texi
texi2pdf --batch --clean --expand org.texi
-:1267: warning: @itemx should not begin @table
-:1345: warning: @table has text but no @item
-:1370: warning: @table has text but no @item
-:1416: warning: @table has text but no @item
-:1558: warning: @table has text but no @item
-:1701: warning: @table has text but no @item
-:2837: warning: @table has text but no @item
-:2894: warning: @table has text but no @item
-:3146: warning: @table has text but no @item
-:4796: warning: @table has text but no @item
-:4933: warning: @table has text but no @item
-:5223: warning: @table has text but no @item
-:5454: warning: @table has text but no @item
-:5808: warning: @table has text but no @item
-:6177: warning: @table has text but no @item
-:6308: warning: @table has text but no @item
-:6485: warning: @table has text but no @item
-:6831: warning: @table has text but no @item
-:6891: warning: @table has text but no @item
-:6910: warning: @table has text but no @item
-:6994: warning: @table has text but no @item
-:7402: warning: @table has text but no @item
-:7590: warning: @table has text but no @item
-:7819: warning: @itemx should not begin @table
-:7838: warning: @table has text but no @item
-:7854: warning: @table has text but no @item
-:7949: warning: @table has text but no @item
-:8107: warning: @table has text but no @item
-:8173: warning: @table has text but no @item
-:8342: warning: @table has text but no @item
-:8726: warning: @table has text but no @item
-:9499: warning: @table has text but no @item
-:9569: warning: @table has text but no @item
-:9636: warning: @table has text but no @item
-:10342: warning: @table has text but no @item
-:10919: warning: @table has text but no @item
-:11233: warning: @table has text but no @item
-:11304: warning: @table has text but no @item
-:12533: warning: @table has text but no @item
-:13462: warning: @table has text but no @item
-:13881: warning: @table has text but no @item
-:14782: warning: @table has text but no @item
-:17653: warning: @table has text but no @item
This is pdfTeX, Version 3.1415926-2.5-1.40.14 (TeX Live 2013)
 restricted \write18 enabled.
entering extended mode
---------- Cut -----

The 'make all' process continues satisfactorily to its conclusion.

Deleting the 'x' from 'itemx' in org.texi at the lines corresponding to the
warnings '@itemx should not begin @table', that is, at lines 1267, 7819, 10342,
removes those warnings. That's all the patch did.

Best wishes,

Colin.

-- 
--
Colin Baxter
m43cap@yandex.com
GnuPG fingerprint: 68A8 799C 0230 16E7 BF68  2A27 BBFA 2492 91F5 41C8

Re: Documentation fix

[Nicolas Goaziou]

Hello,

Colin Baxter <m43cap@yandex.com> writes:

> I've appended (inline) the warnings associated with the documentation output
> of 'make all', removing extraneous output.
>
> ---- Begin --------
> org-version: 9.0.7 (release_9.0.7-478-g30ceb5)
> makeinfo --no-split org.texi -o org
> makeinfo --html --number-sections --no-split -o org.html org.texi
> texi2pdf --batch --clean --expand org.texi
> -:1267: warning: @itemx should not begin @table
> -:1345: warning: @table has text but no @item

[...]

>
> The 'make all' process continues satisfactorily to its conclusion.

These are innocuous warnings.  

> Deleting the 'x' from 'itemx' in org.texi at the lines corresponding to the
> warnings '@itemx should not begin @table', that is, at lines 1267, 7819, 10342,
> removes those warnings. That's all the patch did.

This would be wrong. The @orgcmd macro above already introduces @item,
so the second one really needs to be @itemx.

One solution would be to replace the @itemx ... with @xorgkey, @xorgcmd,
or @xorgcmdnki depending on the needs. But then, it would fall-back to
the other warning, i.e., a @table without any @item (all are
@orgsomething macros).

I'm no Texinfo expert, so I'm not sure what is the best way to handle
this. Maybe also create a special macro that would create a table. It
sounds convoluted, though.

Regards,

-- 
Nicolas Goaziou

Re: Documentation fix

[Colin Baxter]

Dear Nicolas,

>>>>> "NG" == Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

    NG> Hello, Colin Baxter <m43cap@yandex.com> writes:

    >> I've appended (inline) the warnings associated with the
    >> documentation output of 'make all', removing extraneous output.
    >> 
    >> ---- Begin -------- org-version: 9.0.7
    >> (release_9.0.7-478-g30ceb5) makeinfo --no-split org.texi -o org
    >> makeinfo --html --number-sections --no-split -o org.html org.texi
    >> texi2pdf --batch --clean --expand org.texi -:1267: warning:
    >> @itemx should not begin @table -:1345: warning: @table has text
    >> but no @item

    NG> [...]

    >> 
    >> The 'make all' process continues satisfactorily to its
    >> conclusion.

    NG> These are innocuous warnings.

    >> Deleting the 'x' from 'itemx' in org.texi at the lines
    >> corresponding to the warnings '@itemx should not begin @table',
    >> that is, at lines 1267, 7819, 10342, removes those
    >> warnings. That's all the patch did.

    NG> This would be wrong. The @orgcmd macro above already introduces
    NG> @item, so the second one really needs to be @itemx.

Yes, I see that.

    NG> One solution would be to replace the @itemx ... with @xorgkey,
    NG> @xorgcmd, or @xorgcmdnki depending on the needs. But then, it
    NG> would fall-back to the other warning, i.e., a @table without any
    NG> @item (all are @orgsomething macros).

    NG> I'm no Texinfo expert, so I'm not sure what is the best way to
    NG> handle this. Maybe also create a special macro that would create
    NG> a table. It sounds convoluted, though.

I'll look at this more carefully and see what I can do - if anything. It
will have to wait until I have the time, though.

Best wishes,

Colin.

-- 
--
Colin Baxter
m43cap@yandex.com
GnuPG fingerprint: 68A8 799C 0230 16E7 BF68  2A27 BBFA 2492 91F5 41C8