[add] How-To in the book for AucTeX and Tectonic

Author: KaranAhlawat

docs/src/SUMMARY.md

@@ -33,3 +33,4 @@
 - [Building Tectonic](howto/build-tectonic/index.md)
   - [Install Dependencies Externally](howto/build-tectonic/external-dep-install.md)
   - [Install Dependencies With cargo-vcpkg](howto/build-tectonic/cargo-vcpkg-dep-install.md)
+- [Use Tectonic with AucTeX](howto/auctex-setup/index.md)

docs/src/howto/auctex-setup/index.md

@@ -0,0 +1,92 @@
+# How To: Use Tectonic with AucTeX
+
+This section is a guide aimed at [GNU Emacs](https://www.gnu.org/software/emacs/) users for setting up [AucTeX](https://www.gnu.org/software/auctex/) with Tectonic as the TeX/LaTeX distribution.
+
+## Basic Prerequisites
+
+To follow this section you will need Tectonic and GNU Emacs installed on your system. Additionally, you will require the AucTeX emacs package to be installed before
+following along.
+
+> Note: This section makes use of the V2 tectonic CLI, invoked using the `nextonic` command.
+
+## Setup
+
+All the code displayed in this section should go into your `init.el` file (or `config.el` if you are using [Doomemacs](https://github.com/doomemacs/)).
+
+First, load the AucTeX package.
+
+```lisp
+(require 'latex)
+```
+
+You will need to set the default TeX engine AucTeX uses to figure out the build commands to use Tectonic instead of traditional TeX distributions. Therefore we have to modify the `TeX-engine-alist` varible.
+* The first element of the list is the symbol that AucTeX recognizes.
+* The second element is a string with the name of the TeX distribution.
+* The third element is the shell command for compiling plain TeX documents.
+* The fourth element is the shell command for compiling LaTeX documents. Here we are assuming the user is using a Tectonic project (generated using `nextonic new <proj-name>`).
+* The last element is the shell command for compiling ConTeXt documents, left unconfigured for now.
+
+```lisp
+(setq TeX-engine-alist '((default
+                          "Tectonic"
+                          "nextonic compile -f plain %T"
+                          "nextonic watch"
+                          nil)))
+```
+
+Next, modify the `LaTeX-command-style` so that AucTex doesn't add extra options to it that Tectonic does not recognize. We simply set it to the `%(latex)` expansion (from `TeX-expand-list-builtin`), removing any other extra options.
+
+```lisp
+(setq LaTeX-command-style '(("" "%(latex)")))
+```
+
+We need to set the `TeX-check-TeX` variable to `nil` since AucTeX will try to find a traditional distibution like `TeXLive` or others, and will fail since Tectonic doesn't meet it's criteria.
+
+Additionally, we should also set `TeX-process-asynchronous` to `t`, so that running Tectonic in watch mode doesn't hang up Emacs.
+
+We'll also just ensure that the `TeX-engine` is set to `default`.
+
+```lisp
+(setq TeX-process-asynchronous t
+      TeX-check-TeX nil
+      TeX-engine 'default)
+```
+
+Finally, modify the `TeX-command-list` to use the appropriate commands, and not pass in extra metadata and options to Tectonic which cause it to error out. This needs to be done in place.
+
+```lisp
+(let ((tex-list (assoc "TeX" TeX-command-list))
+      (latex-list (assoc "LaTeX" TeX-command-list)))
+  (setf (cadr tex-list) "%(tex)"
+        (cadr latex-list) "%l"))
+```
+
+And that is all! You should now be able to 
+1. Compile plain TeX files.
+2. Build Tectonic LaTeX projects in watch mode.
+
+## Additional Configuration and Usage Suggestions
+
+### Compile LaTeX outside a Tectonic project
+
+To do this, you can simply invoke `M-x TeX-command-master`, and the select the `Other` option, passing in the compile command `nextonic compile -f latex <name of file>`.
+> **Caution**: Compiling a document with multiple LaTeX files in this manner isn't extensively tested, as using a Tectonic project is the better way in that case. Any bug reports are welcome.
+
+### Live PDF Preview in Tectonic projects
+
+AucTeX expects the output PDF after compiling to be in the same directory as the input file. So it will error out when that is not the case, since Tectonic places the output in a build directory.
+
+This behavior can be controlled by using the `TeX-output-dir` variable on a per porject basis.
+
+This configuration assumes you are using `project.el`, although porting this code to `projectile.el` should be trivial.
+
+```lisp
+(add-hook 'after-change-major-mode-hook
+          (lambda ()
+            (when-let ((project (project-current))
+                       (proot (project-root project)))
+              (when (file-exists-p (expand-file-name "Tectonic.toml" proot))
+                (setq-local TeX-output-dir (expand-file-name "build/index" proot))))))
+```
+
+We are basically looking for `Tectonic.toml` file in the project root, and if it exists, setting the `TeX-output-dir` to the appropriate path to the build directory. You may replace the `"build/index"` path to wherever your PDF file is placed after it is generated by Tectonic.