LaTeX Tools Plugin.

This plugin is a collection of tools to make LaTeX editing an easier and quicker task. The tools are generally inactive unless the current buffer is a LaTeX file. There are four docking windows available, and several additional tools available through the LaTeX Tools menu:

Overview

This version of LaTeX Tools has added the concept of a LaTeX project, which consists of a main file along with all of the files (recursively) imported by the main file.

A main file can be specified either globally or locally. The global setting is done through the plugin menu, where Set Main File sets the global main file to the current file, and Reset Main File removes the global property. The local setting is achieved by adding somewhere in the first 5 lines of the file the string :latex.root=Absolute or relative path to Main file:. The menu command Show Main File displays the path to the main file in a pop up box. Note that if present, the locally defined Main file has priority, followed by the globally defined property. If no local or global properties have been set, then the current buffer is deemed to be the Main file.

The main file is used by several other commands, such as the Compile commands, the BiBTex command and the Erase Working Files... command. It is also used by the Label Navigator and the BibTeX Navigator in order to correctly parse information. The project files is a term used in these instructions to refer to the set of files that include the Main file and all files imported by files in the set.

Note: Recognized buffer modes

LaTeX Tools function correctly only if the buffer is recognized as a (La)TeX buffer. At present, the following buffer modes are recognized as tex modes: tex, latex.

LaTeX Tools Window

The LaTeX Tools window has two functions, firstly to display a list of possible structure filters for the Structure Browser to use. The current filter is displayed, and changing the filter causes the Structure Browser to reparse the current buffer. The second function is to display information about the project. The type of information is chosen by clicking one of the tool buttons. Currently, Information Information shows the projects main file, and a tree display of the files imported by the main file and its children. View Image View Image looks for a graphics command under the caret, and if it finds one with a displayable image it will display the image in the information panel. Since this only displays jpeg, gif and png images currently, this is most useful to users of PDFLaTeX. The last two buttons are Find Duplicates Find Duplicates and Find Orphans Find Orphans. These search the project files for duplicate label definitions, and references to missing labels respectively. The duplicate labels or orphaned references are displayed in a list, and can be clicked to move the caret to that reference or label.

Structure Browser

This feature implements a document navigator. By default all special elements of the document are displayed in the SideKick structure browser. Controls for selecting a filter for the document elements to parse are included in the LaTeX Tools dockable. Several filters are predefined, but user defined lists can be added to or replace these filters, as described below.

Suggested use.

The way I use the document navigator is to have the Structure Browser docked to the right, and LaTeX Tools docked at the top (it is one line deep, so doesn't take much space). This way it is easy to select the features of the document you wish to see. If you simply want all of the main elements displayed, don't bother with the toolbar - it is the default parser.

User defined Navigation Lists.

User defined navigation lists are text files containing search data for parsing the document, and are placed in the directory specified in the Global Options for the LaTeX Navigator. They have the following syntax:

Navigation lists must have a title as the first line of the list, of the format, "@titlen". title is the name displayed in the combo box; n is a single digit, giving the preferred position in the combo box (1 being the top, 9 being the bottom) or 0 if it should not appear at all. Users can override default lists by adding a new list of the same name to a user list - user lists take precedent over the defaults.

Following the title tag are the lines defining the search strings to look for in the text. These must be of the format, "N:start search string:replace string:end type:end search string:I ". where N is the nesting level of the search string, and I is the icon to use in the sidekick tree.

The start search string is parsed as a regular expression (so if simple definitions are required, remember to escape special characters).

The replace string is an ordinary string, but the strings $1, $2, etc can be used to refer to captured groups in the search string. If the replace string is simply a " " (space) character, then any captured groups are concatenated and used as the text in the tree, or if no capturing groups are present, then the whole found string (group $0) is used as the tree text. Either a replace expression, or single space should be used as the replace string - other strings may have unpredictable results. Note also that if the ':' symbol is required in either search or replace string, the unicode escape \u003A should be used, or the navigation item will not be parsed correctly. An example from the default navigation file follows:

The end type gives the type of scope the element has, and is used in conjunction with the end search string to determine the scope of the element. The types are:

  1. The end of scope is set to the end of the buffer.
  2. The end of scope is set to the end of the start search string.
  3. The end of scope is set to the end of the end search string.

Each type is appropriate for different types of element. In general sections should be type 0, commands should be type 1 and environments should be type 2.


@Sections2
1:\\chapter\{(.+?)\}: :0: :1
2:\\section\{(.+?)\}: :0: :1
3:\\subsection\{(.+?)\}: :0: :1
4:\\subsubsection\{(.+?)\}: :0: :1
5:\\paragraph\{(.+?)\}: :0: :1

@Theorems3
1:\\begin\{theorem\}(\[.+?\])?:Thm\u003A $1:2:\\end\{theorem\}:3
1:\\begin\{lemma\}(\[.+?\])?:Lem\u003A $1:2:\\end\{lemma\}:3
1:\\begin\{proposition\}(\[.+?\])?:Prp\u003A $1:2:\\end\{proposition\}:3
1:\\begin\{definition\}(\[.+?\])?:Dfn\u003A $1:2:\\end\{definition\}:3
1:\\begin\{corollary\}(\[.+?\])?:Cor\u003A $1:2:\\end\{corollary\}:3
2:\\begin\{proof\}(\[.+?\])?:Proof\u003A $1:2:\\end\{proof\}:0

@Graphics5
1:\\begin\{figure\}:Fig\u003A:2:\\end\{figure\}:2
2:\\includegraphic[xs].*?\{(\S*?)\}:Img\u003A $1:1: :0
2:\\caption\{(.*?)\}:Capt\u003A $1:1: :0

Note that the Sections group in this example will only print the section title in the tree. The strings "Thm" etc will be displayed in the case of the Theorems group, along with the description if present.

The integers for various icons are as follows:

default Default 0
section Section 1
graphics Graphics 2
theorem Theorem 3
table Table 4
list List 5
list Verbatim 6
link Import/Link 7
Any other integer value will display no image at all.

BibTeX Navigator

This tool searches the project files for a \begin{thebibliography} environment, or a \bibliography{} command. If the former is found, the current file is searched for \bibitem commands, and compiles a list of such entries. If the latter is found, then all referenced bib files are searched for the reference names and reference titles, and a table compiled containing these.

A dialog is displayed, from which a selection (or selections if the CTRL keys are held down whilst clicking or dragging on table entries) can be made. Once ENTER is pressed, all citations are entered at the cursor position in the current buffer as a comma delimited list. Alternatively, you can insert an entry by double clicking on it. The dialog is canceled by pressing ESCAPE, by closing the dialog window, or by hitting ENTER with no selections made.

The table of BibTeX references may be sorted by other column than "Ref" by clicking once the column header ("Title", "Author", "Journal" or "Ref" again). (The other fields are only shown when editing a .bib file.) To sort in the descending order, hold Shift while clicking on it. To change the current sort order, just click the header for the second time (but not too fast after the 1st click).

Options

Label Navigator

When activated, this tool simply searches the project files for \label{} commands, and displays the results in a dialog. Only single label can be selected (multiple references in a single \ref are not supported in LaTeX as they are in \cite commands).

Clicking a label has the following effects:

The locking mechanism allows the entire list of labels to be explored by clicking the labels to view their positions. Double clicking a reference will insert the reference at the saved cursor location.

Options

Other Tools

Various utility commands are included, accessible through the Plugins menu. These are catagorized as follows:

Compilation

There are six commands here. Compile runs the default compilation command on the current buffer using the Console plugin. The Compile... command allows the user to specify the compilation command in a text box (which maintains a history of commands). View Output and View Output... are similar, but for the output of the compilation (eg. Acrobat Reader, DVI, ghostview etc). BibTeX runs BibTeX on the current buffer, again through the Console. Erase Working Files... displays a checkbox list of file extensions, and deletes all files in the same directory as the Main file with those extensions (giving plenty of opportunity to pull out at the last minute!).

LaTeX Utilities

Rename Label opens dialogs asking for the current name of the label, and the new name. The project files are then examined, and all labels and references matching the first string are changed to the second. Display Image, Find Duplicate Labels and Find Orphaned References open the LaTeX Tools dockable window with the appropriate information displayed.

Text Insertion

These are various shortcuts to manipulate text. They are pretty self explanatory so play around...

Project Management

These are the commands Set Main File, Reset Main File and Show Main File Path. These are described in Project Management above.

Navigation

The commands BibTeX Navigator, Label Navigator Structure Browser and LaTeX Information Panel simply open the relevant dockable windows.

Open Main File simply opens the Main file as the current buffer. Open Import looks to see if there is an import statement under the caret, and if so tries to open the import file.


View Release Notes

LaTeX Tools

Plugin created by Anthony Roy (home@antroy.co.uk) and maintained by Jakub Holý (jakubholy@jakubholy.net). Last Modified: Sunday January 8, 2006