*latex-box.txt* LaTeX Box
*latex-box*

This plugin consists of a set of tools to help editing LaTeX documents.

Manifesto: LaTeX Box aims to remain lightweight and stay out of the way.

This plugin provides:
- Background compilation using latexmk;
- Completion for commands, environments, labels, bibtex entries and inline
  maths;
- A simple table of contents;
- Smart indentation (activated with "set smartindent");
- Highlighting of matching \begin/\end pairs
- Motion between matching \begin/\end pairs with the % key;
- Motion through brackets/braces (with user-defined keys).
- Environment objects (e.g., select environement with "vie" or "vae")
- Inline math objects (e.g., select inline math with "vi$" or "va$")

==============================================================================

|latex-box-completion|                  COMPLETION
|latex-box-completion-commands|         Commands
|latex-box-completion-environments|     Environments
|latex-box-completion-labels|           Labels
|latex-box-completion-bibtex|           Bibtex
|latex-box-completion-inlineMaths|      InlineMaths

|latex-box-commands|                    COMMANDS
|latex-box-commands-compilation|        Compilation
|latex-box-commands-viewing|            Viewing
|latex-box-commands-motion|             Motion

|latex-box-motion|                      MOTION

|latex-box-mappings|                    MAPPINGS
|latex-box-mappings-compilation|        Compilation
|latex-box-mappings-insertion|          Insertion
|latex-box-mappings-viewing|            Viewing
|latex-box-mappings-motion|             Motion

|latex-box-settings|                    SETTINGS
|latex-box-settings-compilation|        Compilation
|latex-box-settings-completion|         Completion
|latex-box-settings-windows|            Vim Windows

|latex-box-folding|                     FOLDING

|latex-box-indent|                      INDENTATION

|latex-box-FAQ|                         Frequently Asked Questions

|latex-box-todo|                        TODO

==============================================================================

COMPLETION                                              *latex-box-completion*

Completion is achieved through omni completion |compl-omni|, with default
bindings <CTRL-X><CTRL-O>. There are five types of completion:

------------------------------------------------------------------------------

                                               *latex-box-completion-commands*
Commands ~

Command completion is triggered by the '\' character. For example, >
        \beg<CTRL-X><CTRL-O>
completes to >
        \begin{
<

Associated settings:
        |g:LatexBox_completion_commands|
        |g:LatexBox_completion_close_braces|

------------------------------------------------------------------------------

                                           *latex-box-completion-environments*
Environments ~

Environment completion is triggered by '\begin{'. For example, >
        \begin{it<CTRL-X><CTRL-O>
completes to >
        \begin{itemize}
<

Completion of '\end{' automatically closes the last open environment.

Associated settings:
        |g:LatexBox_completion_environments|
        |g:LatexBox_completion_close_braces|

------------------------------------------------------------------------------

                                                 *latex-box-completion-labels*
Labels ~

Label completion is triggered by '\ref{' or '\eqref{'. For example, >
        \ref{sec:<CTRL-X><CTRL-O>
offers a list of all matching labels, with their associated value and page
number. Labels are read from the aux file, so label completion works only
after compilation.

It matches:
        1. labels: >
                \ref{sec:<CTRL-X><CTRL-O>
<       2. numbers: >
                \eqref{2<CTRL-X><CTRL-O>
<       3. labels and numbers together (separated by whitespace): >
                \eqref{eq 2<CTRL-X><CTRL-O>
<

Associated settings:
        |g:LatexBox_ref_pattern|
        |g:LatexBox_completion_close_braces|

------------------------------------------------------------------------------

                                                 *latex-box-completion-bibtex*
BibTeX entries ~

BibTeX completion is triggered by '\cite{', '\citep{' or '\citet{'. For
example, assume you have in your .bib files an entry looking like: >

        @book { knuth1981,
                author = "Donald E. Knuth",
                title = "Seminumerical Algorithms",
                publisher = "Addison-Wesley",
                year = "1981" }

Then, try: >

        \cite{Knuth 1981<CTRL-X><CTRL-O>
        \cite{algo<CTRL-X><CTRL-O>

You can also use regular expressions (or vim patterns) after '\cite{'.

Associated settings:
        |g:LatexBox_cite_pattern|
        |g:LatexBox_bibtex_wild_spaces|
        |g:LatexBox_completion_close_braces|

------------------------------------------------------------------------------

                                            *latex-box-completion-inlineMaths*
InlineMaths ~

InlineMaths completion is triggered by '$', '\(' or '\[', and can also be
triggered by '$' that locates in math environment '\(...\)', '\[...\]', or
'\begin{eq-env} ... \end{eq-env}'. It suggests the inline maths you write in
'$' pairs and in '\( ... \)' and the corresponding line number.

Note that an inline math with open and close symbols on different lines will
not be suggested.

For example, you type two in line maths looking like: >

        $hello$, \(world\)

And you save them before trying to complete elsewhere: >

        :w

You type '$', '\(' or '\[', and part of 'hello': >

        $h <CTRL-X><CTRL-O>
        \(h <CTRL-X><CTRL-O>
        \[h <CTRL-X><CTRL-O>

They comlete to: >

        $hello$
        \(hello\)
        \[hello\]

You can still add more in line maths in '\(...\)' and '\[...\]': >

        \(hello, $ w <CTRL-X><CTRL-O> \)
        \[hello, $ w <CTRL-X><CTRL-O> \]

The results: >

        \(hello, world\)
        \[hello, world\]

Or cross lines: >

        \( hello,
        $ w <CTRL-X><CTRL-O>

        \[ hello,
        $ w <CTRL-X><CTRL-O>

The results: >

        \(hello,
        world

        \[hello,
        world

For equation environments, it's always triggered by '$': >

        \begin{eq-env}
                $h <CTRL-X><CTRL-O>
                $w <CTRL-X><CTRL-O>
        \end{eq-env}

It matches: >

        \begin{eq-env}
                hello
                world
        \end{eq-env}


ATTENTION: do not try to complete inline maths when
1. '$' pair is in multi lines: >

        $
        h <CTRL-X><CTRL-O>

2. '\begin{eq-env}' and '\end{eq-env}' are in single line: >

        \begin{eq-env}   $ h <CTRL-X><CTRL-O>     \end{eq-env}

Associated setting: >
        g:LatexBox_complete_inlineMath
        g:LatexBox_eq_env_patterns

==============================================================================

COMMANDS                                                  *latex-box-commands*

------------------------------------------------------------------------------

                                              *latex-box-commands-compilation*
Compilation ~

*:Latexmk*
        Compile with latexmk.
        See |g:LatexBox_latexmk_async|, |g:LatexBox_latexmk_options|, and
        |g:LatexBox_latexmk_preview_continuously|.
*:Latexmk!*
        Force compilation with latexmk (runs latexmk with "-g" option).
*:LatexmkClean*
        Clean temporary output from LaTeX.
*:LatexmkClean!*
        Clean all output from LaTeX.
*:LatexmkStatus*
        Show the running status of latexmk for the current buffer.
*:LatexmkStatus!*
        Show the running status of latexmk for all buffers with process group
        ID's or PID's.
*:LatexmkStop*
        Stop latexmk if it is running.
*:LatexErrors*
        Load the log file for the current document and jump to the first error.

Note: The commands |:LatexmkStop| and |:LatexmkStatus| are only relevant when
|g:LatexBox_latexmk_async| or |g:LatexBox_latexmk_preview_continuously| is
set.

When latexmk terminates, it reports its success or failure (with status
number). To navigate through the errors, you can use the |:cc|, |:cn| and
|:cp| commands, as well as the |:clist| command to list the errors.

------------------------------------------------------------------------------

                                                  *latex-box-commands-viewing*
Viewing ~

*:LatexView*
        Launch viewer on output file.
        See |g:LatexBox_output_type| and |g:LatexBox_viewer|.

------------------------------------------------------------------------------

                                                   *latex-box-commands-motion*
Motion ~

*:LatexTOC*
        Open a table of contents.
        Use Enter to navigate to selected entry.
        See |g:LatexBox_split_width|.
        See |g:LatexBox_split_side|.
        See |g:LatexBox_split_resize|.
*:LatexTOCToggle*
        Toggle the display of the table of contents.

Associated setting:
        |g:LatexBox_plaintext_toc| (set this if UTF8 conversion does not work)

==============================================================================

MOTION                                                      *latex-box-motion*

The function LatexBox_JumpToNextBraces({backward}) allows to jump outside of
the current brace/bracket pair, or inside of the next opening braces/brackets.

==============================================================================

MAPPINGS                                                  *latex-box-mappings*

------------------------------------------------------------------------------

                                              *latex-box-mappings-compilation*
Compilation ~

<LocalLeader>ll                                                     |:Latexmk|
        Compile with latexmk.
<LocalLeader>lL                                                    |:Latexmk!|
        Force compilation with latexmk.
<LocalLeader>lc                                                |:LatexmkClean|
        Clean temporary output from LaTeX.
<LocalLeader>lC                                               |:LatexmkClean!|
        Clean all output from LaTeX.
<LocalLeader>lk                                                 |:LatexmkStop|
        Stop latexmk if it is running.
<LocalLeader>lg                                               |:LatexmkStatus|
        Show the running status of latexmk for the current buffer.
<LocalLeader>lG                                              |:LatexmkStatus!|
        Show the running status of latexmk for all buffers with process group
        ID's.
<LocalLeader>le                                                 |:LatexErrors|
        Load the log file for the current document and jump to the first error.

------------------------------------------------------------------------------

                                                  *latex-box-mappings-viewing*
Viewing ~

<LocalLeader>lv                                                   |:LatexView|
        View output file.

------------------------------------------------------------------------------

                                                *latex-box-mappings-insertion*
Insertion ~

*<Plug>LatexCloseCurEnv*
        Close the last matching open environment. Use with imap, e.g.: >
        imap ]] <Plug>LatexCloseCurEnv
<

*<Plug>LatexChangeEnv*
        Change the current environment. Use with nmap, e.g.: >
        nmap <F5> <Plug>LatexChangeEnv
<

*<Plug>LatexToggleStarEnv*
        Toggle star environments (add or remove star). Use with nmap, e.g.: >
        nmap <F5> <Plug>LatexToggleStarEnv
<

*<Plug>LatexWrapSelection*
        Wrap the current selection in a LaTeX command. Use with vmap, e.g.: >
        vmap <F7> <Plug>LatexWrapSelection
<

*<Plug>LatexEnvWrapSelection*
        Wrap the current selection in an environment. Use with vmap, e.g.: >
        vmap <S-F7> <Plug>LatexEnvWrapSelection
<

Suggested mappings to put in ~/.vim/ftplugin/tex.vim: >
        imap <buffer> [[     \begin{
        imap <buffer> ]]     <Plug>LatexCloseCurEnv
        nmap <buffer> <F5>   <Plug>LatexChangeEnv
        vmap <buffer> <F7>   <Plug>LatexWrapSelection
        vmap <buffer> <S-F7> <Plug>LatexEnvWrapSelection
        imap <buffer> ((     \eqref{
<

------------------------------------------------------------------------------

                                                   *latex-box-mappings-motion*
Motion ~

<LocalLeader>lt                                                    |:LatexTOC|
        Open a table of contents.
        Use Enter to navigate to selected entry.

*<Plug>LatexBox_JumpToMatch*
        Jump to the matching bracket or \begin/\end pairs. Emulates |%|.

*<Plug>LatexBox_BackJumpToMatch*
        Same as |<Plug>LatexBox_JumpToMatch|, but the initial search is
        backward.

Suggested bindings: >
        map  <silent> <buffer> ¶ :call LatexBox_JumpToNextBraces(0)<CR>
        map  <silent> <buffer> § :call LatexBox_JumpToNextBraces(1)<CR>
        imap <silent> <buffer> ¶ <C-R>=LatexBox_JumpToNextBraces(0)<CR>
        imap <silent> <buffer> § <C-R>=LatexBox_JumpToNextBraces(1)<CR>
<

==============================================================================

SETTINGS                                                  *latex-box-settings*

------------------------------------------------------------------------------

Mappings ~

*g:LatexBox_no_mappings*
        If this variable is defined, the default keyboard mappings will not be
        loaded.

*g:LatexBox_open_pats*
*g:LatexBox_close_pats*
        These variables define the patterns that LatexBox use to detect
        matching pair of braces, parantheses, environments, and similar.

        Default: >
                let g:LatexBox_open_pats  = [
                        \ '\\{','{','\\(','(','\\\[','\[',
                        \ '\\begin\s*{.\{-}}',
                        \ '\\left\s*\%([^\\]\|\\.\|\\\a*\)',
                        \ ]
                let g:LatexBox_close_pats = [
                        \ '\\}','}','\\)',')','\\\]','\]',
                        \ '\\end\s*{.\{-}}',
                        \ '\\right\s*\%([^\\]\|\\.\|\\\a*\)',
                        \ ]
<

                                               *latex-box-settings-completion*
Completion ~

*g:LatexBox_completion_close_braces*    Default: 1
        If nonzero, omni completion will add closing brackets where relevant.
        For example, if nonzero, >
                \begin{itemize
<       completes to >
                \begin{itemize}

*g:LatexBox_bibtex_wild_spaces*         Default: 1
        If nonzero, spaces act as wildcards ('.*') in completion.

        For example, if nonzero, >
                \cite{Knuth 1981
<       is equivalent to >
                \cite{Knuth.*1981

*g:LatexBox_completion_environments*
*g:LatexBox_completion_commands*
        Static completion lists for environments
        |latex-box-completion-environments| and commands
        |latex-box-completion-commands|.
        See |complete-items|.

*g:LatexBox_cite_pattern*
*g:LatexBox_ref_pattern*
        Patterns to match \cite and \ref commands for BibTeX and label
        completion. They must include the trailing '{'.

        Examples: To match only the 'cite' command (case insensitive), use: >
                let LatexBox_cite_pattern = '\c\\cite\*\?\_\s*{'
<       To match all commands that end with 'ref' (case insensitive), use: >
                let LatexBox_ref_pattern = '\c\\\a*ref\*\?\_\s*{'
<       Both of the above examples also match commands with a trailing star.

        Defualt values: >
                let g:LatexBox_cite_pattern
                        \ = '\c\\\a*cite\a*\*\?\(\[[^\]]*\]\)\_\s*{'
                let g:LatexBox_ref_pattern
                        \ = '\C\\v\?\(eq\|page\|[cC]\)\?ref\*\?\_\s*{'
<       The default settings should work for most standard LaTeX packages.

*g:LatexBox_complete_inlineMath*        Default: 0
        Switch for inline math completion.

*g:LatexBox_eq_env_patterns*
        Equation environments besides '$...$', '\(...\)', and '\[...\]' that
        support inline math completion.

        Note that 'eq-env-name*' will also be supported if we add
        'eq-env-name' in the list.

        Default: >
                let g:LatexBox_eq_env_patterns
                        \ = 'equation\|gather\|multiline\|align'
                        \   . '\|flalign\|alignat\|eqnarray'
<

------------------------------------------------------------------------------

Templates (DEPRECATED) ~

*g:LatexBox_templates*

        Dictionary of environment templates |latex-box-templates|.

        DEPRECATED!
        I think it is better to leave this task to plug-ins oriented to do
        this well, like snipMate:
        http://www.vim.org/scripts/script.php?script_id=2540

------------------------------------------------------------------------------

                                              *latex-box-settings-compilation*
Compilation ~

*g:vim_program*                                 Default: autodetected
        Vim program to use on command line for callbacks. If autodetect
        fails, defaults to: >
                '/Applications/MacVim.app/Contents/MacOS/Vim -g'
<       on MacVim, or to |v:progname| on other systems.

*g:LatexBox_latexmk_async*                      Default: 0
        Enable asynchronous LaTeX compilation using vimserver. This will
        allow latexmk to run in the background and load any compilation
        errors in a quickfix window after it finishes running.

*g:LatexBox_latexmk_preview_continuously*       Default: 0
        Run latexmk in continuous mode (i.e. with the "-pvc" option).
        Latexmk will track the currently edited file for writes and
        recompile automatically when necessary, without hanging VIM.
        Setting |g:LatexBox_quickfix|=2 is recommended when this is enabled,
        to prevent the quickfix window from stealing the cursor.

*g:LatexBox_latexmk_env*                        Default: ""
        Additional environment options to place in front of the latexmk
        command, e.g. >
                let g:LatexBox_latexmk_env = "TEXINPUTS=~/mytex:"

*g:LatexBox_latexmk_options*                    Default: ""
        Additional options to pass to latexmk during compilation, e.g, "-d".

*g:LatexBox_output_type*                        Default: "pdf"
        Extension of the output file. One of "pdf", "dvi" or "ps".

*g:LatexBox_viewer*                             Default: "xdg-open"
        Viewer application for the output file, e.g., "xpdf".

*g:LatexBox_quickfix*                           Default: 1
        Adjust the behavior of the quickfix window when there are compilation
        errors or warnings. See also |g:LatexBox_show_warnings|. Recognized
        options are:

        Value   Effect ~
        0       The quickfix is not opened automatically.
        1       The quickfix window is opened automatically if not
                empty and becomes the active window.
        2       The quickfix window is opened automatically if not
                empty but the cursor stays in the current window.

*g:LatexBox_autojump*                           Default: 0
        Automatically jump to first error after calling latexmk.

*b:main_tex_file*                               Default: ""
        Path to the main LaTeX file associated to the current buffer.
        When editing a LaTeX document consisting of multiple source files, set
        this variable to the path of the main source file on which LaTeX must
        be called.

*g:LatexBox_show_warnings*                      Default: 1
        If set to 1, warnings in compilation will be listed as errors.

*g:LatexBox_ignore_warnings*
        A list of warnings to be ignored.

        Default: >
                let g:LatexBox_ignore_warnings
                        \ = ['Underfull', 'Overfull', 'specifier changed to']
<

*g:LatexBox_build_dir*                          Default: ""
        Set output directory for build files.

*b:build_dir*                                   Default: ""
        Set output directory for build files. This overrides the global
        setting.

------------------------------------------------------------------------------

                                                  *latex-box-settings-windows*
Vim Windows ~

*g:LatexBox_split_width*                Default: 30
        Width of vertically split vim windows. Used for the table of contents.

*g:LatexBox_split_side*                 Default: "leftabove"
        On which side the vertically split windows appear. Used for the table
        of contents. Set to "rightbelow" to have it on the right side.

*g:LatexBox_split_resize*               Default: 0
        Resize vim/gvim when opening new windows. Used for the table of
        contents. If set to 1, it will add/remove |g:LatexBox_split_width| to
        the number of columns dynamically, in order to keep the latex file open
        with the desired width.

*g:LatexBox_toc_hidehelp*               Default: 0
        If enabled, the help info at the bottom of the TOC window will be
        hidden.

==============================================================================

FOLDING                                                    *latex-box-folding*

LatexBox can fold texts according to LaTeX structure (part, chapter, section
and subsection). Folding is off by default, and can be turned on by defining
the |g:LatexBox_Folding| variable.

The standard fold settings should suffice for most people. When folding is
turned on and a latex document is opened, the document is parsed once in order
to define the highest fold level based on which parts and sections should be
folded.

*g:LatexBox_Folding*                    Default: undefined
        Set to 1 to activate LaTeX structure folding. Please note that any
        modeline that would set |foldmethod| to something else than
        'fold-expr' will disable the function. The same goes for |foldexpr|.
        Set this variable in your .vimrc

*g:LatexBox_fold_preamble*              Default: 1
        Turn on/off folding of preamble

*g:LatexBox_fold_envs*                  Default: 1
        Turn on/off folding of environments

*g:LatexBox_fold_parts*
        Define parts that should be folded. These are intended as top level
        parts such as \frontmatter and \appendix, and if they are present in
        a latex document they will get fold level 1.

        Default: >
                let g:LatexBox_fold_parts = [
                        \ "appendix",
                        \ "frontmatter",
                        \ "mainmatter",
                        \ "backmatter"
                        \ ]
        <

*g:LatexBox_fold_sections*
        Define which section levels should be folded. The order of the
        elements defines the order in which they are folded.

        Default: >
                let g:LatexBox_fold_sections = [
                        \ "part",
                        \ "chapter",
                        \ "section",
                        \ "subsection",
                        \ "subsubsection"
                        \ ]
        <

*g:LatexBox_fold_toc*                   Default: 0
        Turn on/off folding of TOC (|latex-box-commands-motion|).

*g:LatexBox_fold_toc_levels*            Default: 1
        Set number of section levels to fold in TOC.

==============================================================================

INDENTATION                                                 *latex-box-indent*

*g:LatexBox_custom_indent*              Default: Not defined
        The custom indent file of LaTeX-Box is ignored if this variable is
        defined and set to 0.  This will revert to the default indentation
        file from vim.

==============================================================================

FREQUENTLY ASKED QUESTIONS                                     *latex-box-FAQ*

Q: How can I use SyncTeX with the Skim viewer?

A: Add the following line in your ~/.latexmkrc file: >

        $pdflatex = 'pdflatex -synctex=1 %O %S'

<  and create a "latex-search" mapping (<Leader>ls) in your ~/.vimrc: >

        map <silent> <Leader>ls :silent
                \ !/Applications/Skim.app/Contents/SharedSupport/displayline
                \ <C-R>=line('.')<CR> "<C-R>=LatexBox_GetOutputFile()<CR>"
                \ "%:p" <CR>

<  (inspired from vim-latex).

   Alternatively, the option for latexmk may be given through the variable
   |g:LatexBox_latexmk_options|, for instance as: >

        let g:LatexBox_latexmk_options
                        \ = "-pdflatex='pdflatex -synctex=1 \%O \%S'"

<  which can be added to your .vimrc file as desired.

Q: How can I use xelatex instead of pdflatex for some documents only?

A: Instead of putting the settings in your ~/.latexmkrc file, put them in your
   document's working directory, in a file named latexmkrc or .latexmkrc: >
        $pdflatex = 'xelatex %O %S'

Q: How can I specify the main TeX file for a multi-file document

A: There are several ways to do this:

   1. Add a comment to the first few lines of your file to specify this: >
        %! TEX root = main.tex
<  2. Create an empty file called 'main.tex.latexmain' in the same directory.

==============================================================================

TODO                                                          *latex-box-todo*

- Improve TOC jumping and filter out weird characters. Deal with multiple
  sections with the same name.
- Fix bugs?

==============================================================================

vim:tw=78:ts=8:ft=help:norl:
