emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* incorrect documentation for file-desc header argument?
@ 2020-07-29  4:35 Matt Huszagh
  2020-07-29  4:50 ` Matt Huszagh
  2020-07-29  5:03 ` Kyle Meyer
  0 siblings, 2 replies; 6+ messages in thread
From: Matt Huszagh @ 2020-07-29  4:35 UTC (permalink / raw)
  To: emacs-orgmode@gnu.org

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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: incorrect documentation for file-desc header argument?
  2020-07-29  4:35 incorrect documentation for file-desc header argument? Matt Huszagh
@ 2020-07-29  4:50 ` Matt Huszagh
  2020-07-29  5:03 ` Kyle Meyer
  1 sibling, 0 replies; 6+ messages in thread
From: Matt Huszagh @ 2020-07-29  4:50 UTC (permalink / raw)
  To: emacs-orgmode@gnu.org

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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: incorrect documentation for file-desc header argument?
  2020-07-29  4:35 incorrect documentation for file-desc header argument? Matt Huszagh
  2020-07-29  4:50 ` Matt Huszagh
@ 2020-07-29  5:03 ` Kyle Meyer
  2020-07-29  7:41   ` Eric S Fraga
  2020-07-30  1:19   ` Matt Huszagh
  1 sibling, 2 replies; 6+ messages in thread
From: Kyle Meyer @ 2020-07-29  5:03 UTC (permalink / raw)
  To: Matt Huszagh; +Cc: emacs-orgmode

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.


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: incorrect documentation for file-desc header argument?
  2020-07-29  5:03 ` Kyle Meyer
@ 2020-07-29  7:41   ` Eric S Fraga
  2020-07-30  1:19   ` Matt Huszagh
  1 sibling, 0 replies; 6+ messages in thread
From: Eric S Fraga @ 2020-07-29  7:41 UTC (permalink / raw)
  To: Kyle Meyer; +Cc: Matt Huszagh, emacs-orgmode

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


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: incorrect documentation for file-desc header argument?
  2020-07-29  5:03 ` Kyle Meyer
  2020-07-29  7:41   ` Eric S Fraga
@ 2020-07-30  1:19   ` Matt Huszagh
  2020-07-30  2:29     ` Kyle Meyer
  1 sibling, 1 reply; 6+ messages in thread
From: Matt Huszagh @ 2020-07-30  1:19 UTC (permalink / raw)
  To: Kyle Meyer; +Cc: emacs-orgmode@gnu.org

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


^ permalink raw reply related	[flat|nested] 6+ messages in thread

* Re: incorrect documentation for file-desc header argument?
  2020-07-30  1:19   ` Matt Huszagh
@ 2020-07-30  2:29     ` Kyle Meyer
  0 siblings, 0 replies; 6+ messages in thread
From: Kyle Meyer @ 2020-07-30  2:29 UTC (permalink / raw)
  To: Matt Huszagh; +Cc: emacs-orgmode@gnu.org

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


^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2020-07-30  2:30 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-29  4:35 incorrect documentation for file-desc header argument? Matt Huszagh
2020-07-29  4:50 ` Matt Huszagh
2020-07-29  5:03 ` Kyle Meyer
2020-07-29  7:41   ` Eric S Fraga
2020-07-30  1:19   ` Matt Huszagh
2020-07-30  2:29     ` Kyle Meyer

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).