Confused about what the COMMENT keyword means

Confused about what the COMMENT keyword means

[Alain.Cochard]

Hello.  I have the file:

   * COMMENT foo
   #+EXPORT_FILE_NAME: foo.pdf
   #+TITLE: foot
   fofoo
   * bar
   #+EXPORT_FILE_NAME: bar.pdf
   #+TITLE: bart
   babar

If I do 'C-c e l p', the file 'foo.pdf' is created from the 'foo.tex'
file.  The content is bar'ish, though, as I expect.

By contrast, with this file

   # * foo
   # #+EXPORT_FILE_NAME: foo.pdf
   # #+TITLE: foot
   # fofoo
   * bar
   #+EXPORT_FILE_NAME: bar.pdf
   #+TITLE: bart
   babar

for which I explicitly comment the whole 'foo' tree, the content is the
same but the files are 'bar.pdf' and 'bar.tex'.

But I thought both way of commenting were equivalent.  What am I
missing?  Thank you.

NB: I used 'emacs -Q'

GNU Emacs 27.2 (build 1, x86_64-redhat-linux-gnu, GTK+ Version
3.24.30, cairo version 1.17.4) of 2021-08-07

Org mode version 9.4.4 (release_9.4.4 @
/usr/share/emacs/27.2/lisp/org/)

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Confused about what the COMMENT keyword means

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> Hello.  I have the file:
>
>    * COMMENT foo
>    #+EXPORT_FILE_NAME: foo.pdf
>    #+TITLE: foot
>    fofoo
>    * bar
>    #+EXPORT_FILE_NAME: bar.pdf
>    #+TITLE: bart
>    babar

#+EXPORT_FILE_NAME is an in-buffer export setting with global effect.
According to 13.2 Export Settings section of the Org manual,

       In-buffer settings may appear anywhere in the file, either directly
    or indirectly through a file included using ‘#+SETUPFILE: filename or
    URL’ syntax.

Because export settings are global, they have higher priority over the
COMMENTed heading.

Further, you have two instances of the #+EXPORT_FILE_NAME in your
buffer. The behaviour of Org is undefined in such scenario, but the
current implementation detail makes Org use the first instance found in
the file during export.

Do note that usage of #+EXPORT_FILE_NAME and #+TITLE like in your
example is erroneous - they do not apply to their subtrees. Please use
heading properties instead for the desired effect.

> By contrast, with this file
> 
>    # * foo
>    # #+EXPORT_FILE_NAME: foo.pdf
>    # #+TITLE: foot
>    # fofoo
>    * bar
>    #+EXPORT_FILE_NAME: bar.pdf
>    #+TITLE: bart
>    babar

This file contains no export settings.
# #+EXPORT_FILE_NAME: foo.pdf
line is not an export setting. It does not matter that it is a comment,
blah#+EXPORT_FILE_NAME: foo.pdf
would not work either.

--------

I think that the manual is not clear enough about applying in-buffer
settings and keywords. We may want to clarify this detail.

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92

Re: Confused about what the COMMENT keyword means

[Alain.Cochard]

Thanks for answering.

Ihor Radchenko writes on Tue 27 Sep 2022 09:55:
 > Alain.Cochard@unistra.fr writes:
 > 
 > > Hello.  I have the file:
 > >
 > >    * COMMENT foo
 > >    #+EXPORT_FILE_NAME: foo.pdf
 > >    #+TITLE: foot
 > >    fofoo
 > >    * bar
 > >    #+EXPORT_FILE_NAME: bar.pdf
 > >    #+TITLE: bart
 > >    babar
 > 
 > #+EXPORT_FILE_NAME is an in-buffer export setting with global effect.
 > According to 13.2 Export Settings section of the Org manual,
 > 
 >        In-buffer settings may appear anywhere in the file, either directly
 >     or indirectly through a file included using ‘#+SETUPFILE: filename or
 >     URL’ syntax.
 > 
 > Because export settings are global, they have higher priority over the
 > COMMENTed heading.

OK, I can understand that but if, as I now see in 13.2, both TITLE and
EXPORT_FILE_NAME are export settings, why does it behaves as I expect
for TITLE (the title I get is indeed 'bart') but not for
EXPORT_FILE_NAME?

 > [...]
 
 > > By contrast, with this file
 > > 
 > >    # * foo
 > >    # #+EXPORT_FILE_NAME: foo.pdf
 > >    # #+TITLE: foot
 > >    # fofoo
 > >    * bar
 > >    #+EXPORT_FILE_NAME: bar.pdf
 > >    #+TITLE: bart
 > >    babar
 > 
 > This file contains no export settings.

I don't understand that: what about the line '#+EXPORT_FILE_NAME:
bar.pdf'??

 > # #+EXPORT_FILE_NAME: foo.pdf line is not an export setting. It
 > does not matter that it is a comment,

Yes, of course; if it is a comment, it is as if it were not here at
all, correct?

 > I think that the manual is not clear enough about applying
 > in-buffer settings and keywords. We may want to clarify this
 > detail.

How about adding a sentence in 13.6, perhaps in the footnote?
Something like "Also note that, as mentioned in 13.2, export
settings, being global, take precedence over the 'COMMENT' keyword."

Finally, I'd appreciate a "SUPERCOMMENT" keyword, which would be
equivalent (when exporting) to removing the tree altogether (or, as I
understand, prepending '# ' to each line of the tree).




-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: Confused about what the COMMENT keyword means

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

>  >        In-buffer settings may appear anywhere in the file, either directly
>  >     or indirectly through a file included using ‘#+SETUPFILE: filename or
>  >     URL’ syntax.
>  > 
>  > Because export settings are global, they have higher priority over the
>  > COMMENTed heading.
>
> OK, I can understand that but if, as I now see in 13.2, both TITLE and
> EXPORT_FILE_NAME are export settings, why does it behaves as I expect
> for TITLE (the title I get is indeed 'bart') but not for
> EXPORT_FILE_NAME?

This is a valid observation.
I checked the code more closely, and I have to admit that I was wrong.
Commented subtrees are, in fact, obeyed. Obeyed for all the keywords
_but_ the EXPORT_FILE_NAME!

Basically, including files, removing commented subtrees, and other
excluded elements is done in `org-export-as' function. It is done before
setting export options.

However, `org-export-as' is generally called inside `org-export-to-file'
and `org-export-to-file' needs to know which file to export to in
advance; before the buffer is stripped of commented trees. That's why
there is the observed inconsistency between EXPORT_FILE_NAME and TITLE
settings.

>  > > By contrast, with this file
>  > > 
>  > >    # * foo
>  > >    # #+EXPORT_FILE_NAME: foo.pdf
>  > >    # #+TITLE: foot
>  > >    # fofoo
>  > >    * bar
>  > >    #+EXPORT_FILE_NAME: bar.pdf
>  > >    #+TITLE: bart
>  > >    babar
>  > 
>  > This file contains no export settings.
>
> I don't understand that: what about the line '#+EXPORT_FILE_NAME:
> bar.pdf'??

Sorry, I was referring to the commented part only.

Let me clarify what I was referring to.

If you have a keyword like

#+KEYWORD: value

Org parses it like (keyword) syntax.

and if you comment the keyword as

# #+KEYWORD: value

Org will _not_ parse something like (comment (keyword))
It will stop by seeing a (comment) and will not look further.
Such keyword will be ignored all the times and no special arrangement is
required during the export process.

* COMMENT headings

are different.

If you have something like

* COMMENT heading
#+KEYWORD: value

Org does look inside:
(heading (:commentedp t) (keyword))

Then, such keyword can contribute to calculation of buffer settings.
It is only `org-export-as' that makes special arrangement and physically
removes COMMENTed subtrees before exporting the buffer.

Hope it is now more clear.

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92

Re: Confused about what the COMMENT keyword means

[Alain.Cochard]

Ihor Radchenko writes on Tue 27 Sep 2022 15:40:

 > However `org-export-as' is generally called inside
 > `org-export-to-file' and `org-export-to-file' needs to know which
 > file to export to in advance; before the buffer is stripped of
 > commented trees. That's why there is the observed inconsistency
 > between EXPORT_FILE_NAME and TITLE settings.

 > [...]
 
 > If you have something like
 > 
 > * COMMENT heading
 > #+KEYWORD: value
 > 
 > Org does look inside:
 > (heading (:commentedp t) (keyword))
 > 
 > Then, such keyword can contribute to calculation of buffer
 > settings.  It is only `org-export-as' that makes special
 > arrangement and physically removes COMMENTed subtrees before
 > exporting the buffer.
 > 
 > Hope it is now more clear.

Yes, thanks a lot, much clearer.

I can only hope that the "observed inconsistency" related to
EXPORT_FILE_NAME can be resolved.

I still feel that section 13.6 of the manual can only been interpreted
as: COMMENTing a tree is equivalent to commenting the tree.  I update
my suggestion of addendum to the footnote:

   Note that the subtree is still parsed and '#+KEYWORD: value' pairs
   can contribute to calculation of buffer settings, in particular
   '#+EXPORT_FILE_NAME: value'.

Incidentally, could you provide another example of a buffer setting
that would be taken into account even in a COMMENTed subtree?  (I
tried a few without success.)

Regards

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

[BUG] EXPORT_FILE_NAME keyword is used by `org-export-output-file-name' before macro expansion/INCLUDEs/removing COMMENTed trees (was: Confused about what the COMMENT keyword means)

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> I can only hope that the "observed inconsistency" related to
> EXPORT_FILE_NAME can be resolved.

Well. I do consider this a bug. However, it is not easy to fix.
`org-export-output-file-name' is used across all ox-*.el backends,
including third-party packages, and it is called before we can determine
which parts of the exported file are going to be really exported.

I recommend you to use :EXPORT_FILE_NAME: headline property and export
using subtree scope.

> I still feel that section 13.6 of the manual can only been interpreted
> as: COMMENTing a tree is equivalent to commenting the tree.  I update
> my suggestion of addendum to the footnote:
>
>    Note that the subtree is still parsed and '#+KEYWORD: value' pairs
>    can contribute to calculation of buffer settings, in particular
>    '#+EXPORT_FILE_NAME: value'.
> Incidentally, could you provide another example of a buffer setting
> that would be taken into account even in a COMMENTed subtree?  (I
> tried a few without success.)

There should be no other buffer setting that is taken into account
in COMMENTed subtrees. EXPORT_FILE_NAME is the only one.

I think that we should not really change the manual unless we have to.
It will be better to fix the bug instead.

-- 
Ihor Radchenko,
Org mode contributor,
Learn more about Org mode at https://orgmode.org/.
Support Org development at https://liberapay.com/org-mode,
or support my work at https://liberapay.com/yantar92

Confirmed.

Re: [BUG] EXPORT_FILE_NAME keyword is used by `org-export-output-file-name' before macro expansion/INCLUDEs/removing COMMENTed trees (was: Confused about what the COMMENT keyword means)

[Alain.Cochard]

Ihor Radchenko writes on Sun  2 Oct 2022 12:48:

 > I recommend you to use :EXPORT_FILE_NAME: headline property and export
 > using subtree scope.

Thanks a lot for the tip.  A suggestion: that the :TITLE: property be
used if it exists.


 > > I can only hope that the "observed inconsistency" related to
 > > EXPORT_FILE_NAME can be resolved.

 > Well. I do consider this a bug. However, it is not easy to fix.
 > [...]
 > I think that we should not really change the manual unless we have
 > to.  It will be better to fix the bug instead.

Yes, but if the bug is difficult to fix, it might be fixed only in a
long time (if ever).  In the mean time, I would say it is better to
warn the user.

-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 106]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: [BUG] EXPORT_FILE_NAME keyword is used by `org-export-output-file-name' before macro expansion/INCLUDEs/removing COMMENTed trees (was: Confused about what the COMMENT keyword means)

[Alain.Cochard]

Alain.Cochard@unistra.fr writes on Tue 11 Oct 2022 16:42:
 > Ihor Radchenko writes on Sun  2 Oct 2022 12:48:
 > 
 >  > I recommend you to use :EXPORT_FILE_NAME: headline property and export
 >  > using subtree scope.
 > 
 > Thanks a lot for the tip.  A suggestion: that the :TITLE: property
 > be used if it exists.

Well, I just read about the EXPORT_ prefix properties for subtree
export, hence realized that the :EXPORT_TITLE: property can be used
for what I had in mind above.

PS: there are a few occurrences of 'sub-tree' in the manual, but many
of 'subtree'; I suggest to use 'subtree' everywhere -- better
regarding searching.


-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: [BUG] EXPORT_FILE_NAME keyword is used by `org-export-output-file-name' before macro expansion/INCLUDEs/removing COMMENTed trees (was: Confused about what the COMMENT keyword means)

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

> PS: there are a few occurrences of 'sub-tree' in the manual, but many
> of 'subtree'; I suggest to use 'subtree' everywhere -- better
> regarding searching.

Good point.
Fixed on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=044f09aa6de8f1f38de0f9b517510690807b4ef2

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

[FR] Allow TITLE to be used as default export file name (was: [BUG] EXPORT_FILE_NAME keyword is used by `org-export-output-file-name' before macro expansion/INCLUDEs/removing COMMENTed trees (was: Confused about what the COMMENT keyword means))

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

>  > I recommend you to use :EXPORT_FILE_NAME: headline property and export
>  > using subtree scope.
>
> Thanks a lot for the tip.  A suggestion: that the :TITLE: property be
> used if it exists.

We currently fall back to file name if nothing else works.
Using TITLE is possible but cannot be done by default as a fallback ---
existing users relying on current behaviour will be affected by such
change.

We may add a defcustom though. It will be nil by default and setting it
to non-nil will make Org export fall back to TITLE rather than file
name.

However, there is no point adding yet another option if not many users
are interested. I am changing the subject of this email to facilitate
the feedback.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [FR] Allow TITLE to be used as default export file name (was: [BUG] EXPORT_FILE_NAME keyword is used by `org-export-output-file-name' before macro expansion/INCLUDEs/removing COMMENTed trees (was: Confused about what the COMMENT keyword means))

[Alain.Cochard]

Ihor Radchenko writes on Thu 10 Nov 2022 02:03:
 > Alain.Cochard@unistra.fr writes:
 > 
 > > > I recommend you to use :EXPORT_FILE_NAME: headline property and
 > > > export using subtree scope.
 > >
 > > Thanks a lot for the tip.  A suggestion: that the :TITLE:
 > > property be used if it exists.
 > 
 > We currently fall back to file name if nothing else works.  Using
 > TITLE is possible but cannot be done by default as a fallback ---
 > existing users relying on current behaviour will be affected by
 > such change.
 > 
 > We may add a defcustom though. It will be nil by default and
 > setting it to non-nil will make Org export fall back to TITLE
 > rather than file name.
 > 
 > However, there is no point adding yet another option if not many
 > users are interested. I am changing the subject of this email to
 > facilitate the feedback.

I am surprised by this message: like I said earlier when replying to
myself to the same message as the one to which you are replying, I
discovered the :EXPORT_TITLE: (headline) property, which does exactly
what I was looking for.

It is as if you missed that message of mine (or did not understand
what I wanted to say) AND forgot or don't know about the
:EXPORT_TITLE: property.  As I find it rather unlikely, I guess you
are thinking of something else, which is beyond me.

At any rate, there is no need for anything new in this repect, even
for me.

Best.


-- 
EOST (École et Observatoire des Sciences de la Terre) 
ITE (Institut Terre & Environnement) | alain.cochard@unistra.fr
5 rue René Descartes   [bureau 110]  | Phone: +33 (0)3 68 85 50 44 
F-67084 Strasbourg Cedex, France     | [ slot available for rent ]

Re: [FR] Allow TITLE to be used as default export file name (was: [BUG] EXPORT_FILE_NAME keyword is used by `org-export-output-file-name' before macro expansion/INCLUDEs/removing COMMENTed trees (was: Confused about what the COMMENT keyword means))

[Ihor Radchenko]

Alain.Cochard@unistra.fr writes:

>  > > > I recommend you to use :EXPORT_FILE_NAME: headline property and
>  > > > export using subtree scope.
>  > >
>  > > Thanks a lot for the tip.  A suggestion: that the :TITLE:
>  > > property be used if it exists.
>  > 
>  > We currently fall back to file name if nothing else works.  Using
>  > TITLE is possible but cannot be done by default as a fallback ---
>  > existing users relying on current behaviour will be affected by
>  > such change.
>
> I am surprised by this message: like I said earlier when replying to
> myself to the same message as the one to which you are replying, I
> discovered the :EXPORT_TITLE: (headline) property, which does exactly
> what I was looking for.
>
> It is as if you missed that message of mine (or did not understand
> what I wanted to say) AND forgot or don't know about the
> :EXPORT_TITLE: property.  As I find it rather unlikely, I guess you
> are thinking of something else, which is beyond me.

Hmm. I think I misinterpreted your message. I thought that you were
talking about file name, not the title inside the exported document.

> At any rate, there is no need for anything new in this repect, even
> for me.

Noted.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [BUG] EXPORT_FILE_NAME keyword is used by `org-export-output-file-name' before macro expansion/INCLUDEs/removing COMMENTed trees (was: Confused about what the COMMENT keyword means)

[Ihor Radchenko]

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

Ihor Radchenko <yantar92@gmail.com> writes:

> There should be no other buffer setting that is taken into account
> in COMMENTed subtrees. EXPORT_FILE_NAME is the only one.
>
> I think that we should not really change the manual unless we have to.
> It will be better to fix the bug instead.

I am attaching a tentative change to ox.el machinery that will allow
calculating EXPORT_FILE_NAME dynamically inside the processed export
buffer.

The change is not yet fixing the bug. I just want to hear feedback
on the approach I used.

Let me know if you see any issues or have better ideas.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-export-Allow-export-file-name-to-be-determined-a.patch --]
[-- Type: text/x-patch, Size: 6628 bytes --]

From 57aa366e9d5596741c256688c9b8ef07a9b24e17 Mon Sep 17 00:00:00 2001
Message-Id: <57aa366e9d5596741c256688c9b8ef07a9b24e17.1668044888.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Thu, 10 Nov 2022 09:39:20 +0800
Subject: [PATCH] org-export: Allow export file name to be determined after
 export processing

* lisp/ox.el (org-export-as): When :output-file info property is set
to a list, calculate :output-file after expanding macros, removing
uninterpreted data, and other processing.  Use the list value is used
as argument list for `org-export-output-file-name'.  Add new optional
argument WITH-INFO to return the info channel in addition to the
export string.
(org-export-to-file): Allow FILE argument to be an argument list to be
passed to `org-export-output-file-name' in the processed export
buffer.

This patch allows calculating the output file name after expanding all
the macros, cleaning up commented trees, and other export processing.
In particular, #+EXPORT_FILE_NAME keywords inside commented trees can
be ignored in contrast to what `org-export-output-file-name' returns
on the original Org file.

This patch is not changing any existing behavior and not fixing the
reported byg.  The callers of `org-export-to-file' still need to
change FILE argument to make use of the changes herein.

Reported-by: Alain.Cochard@unistra.fr
Link: https://orgmode.org/list/25422.27044.980916.495348@gargle.gargle.HOWL
---
 lisp/ox.el | 59 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 42 insertions(+), 17 deletions(-)

diff --git a/lisp/ox.el b/lisp/ox.el
index 770f86740..82cf0d166 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -2994,7 +2994,8 @@ (defun org-export--remove-uninterpreted-data (data info)
 
 ;;;###autoload
 (defun org-export-as
-    (backend &optional subtreep visible-only body-only ext-plist)
+    (backend
+     &optional subtreep visible-only body-only ext-plist with-info)
   "Transcode current Org buffer into BACKEND code.
 
 BACKEND is either an export back-end, as returned by, e.g.,
@@ -3020,7 +3021,10 @@ (defun org-export-as
 with external parameters overriding Org default settings, but
 still inferior to file-local settings.
 
-Return code as a string."
+Return code as a string.
+
+When optional argument WITH-INFO is non-nil, return a cons cell with car
+containing return code string and cdr containing the info channel."
   (when (symbolp backend) (setq backend (org-export-get-backend backend)))
   (org-export-barf-if-invalid-backend backend)
   (org-fold-core-ignore-modifications
@@ -3106,6 +3110,14 @@ (defun org-export-as
 			     p
 			     (org-export--remove-uninterpreted-data value info))))
 	       (_ nil)))
+           ;; Update `:output-file' option if needed.
+           (let ((output-file (plist-get info :output-file)))
+             (when (and output-file (listp output-file))
+               (plist-put
+                info :output-file
+                (apply #'org-export-output-file-name
+                       ;; `:output-file' contains argument list.
+                       output-file))))
 	   ;; Install user's and developer's filters.
 	   (setq info (org-export-install-filters info))
 	   ;; Call options filters and update export options.  We do not
@@ -3155,10 +3167,13 @@ (defun org-export-as
 	     ;; Remove all text properties since they cannot be
 	     ;; retrieved from an external process.  Finally call
 	     ;; final-output filter and return result.
-	     (org-no-properties
-	      (org-export-filter-apply-functions
-	       (plist-get info :filter-final-output)
-	       output info)))))))))
+             (let ((final-output
+	            (org-no-properties
+	             (org-export-filter-apply-functions
+	              (plist-get info :filter-final-output)
+	              output info))))
+               (if with-info (cons final-output info)
+                 final-output)))))))))
 
 ;;;###autoload
 (defun org-export-string-as (string backend &optional body-only ext-plist)
@@ -6637,7 +6652,10 @@ (defun org-export-to-file
 BACKEND is either an export back-end, as returned by, e.g.,
 `org-export-create-backend', or a symbol referring to
 a registered back-end.  FILE is the name of the output file, as
-a string.
+a string.  FILE can also be a list of options to determine file name
+automatically.  The options will be used as arguments of
+`org-export-output-file-name', which will be called right before
+:filter-options filter inside the cleaned buffer to be exported.
 
 A non-nil optional argument ASYNC means the process should happen
 asynchronously.  The resulting buffer will then be accessible
@@ -6664,26 +6682,33 @@   (defun org-latex-export-to-latex
 POST-PROCESS needs to be quoted.
 
 The function returns either a file name returned by POST-PROCESS,
-or FILE."
+or FILE written."
   (declare (indent 2))
-  (if (not (file-writable-p file)) (error "Output file not writable")
+  (if (and (stringp file) (not (file-writable-p file)))
+      (error "Output file not writable")
     (let ((ext-plist (org-combine-plists `(:output-file ,file) ext-plist))
 	  (encoding (or org-export-coding-system buffer-file-coding-system)))
       (if async
           (org-export-async-start
 	      (lambda (file)
 		(org-export-add-to-stack (expand-file-name file) backend))
-	    `(let ((output
-		    (org-export-as
-		     ',backend ,subtreep ,visible-only ,body-only
-		     ',ext-plist)))
+	    `(let* ((output
+		     (org-export-as
+		      ',backend ,subtreep ,visible-only ,body-only
+		      ',ext-plist ,(when (listp file) 'with-info)))
+                    (file ,(if (listp file) '(cdr output) file)))
+               (when (consp output) (setq output (car output)))
 	       (with-temp-buffer
 		 (insert output)
 		 (let ((coding-system-for-write ',encoding))
-		   (write-region (point-min) (point-max) ,file)))
-	       (or (ignore-errors (funcall ',post-process ,file)) ,file)))
-        (let ((output (org-export-as
-                       backend subtreep visible-only body-only ext-plist)))
+		   (write-region (point-min) (point-max) file)))
+	       (or (ignore-errors (funcall ',post-process file)) file)))
+        (let* ((output (org-export-as
+                        backend subtreep visible-only
+                        body-only ext-plist
+                        (when (listp file) 'with-info)))
+               (file (if (listp file) (cdr output) file)))
+          (when (consp output) (setq output (car output)))
           (with-temp-buffer
             (insert output)
             (let ((coding-system-for-write encoding))
-- 
2.35.1


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>