Mrthfx

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

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 https://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:

• How can I make AUCTeX spell check in the language specified by babel and csquotes macros?


• How can I make AUCTeX use the spelling dictionary in the same language as babel is loaded with?


• How can I make AUCTeX use the spelling dictionary in the same language as polyglossia is loaded with?

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, 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.

(add-hook 'TeX-mode-hook

          (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

(add-hook 'TeX-mode-hook 'LaTeX-math-mode)



;;; RefTeX

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

(add-hook 'TeX-mode-hook 'turn-on-reftex)



(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 https://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" "{")))

Kieran Healy's "Choosing Your Workflow Applications" is a good place to start. In the article, Healy writes about EMACS, LaTeX, R.

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.