[AUCTeX-diffs] GNU AUCTeX branch, tex-build-only, updated. 6edd94a10202553bbc6a0622f697fe1664ee2bba

[Al Haji-Ali]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU AUCTeX".

The branch, tex-build-only has been updated
       via  6edd94a10202553bbc6a0622f697fe1664ee2bba (commit)
      from  683b9f9e04aae55218cd7fdcff7a16a0e6479f99 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 6edd94a10202553bbc6a0622f697fe1664ee2bba
Author: Al Haji-Ali <a.hajiali@hw.ac.uk>
Date:   Sun Mar 14 10:42:07 2021 +0000

    Added documentation for TeX-output-dir and related functions

diff --git a/doc/auctex.texi b/doc/auctex.texi
index fad97d6..4342b56 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -3905,6 +3905,39 @@ the current buffer, or if already there, to the file 
where the current
 process was started.
 @end deffn
 
+Additionally, output files produced by @AUCTeX{} can be placed in a
+separate directory.
+
+@defopt TeX-output-dir
+Set this option to the path of a directory where output files will be
+placed. The output files include those that are produced by applications
+running under @AUCTeX{}, temporary files related to region processing and
+the @previewlatex{} files. If a relative path is specified, it is
+interpreted as being relative to the master file in a mutlifile document.
+
+This is a buffer local variable and must be set separately for all
+documents and all files in a multifile document. For example,
+
+@example
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-output-dir: "build"
+%%% End:
+@end example
+
+Alternatively, you may use @code{setq-default} to set the default value of
+this option or set it as a directory local variable (see
+@code{add-dir-local-variable}).
+
+Note that a non-nil value of @code{TeX-output-dir} might be incompatible
+with some @TeX{} commands and macros. In particular, the @LaTeX{} macro
+@samp{\include} is known to not work with this option. Some @TeX{}
+packages which produce intermediary files might also be incompatible. A
+possible workaround for those packages is to append the value of
+@code{TeX-output-dir} to the environment variables @samp{TEXINPUTS} and
+@samp{BIBINPUTS}.
+@end defopt
+
 @node Cleaning
 @section Cleaning intermediate and output files
 @cindex Cleaning
diff --git a/preview.el.in b/preview.el.in
index 82b35f8..6d5159a 100644
--- a/preview.el.in
+++ b/preview.el.in
@@ -3331,7 +3331,7 @@ name(\\([^)]+\\))\\)\\|\
 ;;;   Too ugly to describe in detail.  In short, we try to catch file
 ;;;   names built from path components that don't contain spaces or
 ;;;   other special characters once the file extension has started.
-;;;  
+;;;
 ;;;   Position for searching immediately after the file name so as to
 ;;;   not miss closing parens or something.
 ;;;   (match-string 3) is the file name.
@@ -3980,7 +3980,7 @@ If FORMAT-CONS is non-nil, a previous format may get 
reused."
 \\catcode`/ 0 %
 \\def\\AUCTEXINPUT##1{\\catcode`/ 12\\relax\\catcode`\\ 
9\\relax\\input\\detokenize{##1}\\relax}%
 \\let\\dump\\PREVIEWdump\\dump}\\input mylatex.ltx \\relax%\n" nil dump-file)
-      (TeX-save-document 'TeX-master-file)
+      (TeX-save-document #'TeX-master-file)
       (prog1 (preview-generate-preview master command)
         (add-hook 'kill-emacs-hook #'preview-cleanout-tempfiles t)
         (setq TeX-sentinel-function
@@ -4067,7 +4067,7 @@ stored in `preview-dumped-alist'."
 (defun preview-document ()
   "Run preview on master document."
   (interactive)
-  (TeX-save-document 'TeX-master-file)
+  (TeX-save-document #'TeX-master-file)
   (setq TeX-current-process-region-p nil)
   (preview-generate-preview
    (TeX-master-file)
@@ -4162,10 +4162,10 @@ internal parameters, STR may be a log to insert into 
the current log."
       ((preview-format-name (shell-quote-argument
                              (concat "&"
                                      (preview-dump-file-name
-                                        ;; Get the filename from 
TeX-master-file with prv
-                                        ;; to get the correct path but then 
strip
-                                        ;; the extension
-                                        (file-name-sans-extension 
(TeX-master-file "prv" t))))))
+                                      ;; Get the filename from TeX-master-file 
with prv
+                                      ;; to get the correct path but then strip
+                                      ;; the extension
+                                      (file-name-sans-extension 
(TeX-master-file "prv" t))))))
        (process-environment (copy-sequence process-environment))
        (process
         (progn
diff --git a/tex-bar.el b/tex-bar.el
index fa2ccdd..4f90384 100644
--- a/tex-bar.el
+++ b/tex-bar.el
@@ -136,13 +136,13 @@ the argument BUTTON-ALIST in function 
`toolbarx-install-toolbar'."
 (defcustom TeX-bar-TeX-button-alist
   '((tex :image (lambda nil (if TeX-PDF-mode "pdftex" "tex"))
          :command (progn
-                    (TeX-save-document 'TeX-master-file)
+                    (TeX-save-document #'TeX-master-file)
                     (TeX-command "TeX" 'TeX-master-file -1))
          :help (lambda (&rest ignored)
                  (TeX-bar-help-from-command-list "TeX")))
     (pdftex :image "pdftex"
             :command (progn
-                       (TeX-save-document 'TeX-master-file)
+                       (TeX-save-document #'TeX-master-file)
                        (TeX-command "PDFTeX" 'TeX-master-file -1))
             :help (lambda (&rest ignored)
                     (TeX-bar-help-from-command-list "PDFTeX")))
@@ -277,13 +277,13 @@ the argument BUTTON-ALIST in function 
`toolbarx-install-toolbar'."
 (defcustom TeX-bar-LaTeX-button-alist
   '((latex :image (lambda nil (if TeX-PDF-mode "pdftex" "tex"))
            :command (progn
-                      (TeX-save-document 'TeX-master-file)
+                      (TeX-save-document #'TeX-master-file)
                       (TeX-command "LaTeX" 'TeX-master-file -1))
            :help (lambda (&rest ignored)
                    (TeX-bar-help-from-command-list "LaTeX")))
     (pdflatex :image "pdftex"
               :command (progn
-                         (TeX-save-document 'TeX-master-file)
+                         (TeX-save-document #'TeX-master-file)
                          (TeX-command "PDFLaTeX" 'TeX-master-file -1))
               :help (lambda (&rest ignored)
                       (TeX-bar-help-from-command-list "PDFLaTeX")))
diff --git a/tex-buf.el b/tex-buf.el
index f317cbc..5be8505 100644
--- a/tex-buf.el
+++ b/tex-buf.el
@@ -78,15 +78,19 @@
 (defun TeX-save-document (name-or-file-fn)
   "Save all files belonging to the current document.
 Return non-nil if document needs to be re-TeX'ed."
-  (interactive (list 'TeX-master-file))
+  (interactive (list #'TeX-master-file))
   (TeX-check-files (TeX--concat-ext name-or-file-fn (TeX-output-extension))
                    (cons (TeX--concat-ext name-or-file-fn) (TeX-style-list))
                    TeX-file-extensions))
 
 (defun TeX--concat-ext (name-or-file-fn &optional extension)
-  "Concatenate extension to NAME-OR-FILE-FN if it is a
-string. Otherwise assumes NAME-OR-FILE-FN is a callable function
-and calls it with extension as argument"
+  "Append EXTENSION to a filename specified by NAME-OR-FILE-FN.
+
+If NAME-OR-FILE-FN is a string, interpret it as the filename.
+Otherwise, assume it is a callable function and call it with
+EXTENSION as an argument and return the result without
+modification. EXTENSION is a string which should not include
+'.'."
   (if (stringp name-or-file-fn)
       (if extension
           (concat name-or-file-fn "." extension)
@@ -100,7 +104,7 @@ If a prefix argument OVERRIDE-CONFIRM is given, 
confirmation will
 depend on it being positive instead of the entry in `TeX-command-list'."
   (interactive "P")
   (TeX-master-file nil nil t)  ;; call to ask if necessary
-  (TeX-command (TeX-command-query 'TeX-master-file)
+  (TeX-command (TeX-command-query #'TeX-master-file)
                'TeX-master-file override-confirm))
 
 (defvar TeX-command-region-begin nil)
@@ -193,7 +197,7 @@ all text after `TeX-trailer-start'."
   ;; `nondirectory' argument, otherwise `TeX-command-default' called
   ;; within `TeX-command-query' won't work in included files not
   ;; placed in `TeX-master-directory'.
-  (TeX-command (TeX-command-query 'TeX-region-file) 'TeX-region-file
+  (TeX-command (TeX-command-query #'TeX-region-file) #'TeX-region-file
                override-confirm))
 
 (defun TeX-command-buffer (&optional override-confirm)
@@ -807,7 +811,7 @@ omitted) and `TeX-region-file'."
   "Guess the next command to be run on NAME."
   (let ((command-next nil)
         (name (TeX--concat-ext name-or-file-fn)))
-    (cond ((if (equal name-or-file-fn 'TeX-region-file)
+    (cond ((if (eq name-or-file-fn #'TeX-region-file)
                (TeX-check-files (TeX-region-file (TeX-output-extension))
                                 ;; Each original will be checked for all dirs
                                 ;; in `TeX-check-path' so this needs to be just
@@ -2240,7 +2244,7 @@ The compatibility argument IGNORE is ignored."
   ;; where we don't know which function has to be called.  Keep this in mind
   ;; should you want to use another argument here.
   (let ((master-dir (TeX-master-directory)))
-    (concat (or (TeX-master-output-dir master-dir nondirectory)
+    (concat (or (TeX--master-output-dir master-dir nondirectory)
                 (if nondirectory "" master-dir))
             (cond ((eq extension t)
                    (concat TeX-region "." TeX-default-extension))
diff --git a/tex.el b/tex.el
index fb1e7f2..447f0fc 100644
--- a/tex.el
+++ b/tex.el
@@ -183,7 +183,7 @@ If nil, none is specified."
 ;; `TeX-expand-list-builtin' for a description of the % escapes
 
 (defcustom TeX-command-list
-  '(("TeX" "%(PDF)%(tex) %(file-line-error) %`%(extraopts) %(output-dir) 
%S%(PDFout)%(mode)%' %t"
+  '(("TeX" "%(PDF)%(tex) %(file-line-error) %`%(extraopts) 
%S%(PDFout)%(mode)%' %(output-dir) %t"
      TeX-run-TeX nil
      (plain-tex-mode ams-tex-mode texinfo-mode) :help "Run plain TeX")
     ("LaTeX" "%`%l%(mode)%' %T"
@@ -194,7 +194,7 @@ If nil, none is specified."
      (texinfo-mode) :help "Run Makeinfo with Info output")
     ("Makeinfo HTML" "makeinfo %(extraopts) %(o-dir) --html %t" 
TeX-run-compile nil
      (texinfo-mode) :help "Run Makeinfo with HTML output")
-    ("AmSTeX" "amstex %(PDFout) %`%(extraopts) %(output-dir) %S%(mode)%' %t"
+    ("AmSTeX" "amstex %(PDFout) %`%(extraopts) %S%(mode)%' %(output-dir) %t"
      TeX-run-TeX nil (ams-tex-mode) :help "Run AMSTeX")
     ;; support for ConTeXt  --pg
     ;; first version of ConTeXt to support nonstopmode: 2003.2.10
@@ -2244,8 +2244,9 @@ output files."
       (message "No files to be deleted"))))
 
 (defun TeX--clean-extensions-regexp (&optional arg)
-  "Returns a regexp to match extensions that should be cleaned by TeX-clean.
-If the optional argument ARG is non-nil then output files are included"
+  "Return a regexp to match extensions that should be cleaned by `TeX-clean'.
+If the optional argument ARG is non-nil then output files are
+also included in the regexp."
   (let* ((mode-prefix (TeX-mode-prefix))
          (suffixes (and mode-prefix
                         (append (symbol-value
@@ -2428,12 +2429,10 @@ name of master file if it cannot be determined 
otherwise."
                                (or (string-match-p reg (concat "." extension))
                                    (string= "prv" extension))))
            (output-dir (and is-output-ext
-                            (TeX-master-output-dir
+                            (TeX--master-output-dir
                              (file-name-directory name)
                              nondirectory))))
       (if output-dir
-          ;; If output extesnion, use output-dir (directory is already removed)
-          ;; in TeX-master-output-dir
           (setq name (concat output-dir (file-name-nondirectory name)))
         ;; Remove directory if needed.
         (if nondirectory
@@ -2524,17 +2523,25 @@ be relative to that."
   :type 'string)
 
 (defcustom TeX-output-dir nil
-  "The directory where the output files will be generated. The
-  directory cannot start with a `.'.
+  "The path of the directory where output files should be placed.
 
-If this variable is nil, AUCTeX will assume that the output
-directory is the same as the directory of TeX-master."
+A relative path is interpreted as being relative to the master
+file in `TeX-master'. The path cannot contain a directory that
+starts with '.'. If this variable is nil, the output directory is
+assumed to be the same as the directory of `TeX-master'."
   :group 'TeX-file
-  :local t
   :safe 'string-or-null-p
-  :type 'string)
+  :type '(choice (const :tag "Directory of master file" nil)
+                 (string :tag "Custom" "build")))
+(make-variable-buffer-local 'TeX-output-dir)
+
+(defun TeX--master-output-dir (master-dir relative-to-master)
+  "Return nil if `TeX-output-dir' is nil, otherwise return the
+directory path where output files should be placed.
 
-(defun TeX-master-output-dir (master-dir relative-to-master)
+MASTER-DIR is the directory path where the master file is
+located. If RELATIVE-TO-MASTER is t, make the returned path
+relative to the directory in MASTER-DIR."
   (when TeX-output-dir
     (let* ((master-dir (expand-file-name (or master-dir "")))
            (out-dir (file-name-as-directory
@@ -2550,6 +2557,17 @@ directory is the same as the directory of TeX-master."
           (file-relative-name out-dir master-dir)
         out-dir))))
 
+(defun TeX--output-dir-arg (argname)
+  "Return the output directory after prepending ARGNAME or
+return an empty string if `TeX-output-dir' is nil.
+
+This is a helper function for formulating the output directory as
+a command argument."
+  (let ((out-dir (TeX--master-output-dir (TeX-master-directory) t)))
+    (if out-dir
+        (concat argname "\"" out-dir "\"")
+      "")))
+
 (defcustom TeX-style-local "style"
   "Directory containing hand generated TeX information.
 
@@ -2558,16 +2576,10 @@ be relative to that."
   :group 'TeX-file
   :type 'string)
 
-(defun TeX--output-dir-arg (argname)
-  (let ((out-dir (TeX-master-output-dir (TeX-master-directory) t)))
-    (if out-dir
-        (concat argname "\"" out-dir "\"")
-      "")))
-
 (defun TeX-split-string (regexp string)
   "Return a list of strings.
 Given REGEXP the STRING is split into sections which in string was
-seperated by REGEXP.
+separated by REGEXP.
 
 Examples:
 

-----------------------------------------------------------------------

Summary of changes:
 doc/auctex.texi | 33 +++++++++++++++++++++++++++++++++
 preview.el.in   | 14 +++++++-------
 tex-bar.el      |  8 ++++----
 tex-buf.el      | 20 ++++++++++++--------
 tex.el          | 54 +++++++++++++++++++++++++++++++++---------------------
 5 files changed, 89 insertions(+), 40 deletions(-)


hooks/post-receive
-- 
GNU AUCTeX