#+title: auctex-cont-latexmk.el: run latexmk continuously, report errors via flymake
#+author: Paul Nelson

* Overview
This package provides a minor mode where [[https://ctan.org/pkg/latexmk?lang=en][latexmk]] continuously compiles the document in the background and the errors/warnings are reported via [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Flymake.html][Flymake]].

* Configuration and usage
Download this repository, install using =M-x package-install-file= (or package-vc-install, straight, elpaca, ...), and add something like the following to your [[https://www.emacswiki.org/emacs/InitFile][init file]]:
#+begin_src elisp
(use-package auctex-cont-latexmk
  :after latex
  :bind
  (:map LaTeX-mode-map
        ("C-c k" . auctex-cont-latexmk-toggle)))
#+end_src
Replace the keybinding with whatever you prefer (or delete it and just run the command via =M-x=).

The command =auctex-cont-latexmk-toggle= behaves as follows:

In single-file documents, it simply enables continuous compilation and activates Flymake diagnostics in the current buffer.

In multifile documents (documents with a master file and included files), you can use =auctex-cont-latexmk-toggle= independently in each included file you are editing.  The package is designed explicitly to support multiple buffers simultaneously, all sharing a single continuous compilation process for the same master file.  Flymake diagnostics will appear directly in each buffer where they occur, making error tracking easy and intuitive.  Compilation continues to run until you've explicitly disabled =auctex-cont-latexmk-mode= in every participating buffer.

If you prefer continuous compilation without automatic Flymake activation (e.g., if you already manage Flymake separately), you may wish instead to directly call =auctex-cont-latexmk-mode= rather than the toggle command.

The way the Flymake backend works, it will update only when the latexmk process reaches a "watching for changes" state and the buffer is unmodified.  The workflow is thus to save the file, wait a few seconds for the compilation to complete, and then to use Flymake to navigate the errors.  I configure Flymake to use =M-n= and =M-p= for navigation, and also use =(setq flymake-show-diagnostics-at-end-of-line t)= (available in Flymake 1.3.6, part of Emacs 30+), which displays the error/warning messages in the buffer itself rather than just in the minibuffer:

#+begin_src elisp
(use-package flymake
  :custom
  (flymake-show-diagnostics-at-end-of-line t)
  :bind
  (:map flymake-mode-map
        ("M-n" . flymake-goto-next-error)
        ("M-p" . flymake-goto-prev-error)))
#+end_src

I also bind =flymake-show-diagnostics-buffer=, which gives an overview of all errors.  You can find my current setup in [[https://github.com/ultronozm/emacsd/blob/main/init.el][my config]].

That's all.  I prefer this workflow to the alternative in which one compiles the document manually via =TeX-command-master= (=C-c C-c=) and navigates the warning/error messages using =next-error= (=M-n=) and =previous-error= (=M-p=).  It also gives a handy way to keep the .aux files up-to-date; I take advantage of this feature in the packages [[https://github.com/ultronozm/czm-preview.el][czm-preview.el]] and [[https://github.com/ultronozm/czm-tex-fold.el][czm-tex-fold.el]] to annotate the TeX buffer with label numbers.

* Tips
- TeX compilers are not so good at locating errors involving braces.  For this, the Emacs commands =check-parens=, =tex-validate-buffer= and =tex-validate-region= are indispensable.  In particular, you should always try these commands when you encounter errors at the bottom of a file concerning an incomplete argument or environment.
- You can use the command =M-x auctex-cont-latexmk-help-at-point= (or bind it to a key) if you want to see AUCTeX's help message (if any) for the error at point.

* Customization
- You can tweak the underlying =latexmk= command via =M-x customize-variable auctex-cont-latexmk-command=.
- This package respects the AUCTeX variable =TeX-output-dir=: you can use that variable to control where the output files generated via latexmk are placed.
- It also respects AUCTeX's mechanisms for filtering warnings and errors, in particular the variable =TeX-ignore-warnings=, which may be used to exclude certain warnings.

* Troubleshooting
- The compilation takes place in a buffer *pvc-filename*, so look there if you need to see the output.
- AUCTeX's error parsing doesn't work well with filenames (or paths) that contain parentheses, so don't put parentheses in your filenames.
