branch: externals/auctex-cont-latexmk
commit b208286d5594f4a854905f21347b0105b3aca475
Author: Paul Nelson <ultr...@gmail.com>
Commit: Paul Nelson <ultr...@gmail.com>
Add some tips to README
---
README.org | 11 +++++++----
1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/README.org b/README.org
index ffa0f6d9b0..49715fdf07 100644
--- a/README.org
+++ b/README.org
@@ -4,7 +4,7 @@
* 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
+* 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 tex-continuous
@@ -15,7 +15,7 @@ Download this repository, install using =M-x
package-install-file= (or package-v
#+end_src
Replace the keybinding with whatever you prefer (or delete it and just run the
command via =M-x=).
-The command =tex-continuous-toggle= behaves the way that I prefer -- it
enables both =tex-continuous-mode= and =flymake-mode=, restricting the backends
for the latter to those coming from the former. Depending upon your
preferences, you may wish to write your own "wrapper" for =tex-continuous-mode=
akin to =tex-continuous-toggle=.
+The command =tex-continuous-toggle= behaves the way that I prefer -- it
enables both =tex-continuous-mode= and =flymake-mode=, restricting the backends
for the latter to those coming from the former. If you want to use continuous
compilation but no flymake, then you might instead wish to bind a key to
=tex-continuous-mode= or simply do =M-x tex-continuous-mode=. If you already
use flymake for something else in tex buffers, then you might wish to write
your own "wrapper" for =tex-contin [...]
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/warni [...]
@@ -31,12 +31,15 @@ The way the Flymake backend works, it will update only when
the latexmk process
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-main.el][my config]].
-Let me remark that 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.
-
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 t
[...]
+* 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.
+
* Customization
- You can tweak the underlying =latexmk= command via =M-x customize-variable
tex-continuous-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.
* 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.
