[elpa] externals/org 17708ab3fa 2/3: org-export-copy-buffer: Document the caveats

[ELPA Syncer]

branch: externals/org
commit 17708ab3fa4f2a0f118bf86cebd4753f50e8bb26
Author: Ihor Radchenko <yantar92@gmail.com>
Commit: Ihor Radchenko <yantar92@gmail.com>

    org-export-copy-buffer: Document the caveats
    
    * lisp/ox.el (org-export-copy-buffer): Mention that `buffer-file-name'
    is copied around and explain the consequences.  Document why
    `buffer-file-name' is copied.
---
 lisp/ox.el | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/lisp/ox.el b/lisp/ox.el
index 81be2b39cc..95268d3e38 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -2551,6 +2551,16 @@ Return the updated communication channel."
 The copy preserves Org buffer-local variables, visibility and
 narrowing.
 
+IMPORTANT: The buffer copy may also have `buffer-file-name' copied.
+To prevent Emacs overwriting the original buffer file,
+`write-contents-functions' is set to (always).  Do not alter this
+variable and do not do anything that might alter it (like calling a
+major mode) to prevent data corruption.  Also, do note that Emacs may
+jump into the created buffer if the original file buffer is closed and
+then re-opened.  Making edits in the buffer copy may also trigger
+Emacs save dialogue.  Prefer using `org-export-with-buffer-copy' macro
+when possible.
+
 When optional argument BUFFER is non-nil, copy into BUFFER.
 
 Optional arguments DROP-VISIBILITY, DROP-NARROWING, DROP-CONTENTS, and
@@ -2630,6 +2640,10 @@ The function assumes BUFFER's major mode is `org-mode'."
                     (and (not (memq var org-export-ignored-local-variables))
                          (or (memq var
                                    '(default-directory
+                                       ;; Required to convert file
+                                       ;; links in the #+INCLUDEd
+                                       ;; files.  See
+                                       ;; `org-export--prepare-file-contents'.
                                       buffer-file-name
                                       buffer-file-coding-system
                                        ;; Needed to preserve folding state