# A simpleton's guide to (…)TeX workflow with emacs

### Progress Report

Four months on, I thought it a good idea to "report back" here, and I wrote something. Then, I had better thoughts and turned it into a blog post.

You can read it on the TeX.sx blog.

Prompted by a recent conversation in the chat room, I am thinking of revisiting emacs as my source editor. In order to give it a good chance (I have failed with four or five previous attempts over the past ten years or so), I'd like to ask for useful tips, or pointers to larger works, to make this transition from TeXWorks as smooth as possible.

Key features of my modus operandi are:

• heavy use of memoir, beamer, and tikz
• structured documents with \input and standalone
• lualatex (with occasional ventures needed into xelatex or pdflatex), driven by latexmk
• biblatex (using bibtex rather than biber, but only through inertia)
• unicode, with no exceptions
• Windows 7
• Ouside TeXWorks, general-purpose PDF viewer: PDF XChange

Among the questions and uncertainties I should like to see addressed (some of which, I accept, may not be directly on-topic -- links may be more suitable in these cases) are these:

• Initial setup of emacs, including (...)TeX-workflow-specific add-ons
• Compilation and preview direct from the emacs environment
• Synchronisation of source and preview
• Auto-completion
• Spelling (EN-GB, PT-BR, ES, and FR)
• Any other hints, bear-traps, and so forth
• A good tutorial
-
This question might be too broad to get good answers… – Seamus Apr 5 '12 at 9:49
@Seamus: Yes, I can see that. It just struck me that there may be more people than just me thinking "I'd like to use emacs, but I'm frightened", and that this might be the way to help them. – Brent.Longborough Apr 5 '12 at 9:53
Of course, working through the Emacs tutorial is always a good idea. Apart from that: not something essential at all, but maybe of some use: tex.stackexchange.com/a/50309/5626 . And customize-group AUCTeX is your friend. – mbork Apr 5 '12 at 11:27
Not to start a flamewar or anything, but if you have "failed" using emacs for five times already, wouldn't it be smarter to move on to another editor, say vim? – romeovs Apr 5 '12 at 11:33
@romeovs I guess it's because there are so many obviously intelligent people who, apparently, would die for it. And, of course, I love a challenge like that "as a moth to a flame". – Brent.Longborough Apr 5 '12 at 14:16

I have never used Emacs in Windows but I started to learn and use Emacs only eight or nine months ago and I now use it for most of my work.

## Learning

First you need to get comfortable with the basics of Emacs and probably this is what will be your main frustration. For a new user the commands for basic usage can be a pain to learn because they are unlike other editors. Let the learning process take time and you will eventually be very efficient. Know that once you get past the culture shock and learn the basics you will enjoy Emacs.

A good way to start learning the basics of Emacs is by its built-in tutorial which you can access via C-h t. Take your time and follow the tutorial from beginning to end. Make sure you learn how to navigate in buffers, edit buffers, open new buffers and switch between buffers. You do not need to learn it all at once. You can always go back to the tutorial.

Once you can handle the basics you should try to do some of your work in Emacs. Use your old editor in parallel to begin with. The first month or two you mighta switch back and forth before you spend most time in Emacs. The important thing is that you take time to get used to Emacs and try to learn new things every now and then. Even long-time users learn new things once in a while. It is a never-ending learning process.

You may have habits and ways of doing things that conflict with the way of Emacs. Sometimes it is best to adapt Emacs to how you are used to work and sometimes Emacs has a better way and then you are better off adapting. As an example, when I started to use Emacs I thought its way of opening files and switching between buffers was complicated and awkward so I tended to use menus and the toolbar for these tasks. But as I understood and got used to the commands for handling buffers, such as C-x b for switching between buffers, I was impressed by its efficiency. Something you might want to learn for further efficiency of switching between files is the bookmarks feature.

For learning more about Emacs its internal help is good. You can see the help options by doing C-h ?. As usual the web is great for help. A particular site is EmacsWiki. On the Stack Exchange network this site is good for TeX related Emacs issues but sometimes you are better off asking at Stack Overflow where more Emacs gurus are hanging out. For general and non-programming question about Emacs you can try Super User. Finally, the chat might be a good place for venting your Emacs related frustration (or euphoria).

## Modes and tools

What you want to use for LaTeX is the Emacs mode AUCTeX for which http://emacswiki.org/emacs/AUCTeX is a good resource, see also Useful shortcuts or key bindings or predefined commands for emacs+AUCTeX. The best way to get started with and learn AUCTeX is probably to read the quick start. I have included some configuration that is good to start with when using AUCTeX in the setup below. AUCTeX can handle \input and standalone.

I have never used memoir so I do not know if there is some particular Emacs gadget to help with it. Generally YASnippet is a great way to make it easier to insert structures you often insert and for making templates, so it should be helpful for memoir too. The same goes for beamer. Another way to create beamer slides is via another Emacs mode called Org-mode which is a mode for keeping notes, maintaining TODO lists, doing project planning, and authoring. What you do is to write an org file and export it to beamer. Finally, for TikZ checkout AucTeX extension for TikZ.

You can setup Emacs to work with latexmk (my preferred way is http://stackoverflow.com/a/8026921/789593). Then, since you use latexmk you can set up biblatex with bibtex and compilation with lualatex, xelatex and pdflatex via latexmk's own configuration.

For inserting biblatex citation macros and cross-references you use RefTeX which comes with AUCTeX. Check out Setting up RefTeX with biblatex citation commands for configuration. In the configuration below I already included such lines.

Emacs has full support for unicode and it has auto-completion for most commands. AUCTeX also provides auto-completion for TeX commands.

Emacs has good tools for spelling. I use Flyspell when I need to check spelling but I keep it off while writing to avoid distraction. With AUCTeX it knows the difference between code and text. To use Flyspell do M-x flyspell-buffer to spell check the whole buffer or M-x flyspell-region to spell check the marked region. If you want to integrate spell checking with LaTeX language packages the following questions might be interesting for you:

## Workflow

I have already written about workflow in Everyday LaTeX and workflow? It includes a general description of a workflow for LaTeX but without a particular editor in mind and a short description on how to implement it via Org-mode and AUCTeX. I think outlining and drafting is best done in Org-mode. AUCTeX is best later in the process. Since your question is about Emacs and LaTeX in particular I will not say more about Org-mode but focus on AUCTeX.

What is the best workflow may vary between tasks and persons. The following is just some general notes on how you can work with LaTeX files in Emacs. When you edit LaTeX files in Emacs you will probably spend most time using AUCTeX but since you use use biblatex you will also edit .bib files. Roughly, work with LaTeX files can be classified as either writing or compiling.

When it comes to writing you should use the all the basic commands in Emacs to navigate in text and to edit text. These you learn by practice. AUCTeX provides some LaTeX specific commands which you should learn, make sure to checkout the commands for creating macros, C-c Enter, and environments, C-c C-e, LaTeX-math-mode and the RefTeX commands for inserting citations and cross-references, see the AUCTeX resources above for details. To speed up and make creation of LaTeX files easier you can use templates via YASnippet as described in Working with templates. Also, there is a special mode for .bib files which can ease editing such files.

When it comes to compiling you can use latexmk as described above but you can also use AUCTeX built-in compiling method which is quite good (C-c C-c). To view the output of the current buffer simply do C-c C-v. If the compilation fails AUCTeX can take you to the line where the error occurred.

Another aspect of workflow is to track changes. This can be done via revision control, see What are the advantages of using version control (git, CVS etc) in LaTeX documents and What are good working practices for VCS with LaTeX documents? for details. Emacs has built-in support for many revision control systems. If you use git magit is superior to the built-in git support.

## Setup

Your Emacs configuration is based in your .emacs file which is a text file consisting of Lisp code. You do not have to know Lisp to configure Emacs (although you will benefit from knowing some). Often you proceed by finding snippets on the net which you paste into your .emacs.

Configuring Emacs is a never-ending process. There is nothing wrong with this. You adapt it to your needs as you go. However, it is good to have something to start with. Below you find an .emacs to start with. I took my .emacs and removed most things except some minor display configuration, some general AUCTeX and RefTeX configuration and some configuration for proper syntax highlighting of macros from popular packages such as enumitem, biblatex and csquotes macros. I have commented it heavily so that it is easier to understand what it does. If there is some configuration you do not like you can just remove the relevant lines or comment them to deactivate them. Make sure to keep backups of your .emacs so that you do not lose your configuration.

;;; Brent.Longborough's .emacs

(global-visual-line-mode 1); Proper line wrapping
(global-hl-line-mode 1); Highlight current row
(show-paren-mode 1); Matches parentheses and such in every mode
(set-fringe-mode '(0 . 0)); Disable fringe because I use visual-line-mode
(set-face-background hl-line-face "#f2f1f0"); Same color as greyness in gtk
(setq inhibit-splash-screen t); Disable splash screen
(setq visible-bell t); Flashes on error
(setq calendar-week-start-day 1); Calender should start on Monday
(add-to-list 'default-frame-alist '(height . 59)); Default frame height.

;;; AUCTeX
;; Customary Customization, p. 1 and 16 in the manual, and http://www.emacswiki.org/emacs/AUCTeX#toc2
(setq TeX-parse-self t); Enable parse on load.
(setq TeX-auto-save t); Enable parse on save.
(setq-default TeX-master nil)

(setq TeX-PDF-mode t); PDF mode (rather than DVI-mode)

(add-hook 'TeX-mode-hook 'flyspell-mode); Enable Flyspell mode for TeX modes such as AUCTeX. Highlights all misspelled words.
(add-hook 'emacs-lisp-mode-hook 'flyspell-prog-mode); Enable Flyspell program mode for emacs lisp mode, which highlights all misspelled words in comments and strings.
(setq ispell-dictionary "english"); Default dictionary. To change do M-x ispell-change-dictionary RET.
(lambda () (TeX-fold-mode 1))); Automatically activate TeX-fold-mode.
(setq LaTeX-babel-hyphen nil); Disable language-specific hyphen insertion.

;; " expands into csquotes macros (for this to work babel must be loaded after csquotes).
(setq LaTeX-csquotes-close-quote "}"
LaTeX-csquotes-open-quote "\\enquote{")

;; LaTeX-math-mode http://www.gnu.org/s/auctex/manual/auctex/Mathematics.html

;;; RefTeX
;; Turn on RefTeX for AUCTeX http://www.gnu.org/s/auctex/manual/reftex/reftex_5.html

(eval-after-load 'reftex-vars; Is this construct really needed?
'(progn
(setq reftex-cite-prompt-optional-args t); Prompt for empty optional arguments in cite macros.
;; Make RefTeX interact with AUCTeX, http://www.gnu.org/s/auctex/manual/reftex/AUCTeX_002dRefTeX-Interface.html
(setq reftex-plug-into-AUCTeX t)
;; So that RefTeX also recognizes \addbibresource. Note that you
;; can't use $HOME in path for \addbibresource but that "~" ;; works. (setq reftex-bibliography-commands '("bibliography" "nobibliography" "addbibresource")) ; (setq reftex-default-bibliography '("UNCOMMENT LINE AND INSERT PATH TO YOUR BIBLIOGRAPHY HERE")); So that RefTeX in Org-mode knows bibliography (setcdr (assoc 'caption reftex-default-context-regexps) "\\\\\$$rot\\|sub\$$?caption\\*?[[{]"); Recognize \subcaptions, e.g. reftex-citation (setq reftex-cite-format; Get ReTeX with biblatex, see http://tex.stackexchange.com/questions/31966/setting-up-reftex-with-biblatex-citation-commands/31992#31992 '((?t . "\\textcite[]{%l}") (?a . "\\autocite[]{%l}") (?c . "\\cite[]{%l}") (?s . "\\smartcite[]{%l}") (?f . "\\footcite[]{%l}") (?n . "\\nocite{%l}") (?b . "\\blockcquote[]{%l}{}"))))) ;; Fontification (remove unnecessary entries as you notice them) http://lists.gnu.org/archive/html/emacs-orgmode/2009-05/msg00236.html http://www.gnu.org/software/auctex/manual/auctex/Fontification-of-macros.html (setq font-latex-match-reference-keywords '( ;; biblatex ("printbibliography" "[{") ("addbibresource" "[{") ;; Standard commands ;; ("cite" "[{") ("Cite" "[{") ("parencite" "[{") ("Parencite" "[{") ("footcite" "[{") ("footcitetext" "[{") ;; ;; Style-specific commands ("textcite" "[{") ("Textcite" "[{") ("smartcite" "[{") ("Smartcite" "[{") ("cite*" "[{") ("parencite*" "[{") ("supercite" "[{") ; Qualified citation lists ("cites" "[{") ("Cites" "[{") ("parencites" "[{") ("Parencites" "[{") ("footcites" "[{") ("footcitetexts" "[{") ("smartcites" "[{") ("Smartcites" "[{") ("textcites" "[{") ("Textcites" "[{") ("supercites" "[{") ;; Style-independent commands ("autocite" "[{") ("Autocite" "[{") ("autocite*" "[{") ("Autocite*" "[{") ("autocites" "[{") ("Autocites" "[{") ;; Text commands ("citeauthor" "[{") ("Citeauthor" "[{") ("citetitle" "[{") ("citetitle*" "[{") ("citeyear" "[{") ("citedate" "[{") ("citeurl" "[{") ;; Special commands ("fullcite" "[{"))) (setq font-latex-match-textual-keywords '( ;; biblatex brackets ("parentext" "{") ("brackettext" "{") ("hybridblockquote" "[{") ;; Auxiliary Commands ("textelp" "{") ("textelp*" "{") ("textins" "{") ("textins*" "{") ;; supcaption ("subcaption" "[{"))) (setq font-latex-match-variable-keywords '( ;; amsmath ("numberwithin" "{") ;; enumitem ("setlist" "[{") ("setlist*" "[{") ("newlist" "{") ("renewlist" "{") ("setlistdepth" "{") ("restartlist" "{")))  - What a fantastic, and encouraging, answer! I'm so sorry I can only give you one upvote and an accept. – Brent.Longborough Apr 6 '12 at 9:48 Depending on what kind of writing you are doing, it will also be a rather good idea to learn to write your own Emacs macros. After using Emacs for about 15 years, I've just recently started writing my own macros (been scarred of Lisp). I was spurred on by an Emacs symposium in Copenhagen back in December, the main conclusion of the symposium was that, yes it does take some time to write your own macros, but it is worth doing in order to save time. Since most of my LaTeX work is editing other peoples code, these macros help A LOT. – daleif Apr 9 '12 at 19:36 @Brent.Longborough You can retroactively add a bounty. :-) – lockstep Apr 12 '12 at 19:49 @Cam: Most of what I do only search at most 5 lines forward. I have one that look forward for |...| (all variations) it will then ask me for a scaling and replace it by, say, \abs[\Big]{...} (made via mathtools). It soon become very time saving not to have to fix these by hand. I also have some first steps for a general macro for finding matching () or [] plus their scalers, including an interface for changing these. Most of my replacement macros also make sure to place the cursor at a suitable place after the subsitution. – daleif Apr 13 '12 at 8:14 @cam: another simple example is that the book I'm editing currently, have a lot of \text{ for }math..., I'd like this to be <newline>\qquad\text{for }math, so I have a macro for that, which I fire when I get near such a construction. I then edit it manually afterwards such I end up with <line on its own>\qquad\text{for$math$}, thus making the text much more consistent. The book I'm converting was written more than 20 years ago, and converted into LaTeX via certain scripts. But there will still be a lot of things to be done by hand. – daleif Apr 13 '12 at 8:24 Kieran Healy's "Choosing Your Workflow Applications" is a good place to start. In the article, Healy writes about EMACS, LaTeX, R. - Appreciate your answer. Please don't be discouraged by my accepting the other one :) – Brent.Longborough Apr 6 '12 at 12:39 For compilation and preview, I have not had a lot of success using the built-in preview functionality on a Windows machine. Instead of working completely in Emacs, I use Sumatra PDF viewer with TeX-source-correlate-mode. This allows me to generate the PDF with reference links and then forward search from Emacs to the PDF and inverse search from the PDF back to my source file in Emacs. Sumatra will also update the PDF in the viewer on successive compilations, so you do not have to shut down the PDF viewer like you might need to with Acrobat. The relevant portions of my .emacs file are: (add-hook 'LaTeX-mode-hook 'TeX-source-correlate-mode) (server-start) (require 'sumatra-forward)  The first line turns on the correlate mode for the forward and inverse links. The second line is so that when I inverse search from the PDF, Emacs will jump to the line in the current code buffer rather than trying to open a new instance of Emacs every time you inverse search. The last line loads a package to handle the sumatra specific lisp for the forward search. Additional info on setting Sumatra up with Emacs, along with sumatra-forward.el, can be found here. Most of my other tips and tricks have been covered by N.N.'s excellent answer. I would just reiterate that YASnippet is wonderful for template text and is very configurable. I use it all the time for things like \frac{}{}, so that when I expand the snippet I can tab from the numerator to the denominator and then tab to exit the fraction. Another package I've found useful is highlight parenthesis mode, which colors the {[()]} that surround the cursor. It has helped me numerous times with editing long equations. I would also add that Org-mode is a wonderful tool and has a lot of features outside of LaTeX integration. It is the reason I started, and continue, to use Emacs. So if you are looking for some additional motivation to revisit Emacs, I would suggest looking at what Org-mode can do. - Is nschum.de/src/emacs/highlight-parentheses the highlight parenthesis mode you refer to? – N.N. Apr 12 '12 at 19:28 Yes, that is the one. I installed it from ELPA so I did not even think to look for a webpage link. – Brian Maicke Apr 12 '12 at 19:31 You might to be help in another question, see tex.stackexchange.com/questions/51945/… – N.N. Apr 15 '12 at 9:15 +1 for org-mode. That is the river delta at which I also started my journey around the Emacs mountain. I am determined to get LaTeX going here too. – Brady Trainor Jan 19 '14 at 20:36 Also, you can set the Emacs' file explorer (dired, C-x d), to omit files with extensions that you don't want to browse. I believe this requires the dired-x package. Then, (require 'dired-x) (setq dired-omit-files (concat "^\\.?#" "\\|" "^\\.$"
"\\|" "\\.dvi$" "\\|" "\\.log$"
"\\|" "\\.gz"
"\\|" "\\.out\$"
))


will show only the .tex and .pdf files in dired. If you want to un-omit, use C-x M-o (not sure why in my Windows install it is simply M-o).

I write the regexp string a little funny, so that I can read the regexp easier. The repeated string "\\|" is the regexp "OR".

Here's the more off-topic part, and for contrast. In my .gitignore_global, I have the following for ignoring the uninteresting files:

# LaTeX
*.dvi
*.log
*.gz*
*.out
*.aux
*.bbl
*.blg
*.toc


For now, I am experimenting with doing local .gitignores of PDFs in certain repos, and even adding some manually via git add -f blah.pdf if I'd like to be able to view the PDF in my remote.

-