5.3 Latex-Suite \cite completion

5.3.1 Caching the \cite completion results

Latex-Suite provides an easy way to insert references to bibliographic entries. Pressing <F9> when the cursor is placed inside a partially completed \cite command will split open a new window (named __OUTLINE__) which contains a formatted and syntax highlighted list of all bibtex entries found. For example, pressing <F9> after typing \ref{ should present you with a window which looks something like this:

Article [dickinson:science:99]
   "Wing rotation and aerodynamic basis of insect flight"
   M. H. Dickinson and F-O. Lehman and S. P. Sane
   In Science, 1999

Article [ellington:84:part1]
   "The Aerodynamics of Hovering Insect Flight. I. The Quasi-Steady Analysis"
   Ellington, C P
   In Philosophical Transactions of the Royal Society of London. Series B, Biological Sciences, 1984

Article [ellington:84:part2]
   "The Aerodynamics of Hovering Insect Flight. II. Morphological Parameters"
   Ellington, C P
   In Philosophical Transactions of the Royal Society of London. Series B, Biological Sciences, 1984
    

You can easily jump from one entry to another using the 'n' and 'p' keys (to go to the next / previous entry respectively).

You can also filter out a subset of the bibtex entries by pressing 'f' while in this window. Doing this presents the following prompt:

Field acronyms: (`:let g:Tex_EchoBibFields = 0` to avoid this message)
 [t] title         [a] author        [b] booktitle
 [j] journal       [y] year          [p] bibtype
 (you can also enter the complete field name)
Enter filter criterion [field<space>value]:
    

At the prompt, type

a ellington

Notice that the letter a is an acronym for author according to the prompt above. Therefore this filter only shows those bibtex entries whose author field contains the text ellington. You can keep narrowing your selection by repeatedly filtering the results. If you would like to remove all the filters and see all entries again, press 'a', which removes all the filters.

You can also sort the bibtex entries based on a field. To do this, press 's'. This will present you with a prompt like in the case of the filter and you are asked to choose a field. In this case, you would type in a single character. This sorts the entries according to that field.

Note

<F9> will also work in a similar way after any command which contains the word cite in it. For example, pressing <F9> will also work with \citenum etc.

The following logic is applied to find out which bibliographic entries are included in the completion.

  1. Firstly, if the present file has a master-file defined for it, then Latex-Suite will perform the following steps on that file instead of on the current file.

  2. First, the file is scanned for a \bibliography command. To explain better, assume that a command

    \bibliography{file1,file2}

    is found in the present file. For each bibliography file, say file1, Latex-Suite first tries to see if a .bib file, file1.bib can be found. If so, it will scan it for bib-keys of the form @BOOK{ etc., and add these searches to the completion list. If a .bib file cannot be found, then it will try to see if file1.bbl can be found. If so, Latex-Suite will search it for bib-keys of the form \bibitem and add these to the completion list.

    You can set the location where Latex-Suite will search for .bib and .bbl files using the |Tex_BIBINPUTS| variable.

  3. If a \bibliography command is not found, then Latex-Suite tries to scan the present file for a \begin{thebibliography} environment. If found, Latex-Suite searches the present file for bib-keys of the form \bibitem.

  4. Finally, it will try to see if this file includes other files via the \input command. For each such file found, Latex-Suite will repeat the previous two steps stopping at the first file which has either a \bibliography command or a thebibliography environment.

5.3.1 Caching the \cite completion results

Often times, the editing cycle proceeds by first laying out a comprehensive bibliography and then completing all the \cite commands in one session. In such situations, it is inefficient to scan the whole list of bibliography files for bib-keys each time. Latex-Suite provides a way to cache the results of the cite completion search using the Tex_RememberCiteSearch variable. If set, Latex-Suite will perform the search only the first time <F9> is used. Next time on, it will reuse the search results. If you wish to redo the search results, issue the command

TClearCiteHist

This will redo the completion list next time you use <F9>.