*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, and bibtex entries;
- 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-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-FAQ|				Frequently Asked Questions

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

COMPLETION						*latex-box-completion*

Completion is achieved through omni completion |compl-omni|, with default
bindings <CTRL-X><CTRL-O>. There are four 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
complilation.

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|


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

COMMANDS						*latex-box-commands*

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

							*latex-box-commands-compilation*
Compilation ~

*:Latexmk*
	Compile with latexmk in background.
	See |g:LatexBox_latexmk_options|.
*:LatexmkForce*
	Force compilation with latexmk in background.
*:LatexmkClean*
	Clean temporary output from LaTeX.
*:LatexmkCleanAll*
	Clean all output from LaTeX.
*:LatexmkStop*
	Stop latexmk if it is running.
*:LatexmkStatus*
	Show the running status of latexmk for the current buffer.
*:LatexmkStatusDetailed*
	Show the running status of latexmk for all buffers with process group
	ID's.
*:LatexErrors*
	Load the log file for the current document and jump to the first error.

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



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

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 in background.
<LocalLeader>lL		|:LatexmkForce|
	Force compilation with latexmk in background.
<LocalLeader>lc		|:LatexmkClean|
	Clean temporary output from LaTeX.
<LocalLeader>lC		|:LatexmkCleanAll|
	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		|:LatexmkStatusDetailed|
	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>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.


						*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*		Default: '\\cite\(p\|t\)\?\*\?\_\s*{'
*g:LatexBox_ref_pattern*		Default: '\\v\?\(eq\|page\)\?ref\*\?\_\s*{'

	Patterns to match \cite and \ref commands for BibTeX and label completion.
	Must include the trailing '{'.
	To match all commands that contain 'cite' (case insensitive), use: >
		let LatexBox_cite_pattern = '\c\\\a*cite\a*\*\?\_\s*{'
<	To match all commands that end with 'ref' (case insensitive): >
		let LatexBox_ref_pattern = '\c\\\a*ref\*\?\_\s*{'
<	Both examples match commands with a trailing star too.


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

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


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

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

*g:LatexBox_split_width*	Default: 30

	Width of vertically split vim windows. Used for the table of contents.


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

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


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 either latexmkrc or .latexmkrc: >
	$pdflatex = 'xelatex %O %S'
<

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

TODO						*latex-box-todo*

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

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

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