incorrect documentation for file-desc header argument?

incorrect documentation for file-desc header argument?

[Matt Huszagh]

Hello,

The org info documentation states

     The ‘file-desc’ header argument defines the description (see *note
     Link Format::) for the link.  If ‘file-desc’ has no value, Org uses
     the generated file name for both the “link” and “description” parts
     of the link.

However, if I evaluate the

#+BEGIN_SRC asymptote :results value file :file circle.pdf :output-dir img/
  size(2cm);
  draw(unitcircle);
#+END_SRC

I get

#+RESULTS:
[[file:img/circle.pdf]]

I believe the documentation (and this is corroborated by the discussion
of the original patch
(https://lists.gnu.org/archive/html/emacs-orgmode/2012-04/msg00022.html)),
that the intended result is

#+RESULTS:
[[file:img/circle.pdf][file:img/circle.pdf]]

Is my assessment correct? Can anyone else confirm this bug?

Thanks
Matt

Re: incorrect documentation for file-desc header argument?

[Matt Huszagh]

Matt Huszagh <huszaghmatt@gmail.com> writes:

> Hello,
>
> The org info documentation states
>
>      The ‘file-desc’ header argument defines the description (see *note
>      Link Format::) for the link.  If ‘file-desc’ has no value, Org uses
>      the generated file name for both the “link” and “description” parts
>      of the link.
>
> However, if I evaluate the
>
> #+BEGIN_SRC asymptote :results value file :file circle.pdf :output-dir img/
>   size(2cm);
>   draw(unitcircle);
> #+END_SRC
>
> I get
>
> #+RESULTS:
> [[file:img/circle.pdf]]
>
> I believe the documentation (and this is corroborated by the discussion
> of the original patch
> (https://lists.gnu.org/archive/html/emacs-orgmode/2012-04/msg00022.html)),
> that the intended result is
>
> #+RESULTS:
> [[file:img/circle.pdf][file:img/circle.pdf]]
>
> Is my assessment correct? Can anyone else confirm this bug?
>
> Thanks
> Matt

If this is indeed a bug, is there supposed to be a way to create the
current output?:

#+RESULTS:
[[file:img/circle.pdf]]

Re: incorrect documentation for file-desc header argument?

[Kyle Meyer]

Matt Huszagh writes:

> The org info documentation states
>
>      The ‘file-desc’ header argument defines the description (see *note
>      Link Format::) for the link.  If ‘file-desc’ has no value, Org uses
>      the generated file name for both the “link” and “description” parts
>      of the link.
>
> However, if I evaluate the
>
> #+BEGIN_SRC asymptote :results value file :file circle.pdf :output-dir img/
>   size(2cm);
>   draw(unitcircle);
> #+END_SRC
>
> I get
>
> #+RESULTS:
> [[file:img/circle.pdf]]
>
> I believe the documentation (and this is corroborated by the discussion
> of the original patch
> (https://lists.gnu.org/archive/html/emacs-orgmode/2012-04/msg00022.html)),
> that the intended result is
>
> #+RESULTS:
> [[file:img/circle.pdf][file:img/circle.pdf]]
>
> Is my assessment correct? Can anyone else confirm this bug?

Yeah, that looks to be the intended result of that thread.  That
thread's patch was applied with a58a4f0ad (new source block header
argument :filelinkdescr, 2012-03-27).  However, shortly after, that
treatment was intentionally changed (670c7f31c, 2012-03-31):

    simplified implementation of :file-desc header argument
  
    This will no longer insert the value of the :file header argument as
    the description if the description is left blank (as this changes
    the meaning of the :file header argument).
  
    The desc handling logic is moved to the `org-babel-result-to-file'
    function.

So, I'd say this is a documentation bug.

Re: incorrect documentation for file-desc header argument?

[Eric S Fraga]

On Wednesday, 29 Jul 2020 at 01:03, Kyle Meyer wrote:
> So, I'd say this is a documentation bug.

Yes or else many of my org files would cease to work as intended!

-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.3.7-682-geac255

Re: incorrect documentation for file-desc header argument?

[Matt Huszagh]

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

Kyle Meyer <kyle@kyleam.com> writes:

> Yeah, that looks to be the intended result of that thread.  That
> thread's patch was applied with a58a4f0ad (new source block header
> argument :filelinkdescr, 2012-03-27).  However, shortly after, that
> treatment was intentionally changed (670c7f31c, 2012-03-31):
>
>     simplified implementation of :file-desc header argument
>   
>     This will no longer insert the value of the :file header argument as
>     the description if the description is left blank (as this changes
>     the meaning of the :file header argument).
>   
>     The desc handling logic is moved to the `org-babel-result-to-file'
>     function.
>
> So, I'd say this is a documentation bug.

Thanks for the clarification Kyle. I've attached a patch that I believe
clarifies the documentation to match the current behavior.

Matt

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual.org-Modify-file-desc-header-argument-to-m.patch --]
[-- Type: text/x-patch, Size: 1056 bytes --]

From a9cd13f3d7b120a24b3416f8f8ba0892a8e47221 Mon Sep 17 00:00:00 2001
From: Matt Huszagh <huszaghmatt@gmail.com>
Date: Tue, 28 Jul 2020 22:10:12 -0700
Subject: [PATCH] org-manual.org: Modify file-desc header argument to match
 action

---
 doc/org-manual.org | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index b61644626..0f012d4df 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -17436,9 +17436,8 @@ default behavior is to automatically determine the result type.
 
   #+cindex: @samp{file-desc}, header argument
   The =file-desc= header argument defines the description (see
-  [[*Link Format]]) for the link.  If =file-desc= has no value, Org
-  uses the generated file name for both the "link" and
-  "description" parts of the link.
+  [[*Link Format]]) for the link.  If =file-desc= has no value, the
+  "description" part of the link will be omitted.
 
   #+cindex: @samp{sep}, header argument
   By default, Org assumes that a table written to a file has
-- 
2.27.0

Re: incorrect documentation for file-desc header argument?

[Kyle Meyer]

Matt Huszagh writes:

> Thanks for the clarification Kyle. I've attached a patch that I believe
> clarifies the documentation to match the current behavior.

Thank you.  Applied (521d7f5fe), tweaking the commit message a bit to
align more closely with the conventions described at
<https://orgmode.org/worg/org-contribute.html>.