From 17708ab3fa4f2a0f118bf86cebd4753f50e8bb26 Mon Sep 17 00:00:00 2001 From: Ihor Radchenko Date: Fri, 7 Oct 2022 18:03:18 +0800 Subject: [PATCH] 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 81be2b39c..95268d3e3 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