Skip to content

Latest commit

 

History

History
294 lines (247 loc) · 12.7 KB

ome-tex.org

File metadata and controls

294 lines (247 loc) · 12.7 KB
Raw

Oh My Emacs TeX

This is part of oh-my-emacs.

Prerequisites

PackageWindowsUbuntu/Debian/MintArchLinuxFedoraMac OS XMandatory?
texlivetexlive-full latex-beamertexlive-most texlive-cjktexlive-allMacTeXYes
pygments[pip][pip][pip][pip]No

Note:

  • texlive, the full texlive distribution is really huge, so install necessary parts as you need.
  • MacTeX is a redistribution of texlive, which includes Mac-specific utilities and front-ends. It is also pre-configured to work out-of-the-box with Mac OS X as it provides sensible defaults for configuration options that, in TeX Live, are left up to the user to allow for its cross-platform compatibility.

El-get packages

PackageStatusDescription
AUCTeXRequiredYou need it, believe me.
CDLaTeXOptionalSpeedy \LaTeX{} typing.

AUCTeX

AUCTeX is the predominant \TeX{}/\LaTeX{} writing environment for Emacs/XEmacs.

Prerequisites and Installation

\TeX{} is a long history legend in computer typesetting. To configure a working \TeX{} environment is far beyond the scope of this project. However, I can give you some hint to install a \TeX{} system on Linux. If you are

  • a Ubuntu/Debian/Mint user, install texlive by sudo apt-get install texlive-full
  • a Arch Linux user, install texlive by sudo pacman -S texlive-most texlive-langcjk
  • a Fedora user, install texlive by sudo yum -S texlive-all
  • a SuSE user, install texlive by sudo zypper in texlive-xetex

For Mac OS X users, MacTeX is the best choice. You can install it directly from its website or via homebrew-cask. By default, MacTeX install all binary executables to /usr/texbin/, which is different from Linux.

If you are not lucky enough, you should follow the official texlive instructions to install it.

There’re other annoying problems if you’re a CJK user, such as fonts and package configuration in \TeX{} documents, but this is further beyond the scope of this project. So refer to necessary TUGs, or BBS for help. For Chinese user, CTEX is a good place to start your journey. LaTeX编辑部 also provides lots of useful resources written in Chinese.

For all \TeX{} users, the Comprehensive TEX Archive Network (CTAN) is your lifelong friend, which act as the central place for all kinds of material around \TeX{}. The famous Stack Exchange Network also provides a http://tex.stackexchange.com/ which focus on \TeX{} related questions.

Enough, enjoy your journey to \TeX{} world! Now it’s time to come back to AUCTeX. Besides a working \TeX{} installation, you also need autoconf and texinfo package for el-get-install auctex, and a recent Ghostscript for preview-latex in both DVI and PDF mode.

Finally, if you’re tired or afraid to setup a working \TeX{} environment, writelatex provides a really instance starting point with no pain, just try it before you fall in love with \TeX{} world.

Keybindings

AUCTeX is really flexible and customizable, it also provides a rich set of menubar entries. Here’s a list of most commonly used keybindings in AUCTeX:

  • Editing
    • C-c C-s LaTeX-section
    • C-c C-e LaTeX-environment
    • C-c C-m TeX-insert-macro
    • C-c ] LaTeX-close-environment
  • Marking and Commenting
    • C-c * LaTeX-mark-section
    • C-c . LaTeX-mark-environment
    • C-c ; TeX-comment-or-uncomment-region
    • C-c % TeX-comment-or-uncomment-paragraph
  • Folding:
    • C-c C-o C-b TeX-fold-buffer
    • C-c C-o b TeX-fold-clearout-buffer
  • Command Controlling
    • C-c C-c TeX-command-master
    • C-c C-r TeX-command-region
    • C-c C-b TeX-command-buffer
    • C-c C-k TeX-kill-job
    • C-c C-l TeX-recenter-output-buffer
    • C-c ^ TeX-home-buffer

Checking

lacheck and chktex is the lint tool for \TeX{}, you can install them in Ubuntu by sudo apt-get install lacheck chktex. AUCTeX has direct support for lacheck and chktex. You can start lacheck with C-c C-c Check <RET> and chktex with C-c C-c ChkTeX <RET>.

Each of the two utilities will find some errors the other doesn’t, but chktex is more configurable, allowing you to create your own errors

Reftex

  • C-c = reftex-toc will show a table of contents of the document.
  • C-c ( reftex-label to insert a label at point.
  • C-c [ reftex-citation to insert a citations from BibTeX database.

Coordinations with other packages

Oh-my-emacs adopts some other awesome packages such as smartparens and evil, which has some conflicts with AUCTeX. so there need some hack, which, is always the main topic with Emacs.

smartparens-latex provide some goodies for \TeX{} editing. But we need to ensure smartparens is available before we require 'smartparens-latex.

smartparens still has some weird problems for inserting “$” in \TeX{}, which is a weird problem. In fact, both AUCTeX and smartparens provides some pair management functions, which may be overlapping. AUCTeX provide a TeX-electric-math, while smartparens was born for pair management. Worse, the following cdlatex.el also provides some pair management functions. Ah, we need some coordination between them. So any ideas or patches will be appreciated.

Another oh-my-emacs package, evil, shadowed some keybindings for AUCTeX’s reftex-toc-mode. However, I only enable evil-mode in text-mode-hook and prog-mode-hook, and reftex-toc-mode is derived from fundamental-mode, I have no idea why evil-local-mode is enabled by default when entering reftex-toc-mode, so I have to turn-off-evil-mode explicitly.

Oh-my-emacs settings

  • Use xetex as the default TeX-engine for better support for \TeX{} font selection and PDF export.
  • Enable outline-minor-mode and flyspell-mode.
  • Enable TeX-interactive-mode, TeX-PDF-mode, TeX-fold-mode and reftex-mode.
  • Favors Okular and Evince as the default viewer in Linux, and fallbacks to xdg-open if both Okular and Evince is unavailable. Since I don’t have a Windows or Mac OS X environment, patches are always welcome.
(defun ome-auctex-setup ()
  (when (require 'smartparens nil 'noerror)
    (require 'smartparens-latex))
  (setq TeX-auto-save t)                ; Automatically save style information
                                        ; when saving the buffer
  (setq TeX-parse-self t)               ; Parse file after loading it if no
                                        ; style hook is found for it.
  (setq LaTeX-syntactic-comment t)
  (setq TeX-auto-untabify t)            ; remove all tabs before saving
  (setq reftex-plug-into-AUCTeX t)
  (setq-default TeX-engine 'xetex)      ; use xelatex by default

  ;; Mac OS X fallback to the "open" program as the default viewer for all
  ;; types of files.
  (cond
   ;; settings for Linux
   ((eq system-type 'gnu/linux)
    (cond
     ((executable-find "okular")
      (setq TeX-view-program-selection
            '((output-pdf "Okular")
              (output-dvi "Okular"))))
     ((executable-find "evince")
      (setq TeX-view-program-selection
            '((output-pdf "Evince")
              (output-dvi "Evince"))))
     (t
      (setq TeX-view-program-selection
            '((output-pdf "xdg-open")
              (output-dvi "xdg-open")))))))

  (add-hook 'TeX-mode-hook
            (lambda ()
              (outline-minor-mode t)
              (flyspell-mode t)
              (TeX-interactive-mode t)
              (TeX-PDF-mode t)
              (TeX-fold-mode t)))

  (add-hook 'LaTeX-mode-hook
            (lambda ()
              (LaTeX-math-mode t)
              (reftex-mode t)))

  (add-hook 'reftex-toc-mode-hook
            (lambda ()
              (when (featurep 'evil)
                (turn-off-evil-mode)))))

(when (executable-find
       (if (eq system-type 'darwin)
           ;; MacTeX install all its executables to /usr/texbin directory
           "/usr/texbin/pdflatex"
         "pdflatex"))
  (ome-install 'auctex))

Tips and Tricks

Here’s some tips and tricks about AUCTeX.

LaTeX shell escape

\LaTeX{} supports an lesser known “shell-escape” feature. In a word, this mode can be used to incorporate dynamic content, or run external process during the compilation phase. Check this post for details.

Unfortunately, there no easy explicit way to customize command line options for various AUCTeX backend. So we need some tricks to get around this. Thanks stackoverflow again, here’s the code snippet for AUCTeX \LaTeX{} backend.

(defvar ome-LaTeX-shell-escape-mode nil
  "Whether or not LaTeX shell escape mode is enabled.")

(defun ome-LaTeX-toggle-shell-escape ()
  (interactive)
  (if ome-LaTeX-shell-escape-mode
      (progn
        (setcdr (assoc "LaTeX" TeX-command-list)
                '("%`%l%(mode)%' %t"
                  TeX-run-TeX nil (latex-mode doctex-mode) :help "Run LaTeX"))
        (setq ome-LaTeX-shell-escape-mode nil)
        (message "LaTeX shell escape mode turned off."))
    (progn
      (setcdr (assoc "LaTeX" TeX-command-list)
              '("%`%l%(mode) -shell-escape%' %t"
                TeX-run-TeX nil (latex-mode doctex-mode) :help "Run LaTeX")))
    (setq ome-LaTeX-shell-escape-mode t)
    (message "LaTeX shell escape mode turned on.")))

;; (define-key org-mode-map (kbd "C-c C-x x") 'ome-LaTeX-toggle-shell-escape)

CDLaTeX

CDLaTeX - more LaTeX functionality for Emacs and XEmacs

CDLaTeX is a minor mode which re-implements many features also found in the AUCTeX LaTeX mode. The reason for this is mainly historical - much of it was written before I knew about AUCTeX. So check this out if you would like to try a different implementation. Here are some of the differences: Environment insertion is template based, and not hook based. Keyword commands (which are executed by typing a short (2-4 letters) keyword into the buffer, followed by TAB) give very rapid access to the main environment templates and mathematical constructs. CDLaTeX knows the difference between text mode and math mode in LaTeX and adapts automatically to that. You can download CDLaTeX here.

– http://staff.science.uva.nl/~dominik/Tools/cdlatex/

The comments in cdlatex.el said that “CDLaTeX requires texmathp.el which is distributed with AUCTeX. Starting with Emacs 21.3, texmathp.el will be part of Emacs.”, however, I didn’t find any texmathp.el with current emacs distribution. So CDLaTeX requires AUCTeX as a dependency, which means it didn’t work with Emacs builtin tex-mode anymore.

(defun ome-cdlatex-mode-setup ()
  (add-hook 'LaTeX-mode-hook 'turn-on-cdlatex)
  (add-hook 'latex-mode-hook 'turn-on-cdlatex))

(when (el-get-package-is-installed 'auctex)
  (ome-install 'cdlatex-mode))

Todo

AUCTeX