lang/latex: rewrite README

modules/lang/latex/README.org

@@ -1,79 +1,73 @@
-#+TITLE: :lang latex
+#+TITLE:   lang/latex
+#+DATE:    January 16, 2017
+#+SINCE:   v1.3
+#+STARTUP: inlineimages
 
-* Module Description
+* Table of Contents :TOC_3:noexport:
+- [[Description][Description]]
+  - [[Module Flags][Module Flags]]
+  - [[Plugins][Plugins]]
+- [[Features][Features]]
+- [[Customization][Customization]]
+  - [[Specifying the location of a bibtex file & corresponding PDFs][Specifying the location of a bibtex file & corresponding PDFs]]
+  - [[Changing the PDFs viewer][Changing the PDFs viewer]]
+
+* Description
 Provide a helping hand when working with LaTeX documents.
 
-** Feature:
 + Sane defaults
 + Fontification of many popular commands
 + Pretty indentation of wrapped lines using the ~adaptive-wrap~ package
-+ Spell checking with ~flyschek~
++ Spell checking with ~flycheck~
 + Change PDF viewer to Okular or ~latex-preview-pane~
 + Bibtex editor
 + Autocompletion using ~company-mode~
 + Ivy or Helm for selecting bibliography
 + Compile your .tex code only once using LatexMk
 
+** Module Flags
++ ~+latexmk~ Use LatexMk instead of LaTeX to compile documents.
+
+** Plugins
++ [[http://www.gnu.org/software/auctex/][auctex]]
++ [[http://elpa.gnu.org/packages/adaptive-wrap.html][adaptive-wrap]]
++ [[https://github.com/jsinglet/latex-preview-pane][latex-preview-pane]]
++ [[https://github.com/tom-tan/auctex-latexmk][auctex-latexmk]]*
++ [[https://github.com/alexeyr/company-auctex][company-auctex]]*
++ [[https://github.com/TheBB/company-reftex][company-reftex]]*
++ [[https://github.com/vspinu/company-math][company-math]]*
++ [[https://github.com/tmalsburg/helm-bibtex][ivy-bibtex]]* or [[https://github.com/tmalsburg/helm-bibtex][helm-bibtex]]*
+
+* TODO Features
 
 * Customization
+** Specifying the location of a bibtex file & corresponding PDFs
+The reftex and bibtex-completion packages have two variables that allow you to
+specify where it should find your bibliography file(s) and their corresponding
+PDFs:
 
-** Custom Variables
+#+BEGIN_SRC emacs-lisp
-Two custom variables state where AUCTeX will search for bibliography files and their corresponding PDFs.
+(setq reftex-default-bibliography "/your/bib/file.bib")
-Set these variables in your private configuration with:
+;; Optionally specifying a location for the corresponding PDFs
-#+BEGIN_SRC emacs_lisp
+(setq bibtex-completion-library-path (list "/your/bib/pdfs"))
-(set! :latex-bibtex-file "./your/bib/file.bib")
-(set! :latex-bibtex-pdfs-dir "./dir/with/bib/pdfs/")
-#+END_SRC
-If the variables are not set, they are ignored.
-
-** Choose View Program
-You have four options to choose from for the viewer of your PDF rendered files.
-*** Okular
-Use Okular as default PDF viewer.
-
-Activate with the flag '+okular' of the latex module in your private init.el.
-#+BEGIN_SRC emacs_lisp
-(latex +okular)
 #+END_SRC
 
-*** Skim
+** Changing the PDFs viewer
-For Mac users. Use Skim to preview your PDFs.
+This module provides integration for four supported pdf viewers. They are
 
-Activate with the flag '+skim' of the latex module in your private init.el.
++ [[https://skim-app.sourceforge.io/][Skim.app]] (MacOS only)
-#+BEGIN_SRC emacs_lisp
++ Okular
-(latex +skim)
++ Zathura
++ pdf-tools (requires =:tools pdf= module)
+
+They are searched for in this order. See ~+latex-viewers~ to change the order,
+or remove tools from the search altogether. If you want to exclusively use one
+tool, for instance:
+
+#+BEGIN_SRC emacs-lisp
+(setq +latex-viewers '(zathura))
 #+END_SRC
 
-*** PDF Tools
+If none of these tools are found, ~latex-preview-pane~ (uses ~DocView~ in Emacs)
-Use the PDF Tools package to preview your PDFs. Requires the tools module ~pdf~ enabled in your configuration.
+is used as a fallback. You can use this exclusively by setting ~+latex-viewers~
-#+BEGIN_SRC emacs_lisp
+to ~nil~.
-(:tools pdf)
-#+END_SRC
-
-Activate with the flag '+pdf-tools' of the latex module in your private init.el.
-#+BEGIN_SRC emacs_lisp
-(latex +pdf-tools=)
-#+END_SRC
-
-*** Preview Pane
-You may wish to use the old school package ~latex-preview-pane~ instead of the
-other alternatives. ~latex-preview-pane~ uses a ~DocView~ instead.
-
-Activate with the flag '+preview-pane' of the latex module in your private init.el.
-#+BEGIN_SRC emacs_lisp
-(latex +preview-pane)
-#+END_SRC
-
-** LatexMk
-Use LatexMk instead of normal LaTeX to compile documents. LatexMk only needs to
-run once to get all references, bibliography and other things right.
-
-Activate with the flag '+latexmk' of the latex module in init.el.
-#+BEGIN_SRC emacs_lisp
-(latex +latexmk)
-#+END_SRC
-
-You can enable both a custom view program and LatexMk with a call such as:
-#+BEGIN_SRC emacs_lisp
-(latex +latexmk +okular)
-#+END_SRC