-
Notifications
You must be signed in to change notification settings - Fork 1
/
automatic-tex-plugin.txt
1339 lines (1133 loc) · 51.8 KB
/
automatic-tex-plugin.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
automatic-tex-plugin* *atp*
Introduction to Automatic (la)TeX Plugin
by Marcin Szamotulski
----------------------------------------
If you found this plugin useful, you are cordially invited to write to me:
mszamot@gmail.com. This is my first vim plugin, and its a great pleasure
to get even the smallest message.
Abstract
========
This is a new plugin for vim to comfortably write TeX (LaTeX, PdfLaTeX)
documents, which provides functionality not met in other such plugins. It
makes you FREE from compiling procedure, making this process automatic using
autocommands. It also provides useful mappings and other functions: analyse
your .log file to see the table contents, to search for a label, to search in
bib files. To have full functionality you need: texloganalyser (a perl
program written by Thomas van Oudenhove) and pdffonts available in the package
app-text/poppler-utils (at least in Gentoo). Another good tool is texdoc,
which is a part of texlive - these days standard TeX distribution for Linux,
and MikTeX on Windows.
Features include:
* a powerful function to search in bibliographic files (bib files):
See |atp-bibsearch|,
* table of contents which allows to switch between different '.tex' files:
See |atp-TOC()|,
* list of labels which allows to see the context of a label:
See |atp-Labels()|,
* a command to list ToDo lines:
See |atp-ToDo()|.
*atp-help-toc*
|atp-installation| Installation
|atp-functions| Functions
|atp-bibsearch| Searching in bib files
|atp-configure| How to configure to your needs
|atp-mappings| Mappings and Commands
|atp-errors| Error handling
|atp-requirements| Requirements
|atp-viewers| Note about viewers (including inverse and reverse searching for xdvi)
|atp-color-highlight| Colors and syntax files
|atp-remarks| Final remarks
|atp-copy-rights| Copy Rights
Note on usage: type :help atp<CTRL>d to see all the helptags. To see help tags
for all the defined functions :help atp*()<CTRL>d, mappings: :help atp-map<CTRL>d
================================================================================
Installation *atp-installation*
>
:filetype plugin on is required to run this plugin, see
|:filetype-plugin-on| and |:filetype-indent-on| if you want to have
automatic indentation for TeX files.
<
To install you just need to copy tex.vim file to ~your ~/.vim/ftplugin/
directory copy this help file to ~/.vim/doc and then run :helptags ~/.vim/doc
and that's all, now you can just type your story ... :)
================================================================================
Functions *atp-functions*
The main function is not seen by the user (it is called s:compiler, for those
who want to read the plugin). It executes tex compiler specified by the
variable b:texcompiler. It is executed
as an autocommand by the line:
au! CursorHold $HOME*.tex silent call 's:auTeX()'
where s:auTeX() is a simple function which calls s:compiler if the file written
on the disk and the buffer differ.
As you can see it will run if a key is not pressed during time defined by
option 'updatetime' (see |CursorHold|) in the normal mode. If you type in
insertmode the file wan't be compiled (and that's alright as you can be in the
middle of your very long formula). The value of 'updatetime' which works fine
is around 1000ms ('updatetime' is set in miliseconds). Tex compiler is run with
two options:
-output-directory
-jobname
which points to a unique temporary file in vim temporary directory (using the
function 'tempname()' (see |tempname()|. If you are concerned with security
reasons read also: |shelltemp|.
You can switch off/on the function s:auTeX by pressing <S-F5> or by letting
the local to buffer variable b:autex=1 (on) b:autex=0 (off). It is useful in
some situations turn automatic compiling off. The key <S-F5> calls the function
ToggleAuTex() which sets the variable b:autex and issue a message. You can also
set this variable to 0 for some files that are not supposed to be processed,
for example:
>
au BufRead texmf/*.tex let b:autex=0
<
The second important variable b:texcompiler (see |atp-texcompiler|) configures
if you use TeX, PdfTeX, LaTeX, PdfLaTeX and it should point to the program
name so please do not use capital letters.
Next variable to set is b:outdir (see |atp-outdir|). It configures where TeX
will put the output and where viewer and log analyzing tools can find
appropriate files.
The last top most important variable is |atp-keep| which is a list of extensions,
by default it is
let g:keep = ["log","aux","toc","bbl"]
Files with this extension will be copied from b:outdir to the temporary
directory with appropriate name to be used when (La)TeX is compiling. (log file
will be only copied after it is created, other files will be copied back and
forth between you b:outdir and the temporary directory)
There is also a variable which stores the last command which executed
your tex compiler, see |atp-texcommand|.
The last remark is that it is convenient to see if tex is running, if you are
using a simple window manager like DWM or WMII or some others you can do that
in your .xinitrc file. If you are using more complex window manager (Gnome,
KDE) you can use the command GPID (which is mapped to \g). It returns pid
of |atp-texcompiler| if it runs. The vim status line could be used for that but
it seems to be to slow and the screen gets messy (at least for me).
If you have defined a function with the same name it wan't be overwritten.
You can check where the function was defined by the command
:verbose function TEX
the last component is the name of the function (without () at the end).
Below I explain functions which are defined:
/all of them do not have any arguments/
TEX([runs]) *atp-TEX()*
map \l,imap \l, :TEX
If anyway you want to run TeX yourself but you do not want to see the
output this is the right tool. This runs TeX in 'nonstopmode'. You can
specify an argument 'runs' which tells how many consecutive runs of
TeX you need (this is important if you want to compile Table of
Contents, or index, or the bibliography (see |atp-Bibtex()|)
If b:openviewer=1 and there current viewer (b:Viewer) is not running on the
output file then this function will open a viewer. By default b:openviewer=0
and this feature is disabled.
The command :2TEX will run :call TEX(2), :TEX 3 do :call TEX(3), and
:2TEX3 will resolve to :call TEX(3).
It is useful when you want to make the outline (using hyperref
package) of your article in pdf files, the tex file has to be
'sourced' twice. To make the bibliography you can use |atp-Bibtex()|.
If runs > 5 it will be reduced to 5, to avoid running tex for hundreds
(or event thousands) of times (what could happen otherwise by
a mistake giving the range of the command to be the current line
number).
VTEX([runs]) *atp-VTEX()*
map <F5>,imap <F5>, :VTEX
Verbose TeX, if you want to see the log file after tex compiler is
called. This runs TeX in the errorstop mode.
If b:openviewer=1 and there current viewer (b:Viewer) is not running
on the ouput file then this function will open a viewer. By default
b:openviewer=0 and this feature is disabled.
If the variable 'runs' is specified is given then VTEX will call the
tex compiler as many times as given. Only the last time is with
errorstop mode.
The command :2VTEX will run :call VTEX(2), :VTEX 3 do :call VTEX(3), and
:2VTEX3 will resolve to :call VTEX(3).
ShowErrors *atp-ShowErrors*
:ShowErrors <flag>
This command shows error/warning messages. It sets the |'errorformat'|
variable accordingly to the flag, which is a word made of letters:
>
e - include errors
w - include all warning messages
r - include all reference warnings
c - include all citations warnings
f - include all font warnings
<
If none flag is given 'e' is used.
Example:
>
:ShowErrors rc
<
will show all reference and citation warnings.
SetErrorFormat *atp-SetErrorFormat*
:SetErrorFormat <flag>
This command has the same syntax as :ShowErrors. It only sets the
|'erroformat'| variable.
Bibtex([debug]) *atp-Bibtex()*
map \b, :Bibtex, :Bibtex v
This function will call bibtex to produce the bibliography file
(.bbl). If in |atp-outdir| there is no 'aux' file it first calls tex
compiler. After the 'bbl' file is produced two consecutive runs of tex
compiler are called to make the bibliography.
If you specify any value to the debug variable then then this function
will be called in verbose mode (only the last time tex compiler will
run in errorstop mode). This gives you the chance to see the output of
bibtex command for a second. The command :Bibtex v is associated to
this behaviour. If you want to just run bibtex see the next function.
The command :Bibtex will :call Bibtex(), while :Bibtex v
(and :Bibtex <anything>) will :call Bibtex(1)
*atp-BIBINPUTS*
Bibtex is looking for the date base files in the current directory
otherwise in the directory defined by $BIBINPUTS environment variable.
You can set in in your environment. If it is not set it will be
set to g:texmf/bibtex (so the default value is $HOME/texmf/bibtex).
SimpleBibtex() *atp-SimpleBibtex()*
map \sb, :SBibtex
This calls bibtex on the aux file in your |atp-outdir| directory and
shows you the output. It is useful if you are debugging your
bibliography database.
ViewOutput() *atp-ViewOutput()*
map \v,map <F3>, imap \v, imap <F3>
You would like to see what you are editing use this function. It will
use the program defined in the variable b:Viewer. See |atp-Viewer|,
|atp-XpdfServer|, |atp-XpdfOptions|. When there is no output file it will run
TeX and open the file. Read more about particular viewers
(inverse/reverse searching) in |atp-viewers|.
:SetXdvi *atp-SetXdvi*
This command sets the options for xdvi viewer, which enables inverse
and reverse searching. It sets the command
:IS[earch]
and the map '<LocalLeader>is' for inverse searching. For reverse
searching hold CTRL and click with left mouse button on the text in
xdvi viewer.
:SetXpdf *atp-SetXpdf*
This command sets the options for xpdf viewer (as for now the
inverse/reverse searching in pdf files is not implemented)
BibSearch({pattern},{flag}) see |atp-BibSearch|
:BibSearch
This function finds bib entries in bib files defined in your tex file and in the
variable b:bibfiles (see |atp-bibfiles|), which match the
pattern. The output is configurable by the flag argument, see
|atp-bibflags|.
BibChoose() see |atp-BibChoose|
:BibChoose, map c, map y, map p
This function is defined in the window with results of BibSearch
command. It is mapped to 'y' and 'c' and let you copy the bib entry key
to a register (see |atp-BibChoose|) or directly to last opened
buffer (after the last cursor position). When you paste it will close
the Bibsearch window.
FindBibFiles({bufname}) *atp-FindBibFiles()*
:FindBibFiles
This updates the variables s:bibfiles, s:allbibfiles,
s:notreadablebibfiles (showed by ShowOptions command). Finds all bib
files defined in all '\bibliography' commands. For more about the
above variables read |atp-variables-bib|. This function is called
internally be the script functions BibSearch/BibChoose/ShowOptions.
The command :FindBibFiles finds bib files in the current buffer.
If a readable bib file was not found in b:outdir and $BIBINPUTS
(see |atp-BIBINPUTS|) directories it is classified as not readable.
FindInputFiles([bufname]) *atp-FindInputFiles()*
:FindInputFiles [bufname]
This function finds all the input files, i.e. files put after the
tex commands: '\input', '\include' or '\includeonly'. And prints the
reuslt.
The function and the command have one optional argument - the buffer
name. By default it searches for input files in the current buffer.
The bufername complition is set, hence you can use <Tab> to choose the
bufername.
EditInputFile([input_file_name],[bufname]) *atp-EditInputFile()*
:EditInputFile [input_file_name] [bufname]
This function finds input files (using the function FindInputFiles()
in the current buffer and let you choose one to edit. window.
The first as well as the second argument are optional. There is
completion for the input file name, so that you can just press <Tab>
to switch between input files. If you want to list the first and then
choose do not pass any arguments.
The input file name may contain white spaces, but then has to be quoted
with '"' (this is a latex requirement).
Input files are searched in the |atp-outdir| directory, if not found
there then in the directory |atp-texmf|. The default value is
g:texmf=$HOME/texmf, which is the default value of local texmf tree in
texlive.
The bibliographis declared are also listed. The command searches for
them in the b:outdir and if not found there in $BIBINPUTS directory.
(see: man bibtex)
OpenLog() *atp-OpenLog()*
map <F6>l, imap <F6>l
Opens log file in a new tab with two options (which are set
locally): ruler, nospell.
You can also use the standard command (distributed with vim)
":Texplore" to see log,aux,... files.
Delete() *atp-Delete()*
map <F6>d
Delets the files produced by TeX wich extensions belongs to
g:texextensions (see |atp-texextensions|). It removes not taking care
about the name, i.e. it runs like: rm *.out.
Print(<printer>,<printer_options> *atp-Print()*
map \p,:SshPrint
It will run 'lpr' command and append to it the options defined in the
variable 'g:printeroptions' + options given in the second argument. It
prints the pdf or dvi depending on the value of 'b:texcompiler' (see
|atp-texcompiler|). If you specify the variable
'g:atp_ssh=<user>@<host>' it will print via ssh on the <host> using
the <printer>. The command ':SshPrint' has a completion set for the
printers available on your local system or in the host. All the
arguments of the command SshPrint are |<f-agrs>|.
The map '\p' will print on the default printer.
ShowOptions() *atp-show-options* *atp-ShowOptions()*
:ShowOptions, :ShowOptions v
This will show values of variables that are currently set. If you specify any
argument the deafult values will be shown is square brackets.
>
:ShowOptions v
<
TOC() *atp-TOC()*
map \t, :TOC
Shows Table of Contents of your document. It do not yet support the
started version of chapter, section,... environemnts. It opens new
window in which you can use the mappings:
'e' to echo the line from your tex file
'y' to yank the label of the chapter under the curosor
to a register, if it exists,
'p' to paste it directly to your tex file (just after the
current cursor position),
's' it splits the window with your tex source file and
sets the current line to the beginning of the
chapter/section under the cursor,
'q' to quit, and finaly,
<Enter> to go to the chapter under the cursor and close ToC.
<space> to go to the chapter under the cursor but leave ToC
open.
There are also commands: ':C' and ':P', which do the same as 'c' and
'p' mappings. They all call the function 'Yank(<where>)', the argument
<where> can be one of: '@<register name>' or 'p'.
TOC() supports many eddited files. For example if you have in your
buffer list two files a.tex and b.tex this command will produce table
of contents of both of them. If you have just one opened window
(excluding the ToC window) then pressing <space>, <enter>, p and q
will take you to the right buffer (which will be read if is unloaded
or hidden). If you split a window then <space>, <enter>,
p, q will take you to the window from which you are comming. However,
if you have two windows with two different buffers loaded they will
act on the window with the matching buffer name.
The variable t:toc_window_width sets the width of table of contents
window. By default t:toc_window_width=30. You can set a global
variable g:toc_window_width to overide the default value.
CTOC() *atp-CTOC()*
:CTOC
This function returns the name of the currently eddited chapter/
section/subsection/subsubsection. Use ':echo CTOC()' or just ':CTOC' to
see the returned value. If you added a section unit the function will
not update the database, run ':TOC' to do that (map \t).
Labels() *atp-Labels()*
map \L, :Labels
Shows labels defined in your file. You can also use the mappings
'e','c','p','s','q' and <Enter> as above.
If you forget what are these mappings, write ':map' in the TOC or
LABELS window.
The key 's' shows the context of the label under the cursor (your
current window splits).
The variable t:labels_window_width sets the width of labels window. By
default t:labels_window_width=30. You can set a global
variable g:labels_window_width to overide the default value.
ToDo(<keyword>,<stop>,[bufname]) *atp-ToDo()*
:ToDo [bufname]
:Note [bufname]
This function list all the lines of the buffer [bufname] which match
for the pattern '%.*<keyword>'. The <stop> argument is the pattern to
before which to stop. The optional argument is the buffer
name (the buffer name complition is set on). If not given the
current buffer is assumed.
You can set highlighting for this command by:
highlight atp-Todo ctermfg=... guifg=...
The command :ToDo sets keyowrd='\c\<todo\>' and
stop='\s*%.*\c\<note\>', and the command :Note
sets keyowrd='\c\<note\>' and stop='\s*%.*\c\<todo\>'. This prevent
from listing ToDo lines with Notes and vice versa.
SpecialSpaceToggle() *atp-SpecialSpaceToggle*
:SpecialSpaceToggle, map <F2>
This function (command) sets, if it is undefined or removes if it is
defined, the mapping:
>
:cmap <Space> \_s\+
<
which is useful when searching by the command '/', especially if
|'textwidth'| or |'wrapmargin'| is non zero (and |'formatoptions'|
contains one of the flags 't', 'v' or 'b'). Then each <Space> will
match for a space which also might end of the line.
:SetOutDir *atp-SetOutDir*
This is a command wich sets the 'b:outdir' variable and the |'errorfile'| option.
See |atp-outdir| for the default value.
:SetErrorFile *atp-SetErrorFile*
If you change |atp-outdir| variable and you want to update the
|'errorfile'| option use this command. It will show you the value to
which |'errorfile'| was set.
ATPStatus *atp-ATPStatus*
:ATPStatus
This function (command) sets the status line, which include: the name
of currently eddited chapter (or section) the value of 'b:outdir' and
it will warn you if 'b:outdir' variable is not set. This function is
called at startup unless the variable 'g:atp_statusline=0' is set (for
example in you $VIMRC file). The status is set by the autocommand:
>
au BufWinEnter *.tex :call ATPStatus()
<
In this way every opened window with a '*.tex' file will get the correct
status line.
================================================================================
Searching in bib files *atp-bibsearch*
___________________________
Tabel of Contents:
|atp-BibSearch|
|atp-bibpatterns|
|atp-bibflags|
|atp-bibflags:default|
|atp-bibsearch-show-only-keys|
|atp-bibflags:+|
|atp-bibflags:output|
|atp-bibflags:all|
|atp-bibflags:last|
|atp-bibflags:add-flag|
|atp-BibChoose|
|atp-bibsearch-highlight|
|atp-BibSearch-command|
|atp-bibflags:examples|
|atp-bibsearch-variables|
|atp-bibfiles|
____________________________
Naming Convensions:
@article{<label>, \
author = { .... }, <-- bib entry |
title = { .... }, > bib field
journal= " .... ", |
} /
article <-- bib field keyword
author,title,... <-- bib entry label
<label> <-- bib field label
One more function is provided which searches the bib files for bib fields,
and for the bib field labels for the latex command \cite{}.
BibSearch([pattern],[flags]) *atp-BibSearch*
The function BibSearch allows you to search for the pattern in bib
files and opens a new window with results. For the command, please read
|atp-bibsearch-command|.
The function BibSearch takes two arguments (the last one is optional).
The first one is the pattern to match against each line of the
bibliographic files supplied in the commands \bibliography (if there
are several names,please do not add a white space ' ' after ',' unless
the file name begins with a space, i.e.
>
\bibliography(Mathematics, Physics,/home/user/Bibliography)
<
then the plugin will understand that the names of the bib files are
'Mathematics.bib', ' Physics.bib' and '/home/user/Bibliography.bib'.
*atp-bibpatterns*
Each line of every bib file found in your tex docummnet will be
matched against the pattern, for example if the pattern is:
>
'author.*Grothendieck'
<
the BibSearch function will find all the bibliographic fields
which in one line have the words 'author' and 'Grothendieck' (in most
cases it means that you will see only works of Grothendieck). Another
example:
>
'^\(\s*author.*Joayl\)\|Galois Theory'
<
will result in all bib fields which author is Joyal or
which includes the words 'Galois Theory' (which by the way apear in
many article/book titles), yet another example:
>
'author.*Joayl\|title\p*Galois Theory'
<
This will match against all bib entries written by Joyal or which title
includes the word 'Galois Theory'.
>
:call BibSearch('author.*Joyal\&.*Tirney')
<
will find all the bib entries which were written by Joyal and Tirney
(and maybe somebody else).
For now, there is no possibility to filter bibliographic entries which
both match a pattern in separate lines, i.g. to show all bib entries
written by Joyal on 'Descent Theory'.
Before a match, all '{', and '}' are deleted from the line of the bib file.
But you will see them in the output (what can be useful for debugging
errors in bib files)
Note that in vim patterns should be quoted using '...' not "...".
Further examples are supplied after the next section
|atp-bibflags:examples|, which describes other functionalities
of the BibSearch/BibChoos functions.
*atp-bibflags*
The first optional argument [flags] chooses what and in which order
you want to see the bib entries found (entries are listed in
the order they appear in bib file). Flag is a word made of letters.
There are three kinds of flags: entry flags which mathes againts
labels of bib entries, like author, title, etc..., and keyword flags: which
matches agains keywords of bib fields: @article, @book, @techreport,
etc... and two special flags 'All' and 'L'. A flag is a word on
letters:
>
a - author
e - editor
t - title
b - booktitle
j - journal
s - series
y - year
n - number
v - volume
p - pages
P - Publisher
N - Note
S - School
h - howpublished
o - organization
u - url
H - Homepage
any other letter - do not show anything but the first line of bib entry
@a - article /@article/
@b - book or booklet /@book,@booklet/
@B - Booklet /@booklet/
@c - incollection /@incollection,@inbook/
@p - proceedings, inproceedings, conference /@proceedings,@inproceedings,@conference/
@m - misc /@misc/
@M - Manual /@manual/
@t - master or PhD thesis /@masterthesis,@phdthesis/
@T - Techreport /@techreport/
@u - unpublished /@unpublished/
All - all flags (see |atp-bibflags:all|)
L - last flags (see |atp-bibflags:last|)
<
Examples:
>
tayu@a --> show the entries: tile, author, year, url of matching articles.
baeP@b --> show the entries: booktitle, author, editor,
publisher of matching books (@book,@booklet).
<
If flags '@.' are filtered out, if one do not belongs to the one above
then it is deleated. You can see which flags are defined using
ShowOptions function/command (they are listed as Available
KeyWordFlags).
*atp-bibflags:default*
The default flag is stored in the global variable g:defaultbibflags and is
equal to 'tabejsyu'. This means that the ouput for each bib field found
will include the
title
author
booktitle
editor
journal
series
year
if title,author,... are specified in the bibliography for the given
position. If there are many position which match you can set flags to
be as simple as possible to include more lines on the screen. For
example 'tabe' is quite reasonable (note that all bib entries are
matched separately, i.e. if a bib field has both 'title' and 'booktitle'
bib entries it will give you both of them.
*atp-bibsearch-show-only-keys*
If you just want to list just the lines with bib fields keywords:
@article{, @book{, etc. supply a flag which do not belongs to
'g:defaultallbibflags', for example 'X', or 'X@a'
*atp-bibflags:+*
You can also specify flags with '+', for example:
>
flags='+p'
flags='+@b'
<
This feature ADDS FLAGS TO THE DEFAULT VALUE defined in the variable
g:defaultbibflags (see |atp-defaulbibflags|). The first will result in
showing the default entries and the page number, the second will
result in showing only books with the default bib entries. You can
specify as many additional flags as you wish. *atp-bibflags:output*
Note that the function shows the line with database file name if there
are entries in this bibliography which match the pattern thus,for
example, if you specify the flag '@a' and you see the line with
database file name, but you do not see any bib entry, then in this
database there are bib fields which match but these are not articles.
*atp-bibflags:all*
The flags='All' is a synonim of flag=g:defaultallbibflags which by default is
equal to'tabejfsvnyPNSohiuHcp' i.e. all flags in this order. If you
add your own flag you should change this global variable. You can add to
this flag any flag which contains '@' (see |atp-bibflags|) by
the plus operator, i.e. All+@a@b or +@aAll will give the same result.
*atp-bibflags:last*
*atp-lastbibflags*
The variable 'b:lastbibflags' stores the recently used flags. The flag
'L' sets the flags for this search to the value of 'b:lastbibflags'.
You can write '+L@a', '+L@a', 'L@a' or '@aL' but not '+@La', if you
want to add some flags to previous searches. Next time the flag 'L'
will change the meaning (i.e. it is really the last time not earlier
:) However, there is no '-' :( '-@aL' could be helpful.
The variable 'b:lastbibflags' is not changed when you use the 'All'
flag.
*atp-bibflags:add-flag*
You can add your own flags but not keyword flags (i.e. @a,@b,...).
Just add an entry to the dictionary g:bibflagsdict. (:ShowOptions v to
see its current value), For example
>
let g:bibflagsdict=extend(g:bibflagsdict, { '<flags_name>' : [
'<bib_entry_name>': '<how_to_show>'] })
<
where, <flags_name> is the flag to use (it should be one letter), it
must be different from the defined flags, <bib_entry_name> is a
lowercase bib entry name, like 'title', 'url', etc., <how_to_show> if
you want to have a nice output put the bib entry name and that much of
white spaces to get 13 strings.
BibChoose *atp-BibChoose*
map c, map y, map p
This function/command is only available in the window with BibSearch results
and allows to copy a bib entry key to a register or directly to the
last opened buffer (after the cursor position). It is mapped to 'c'
and 'y'. You will be asked to give the number of bib entry to yank:
>
<bib entry number><register name><Enter> - to copy it to a register
<bib entry number><Enter> - to paste it to 'tex' file
<Enter> - to skip the choice
<
When you paste the bib entry key the bib search window will close.
*atp-bibsearch-highlight*
The colours of the output are set by the syntax file
'syntax/bibsearch_atp.vim'. All groups except one are the same as in
the syntax file for bib files ('syntax/bib.vim' in your $VIMRUNTIME
directory). Their names are 'bibsearchEntryKw' instead 'bibEntryKw'.
The one that is differently defined 'bibsearchComment'. Which is
changed in that way to highlight the bib file names. One additional
highlight group is: 'bibsearchInfo'. It highlights the number of
entry and its line number in the bib file. By default all bibsearch
groups are linked to the corresponding bib group, the bibsearchInfo
group is not set.
In a colour file (~/.vim/color/*.vim) you can use these groups to set
colours. See |highlight| or just read a colour file. For example,
this is a nice set of colours for dark background
:BibSearch [pattern] [flag] *atp-BibSearch-command*
which do what you expect. The arguments should not be quoted and
separated by a white spaces (if you want to include a white space use
'\ '), for more see |f-args|. If you do not provide any argument then
all entries of all bib files will be shown. Examples:
Some examples: *atp-bibflags:examples*
>
:BibSearch
< this is a tip how to show all bib fields with
the default flags
>
:BibSearch @ yt
< this is a tip how to show all bib fields with
different flags than the default ones, which
is equivalent to:
>
:call BibSearch('','yt')
:BibSearch title[\s.]*Galois Theory aetb
<
The next one shows all bib fields which were written by Joyal and
Tirney (and mayby somebody else).
>
:BibSearch 'author.*Joyal\&.*Tirney'
<
*atp-bibsearch-variables*
*atp-variables-bib*
SOME VARIABLES:
All the values of important variables can be shown by ShowOption
command.
b:bibfiles *atp-bibfiles*
This variable is a list and you can put here additional bib files.
They will be parsed by the BibSearch/BibChoose functions.
The following variables you can see using the ShowOptions command (see
|atp-ShowOptions()|).
s:bibfiles
This variable is a list which stores bib files found in your tex
files and which are readable. It is set up when you first run of the commands:
BibSearch/BibChoose/ShowOptions. Its value is shown by the
functions FindBibFiles({bufname}).
s:allbibfiles
this is a sum of found bib files the locally defined b:bibfiles, which
not necessarily are readable.
s:notreadablebibfiles
guess what :)
-----------------------------------------------------------------------------------
*atp-bibsearch-comments*
Please do not hesitate to report any bug to me:
mszamot@gmail.com
The algorithm will work only if all kind of bib entries of your bib
file are included in the list g:bibentries. However, changing just
this variable is not enough. In that case the search engine (function
s:search) will produce correct output, but the function which displays
found entries, will not know how to work with the new entries. One
would have to also add an entry to the dictionary 'g:bibflagsdict'. If
it is the case, please let me know: mszamot@gmail.com
As you can see entries of the type '@string' which can be used in bib
files are not supported (i.e. there is no function which substitutes
the variables defined in @string to their values), but it is doable.
@string{ Name = Value }
------------------------------------------------------------------------------------
Comments: for a bib file with over 16000 lines and 1675 entries, it
took on my computer (AMD Core 2Duo 1.9Ghz) 25.5s to find all entries,
with the command ':BibSearch . All' and 1s to show results (the
longest loop took over 100000 times). However to find in this database
one entry with default flags (:BibSearch <Name>) it took 2.84s
(exactly 79 matching bib fields), and to display them another 0.6s.
If for you the algorithm is too slow, there is a way to make it more
efficient: the problem with when every line is matched: when we are in
line x we go back to find the nearest line of the form @article{,
@book{, etc., if we find it we go to line x+1 and do it once again. We
could remember previous line numbers and test if we already have done
the calculations. This can avoid long loops.
================================================================================
How to configure to your needs *atp-configure*
*atp-variables*
There are several options you can set, and they might be set in your vimrc
file. The default values are given below.
All buffer variables (see |b:var|), i.e. these which name begins with "b:",
should be set in your vimrc file. The best way to do that is by using
autocommand:
>
au BufReadPre *.tex let b:texcompiler="latex"
<
If you put just let b:texcompiler, this will also work but not always: for
example when you open a new buffer in existing vim session.
let b:texcompiler="pdflatex" *atp-texcompiler*
Used by functions: TEX() (map \l, imap \l), VTEX() (map <F5>, imap <F5>)
You can set it to latex, tex, luatex, and so on and possibly to
lilypond as well.
let b:texoptions=""
If you want to set some additional options to your texcompiler you can
use this variable, note that, -jobname, -output-directory, -mode, are
already used. You can use this to make reverse searching with xdvi see
|atp-xdvi|.
*atp-outdir*
let b:outdir=fnameescape(fnamemodify(resolve(expand("%:p")),":h")) . "/"
Used by ViewOutput(), TEX(), VTEX(), BibTeX(), TexLog(), Pdffonts(), Delete()
i.e. in all functions.
This is the directory in which tex will put the output files. If the
open file is not a symbolic link it is equal to the directory in which
the tex file is located. If the open file is a symbolic link it points
to the directory in which the real file is located.
If you set this variable to './' (or '.') and change the current
working directory for example to /tmp (:cd /tmp) then the latex output
will be placed in /tmp, i.e. it will move with with cd. However, the
default value of b:outdir is not affected by :cd command.
White spaces and other characters should not be escaped. It will be
quoted in '...' using the |shellescape()| function.
You can see the current output directory in the status (it is in the
short notation) to see it whole type:
:echo b:outdir
or use the function ShowOptions() (see |apt-ShowOptions()|).
If in your environment the variable $TEXMFOUTDIR is set the value of
b:outdir will be set to its value.
let b:auruns=1 *atp-auruns*
This variable control how many times the automatic function calls tex
compiler (consecutively). It is useful if you are working with PDF
files and you want to have bookmarks (you can get them using hyperref
package with the option: bookmarks. Then set b:auruns to '2'.
let g:texmf=$HOME/texmf *atp-texmf*
This variable configures where input files are placed. See
|atp-EditInputFile()|.
let g:askforoutdir=0 *atp-askforoutdir*
Its values are 1 and 0. When it is set to 1 you will be asked for the
name of a directory where tex will put output files, note that this
name should end with a "/".
let b:Viewer="xpdf" *atp-Viewer*
it was tested with xpdf, evince, epdfviewer, kpdf, okular, xdvi and
they all works fine. I'm using xpdf and the xpdf server options are
supported so that the file is automatically reloaded (other viewers,
except epdfview, have this functionality as well. This do not works
for acroread. Read more about viewers in |atp-viewers|.
let b:XpdfOptions="" *atp-XpdfOptions*
Used by function: ViewOutput() (map \v, map <F3>, imap <F3>)
For example, if you want to have different look of one document you can
set it to "-bg gray20". Other example:
>
let b:XpdfOptions="-bg Grey30 -mattecolor SlateBlue2 -papercolor White"
<
If you want this option to work in every new open buffer, use an
autocommand like in the following line:
>
au BufRead *.tex let b:XpdfOptions="-bg NavajoWhite4 -fg black -mattecolor burlywood"
<
let b:XpdfServer=fnamemodify(expand("%"),":t") *atp-XpdfServer*
Used by function: ViewOutput() (map \v, map <F3>, imap <F3>)
It is equal to the name of the source file. You do not need escape
spaces in the name (shellescape() function is used before it is send
to the shell).
let b:openviewer=1 *atp-openviewer*
If the function which calles TeX compiler do not see that you are
viewing the output file it will open it for you if b:openviewer=1.
Otherwise, this feature is disabled.
let g:rmcommand="perltrash" *atp-rmcommand*
Used by function: Delete() (map <F6>d imap <F6>d)
If you have another 'trash can' program you can use it here, if you do
not have it you can use "rm" (at your own risk). It is used to delete
the files produced by (La)TeX (see |apt-Delete()|). The function
Delete() will remove all files in the output directory (see
|atp-outdir|), which ends with an extension defined in the list
|atp-texextensions|. If you set:
>
let g:rmcommand=''
<
then the function Delete() (see |apt-Delete()|) will use the vim
|delete()| command, and will delete only the files produced by the
current '.tex' file. The temporary directory is cleared by rm command.
The program 'perltrash' is in the package app-misc/perltrash (at least
for Gentoo).
*atp-texextensions*
let g:texextensions=["aux", "log", "bbl", "blg", "spl", "snm", "nav", "thm", "brf", "out", "toc", "mpx", "idx", "maf", "blg", "glo", "mtc[0-9]", "mtc1[0-9]"]
This list is used by the function Delete() (see |apt-Delete()|) which
delets all the files with the specified extension in the directory
b:outdir, unless g:rmcommand="" (see |atp-rmcommand|) in which case
Delete() deletes only the output files for the current buffer.
let g:keep=["log","aux","toc","bbl"] *atp-keep*
Files with an extension belonging to this list will be copied from
'b:outdir' to the temporary directory with appropriate name. Then it
will be used by (La)TeX. (log file will be copied after it is created,
other files will be copied back and forth between 'b:outdir' and the
temporary directory). These four elements: log,aux,toc,bbl are
essentially minimum to work with: table of contents, pdf-bookmarks and
bibtex. There are possibly other classes, like beamer, or packages
like theorem (produce .thm files) which will need to configure this
variable.
You can change this variable by the command:
:let g:keep+=["thm","spl"]
let g:printeroptions="" *atp-printeroptions*
You can set the printer options. These are options for the 'lpr'
command, which will print the output file (pdf or dvi) this depends on
the b:texcompiler that you use.
b:texcommand *atp-texcommand*
This variable is for debugging. It stores the last executed command to
compile your document. This changes also when your compiler was run
automatically.
>
:TEX
:echo b:texcommand
:TEX 2
:echo b:texcommand
<
g:defaultbibflags see |atp-bibflags:default|
g:defaultallbibflags see |atp-bibflags:all|
b:lastbibflags see |atp-bibflags:last|
b:bibfiles see |atp-variables-bib|
s:bibfiles
s:allbibfiles
s:notreadablebibfiles
For more on bib flags see |atp-bibflags|.
let t:toc_window_width=30
g:toc_window_width (by default not set, if set ovverides
t:toc_window_width)
Configures the initial width of the window with table of contents.
let t:labels_window_width=30
g:labels_window_width (by default not set, if set ovverides
t:labels_window_width)
Configures the initial width of the window with lables.
g:atp_statusline
by default it is not set, put the line
>
let g:atp_statusline=0
<
in your $VIMRC file if you do not want the status line provided by this
plugin. (See |atp-ATPStatus|).
let b:truncate_status_section=40
This variable sets how many characters of the section/subsection title
(or chapter/section titles if you write a book) should be shown in the
status line. Section title and subsection title gets equal amount of
characters.
================================================================================
Mappings and Commands *atp-mappings*
Lots of mappings which are given here uses #. This is a convenient map on
British keyboards, but not in the US layout, you can change them for '`' or
some other key that it is not used in vim (there are not many of them though).
The most commonly used latex-suite plugin uses similar set of mappings (but
there might be some differences).
These mappings are loaded unless you set one of variables: 'no_plugin_maps' or
'no_atp_maps' (disables maps defined in tex_atp.vim) or 'no_atp_toc_maps'
(disables maps defined in 'toc_atp.vim'.
Note: in all mappings "\" is set to your <LocalLeader> (and thus, in fact, the
mappings can differ).
ShowOptions *atp-map-ShowOptions()*
:ShowOptions, :ShowOptions v
TEX() *atp-map-TEX()*
map \l,imap \l, :TEX
VTEX() *atp-map-VTEX()*
map <F5>,imap <F5>, :VTEX
ViewOutput() *atp-map-ViewOutput()*
map \v,map <F3>, imap \v, imap <F3>
Bibtex() *atp-map-Bibtex()*
map \b, :Bibtex
SimpleBibtex() *atp-map-SimpleBibtex()*