-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathauctex.info
8197 lines (6656 loc) · 370 KB
/
auctex.info
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
This is docerhJsA.info, produced by makeinfo version 6.8 from
auctex.texi.
This manual is for AUCTeX (version 14.0.9.2025-03-11_18:24:01 from
2025-03-11_18:24:01), a sophisticated TeX environment for Emacs.
Copyright (C) 1992-1995, 2001, 2002, 2004-2024 Free Software
Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts and no
Back-Cover Texts. A copy of the license is included in the section
entitled "GNU Free Documentation License."
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* AUCTeX: (auctex). A sophisticated TeX environment for Emacs.
END-INFO-DIR-ENTRY
INFO-DIR-SECTION TeX
START-INFO-DIR-ENTRY
* AUCTeX: (auctex). A sophisticated TeX environment for Emacs.
END-INFO-DIR-ENTRY
File: docerhJsA.info, Node: Top, Next: Copying, Up: (dir)
AUCTeX
******
This manual may be copied under the conditions spelled out in *note
Copying this Manual::.
AUCTeX is an integrated environment for editing LaTeX, ConTeXt,
docTeX, Texinfo, and TeX files.
Although AUCTeX contains a large number of features, there are no
reasons to despair. You can continue to write TeX and LaTeX documents
the way you are used to, and only start using the multiple features in
small steps. AUCTeX is not monolithic, each feature described in this
manual is useful by itself, but together they provide an environment
where you will make very few LaTeX errors, and makes it easy to find the
errors that may slip through anyway.
It is a good idea to make a printout of AUCTeX's reference card
'tex-ref.tex' or one of its typeset versions.
If you want to make AUCTeX aware of style files and multifile
documents right away, insert the following in your init file (usually
'~/.emacs.d/init.el').
(setq TeX-auto-save t)
(setq TeX-parse-self t)
(setq-default TeX-master nil)
Another thing you should enable is RefTeX, a comprehensive solution
for managing cross references, bibliographies, indices, document
navigation and a few other things. (*Note (reftex)Installation::.)
For detailed information about the preview-latex subsystem of AUCTeX,
see *note Introduction: (preview-latex)Top.
There is a mailing list for general discussion about AUCTeX: write a
mail with "subscribe" in the subject to <auctex-request@gnu.org> to join
it. Send contributions to <auctex@gnu.org>.
Bug reports should go to <bug-auctex@gnu.org>, suggestions for new
features, and pleas for help should go to either <auctex-devel@gnu.org>
(the AUCTeX developers), or to <auctex@gnu.org> if they might have
general interest. Please use the command 'M-x TeX-submit-bug-report
<RET>' to report bugs if possible. You can subscribe to a low-volume
announcement list by sending "subscribe" in the subject of a mail to
<info-auctex-request@gnu.org>.
* Menu:
* Copying:: Copying
* Introduction:: Introduction to AUCTeX
* Editing:: Editing the Document Source
* Display:: Controlling Screen Display
* Processing:: Starting Processors, Viewers and Other Programs
* Customization:: Customization and Extension
* Appendices:: Copying, Changes, Development, FAQ, Texinfo mode
* Indices:: Indices
-- The Detailed Node Listing --
Introduction
* Summary:: Overview of AUCTeX
* Installation:: Installing AUCTeX
* Quick Start:: Quick Start
Editing the Document Source
* Quotes:: Inserting double quotes
* Font Specifiers:: Inserting Font Specifiers
* Sectioning:: Inserting chapters, sections, etc.
* Environments:: Inserting Environment Templates
* Mathematics:: Entering Mathematics
* Completion:: Completion of macros
* Commenting:: Commenting text
* Indenting:: Reflecting syntactic constructs with whitespace
* Filling:: Automatic and manual line breaking
Inserting Environment Templates
* Equations:: Equations
* Floats:: Floats
* Itemize-like:: Itemize-like Environments
* Tabular-like:: Tabular-like Environments
* Customizing Environments:: Customizing Environments
Controlling Screen Display
* Font Locking:: Font Locking
* Folding:: Folding Macros and Environments
* Outline:: Outlining the Document
* Narrowing:: Restricting display and editing to a portion of the buffer
* Prettifying:: Displaying Greek and math macros as Unicode characters
Font Locking
* Fontification of macros:: Fontification of macros
* Fontification of quotes:: Fontification of quotes
* Fontification of math:: Fontification of math constructs
* Verbatim content:: Verbatim macros and environments
* Faces:: Faces used by font-latex
* Known problems:: Known fontification problems
Starting Processors, Viewers and Other Programs
* Commands:: Invoking external commands.
* Viewing:: Invoking external viewers.
* Debugging:: Debugging TeX and LaTeX output.
* Checking:: Checking the document.
* Control:: Controlling the processes.
* Cleaning:: Cleaning intermediate and output files.
* Documentation:: Documentation about macros and packages.
Viewing the Formatted Output
* Starting Viewers:: Starting viewers
* I/O Correlation:: Forward and inverse search
Catching the errors
* Ignoring warnings:: Controlling warnings to be reported
* Error overview:: List of all errors and warnings
Customization and Extension
* Multifile:: Multifile Documents
* Parsing Files:: Automatic Parsing of TeX Files
* Internationalization:: Language Support
* Automatic:: Automatic Customization
* Style Files:: Writing Your Own Style Support
Language Support
* European:: Using AUCTeX with European Languages
* Japanese:: Using AUCTeX with Japanese
Automatic Customization
* Automatic Global:: Automatic Customization for the Site
* Automatic Private:: Automatic Customization for a User
* Automatic Local:: Automatic Customization for a Directory
Writing Your Own Style Support
* Simple Style:: A Simple Style File
* Adding Macros:: Adding Support for Macros
* Adding Environments:: Adding Support for Environments
* Adding Other:: Adding or Examining Other Information
* Hacking the Parser:: Automatic Extraction of New Things
Copying, Changes, Development, FAQ
* Copying this Manual::
* Changes::
* Development::
* FAQ::
* Texinfo mode::
Copying this Manual
* GNU Free Documentation License:: License for copying this manual.
Indices
* Key Index::
* Function Index::
* Variable Index::
* Concept Index::
File: docerhJsA.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top
Copying
*******
AUCTeX primarily consists of Lisp files for Emacs, but there are also
installation scripts and files and TeX support files. All of those are
"free"; this means that everyone is free to use them and free to
redistribute them on a free basis. The files of AUCTeX are not in the
public domain; they are copyrighted and there are restrictions on their
distribution, but these restrictions are designed to permit everything
that a good cooperating citizen would want to do. What is not allowed
is to try to prevent others from further sharing any version of these
programs that they might get from you.
Specifically, we want to make sure that you have the right to give
away copies of the files that constitute AUCTeX, that you receive source
code or else can get it if you want it, that you can change these files
or use pieces of them in new free programs, and that you know you can do
these things.
To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights. For example, if you distribute
copies of parts of AUCTeX, you must give the recipients all the rights
that you have. You must make sure that they, too, receive or can get
the source code. And you must tell them their rights.
Also, for our own protection, we must make certain that everyone
finds out that there is no warranty for AUCTeX. If any parts are
modified by someone else and passed on, we want their recipients to know
that what they have is not what we distributed, so that any problems
introduced by others will not reflect on our reputation.
The precise conditions of the licenses for the files currently being
distributed as part of AUCTeX are found in the General Public Licenses
that accompany them. This manual specifically is covered by the GNU
Free Documentation License (*note Copying this Manual::).
File: docerhJsA.info, Node: Introduction, Next: Editing, Prev: Copying, Up: Top
1 Introduction
**************
* Menu:
* Summary:: Overview of AUCTeX
* Installation:: Installing AUCTeX
* Quick Start:: Quick Start
File: docerhJsA.info, Node: Summary, Next: Installation, Up: Introduction
1.1 Overview of AUCTeX
======================
AUCTeX is a comprehensive customizable integrated environment for
writing input files for TeX, LaTeX, ConTeXt, Texinfo, and docTeX using
Emacs.
It supports you in the insertion of macros, environments, and
sectioning commands by providing completion alternatives and prompting
for parameters. It automatically indents your text as you type it and
lets you format a whole file at once. The outlining and folding
facilities provide you with a focused and clean view of your text.
AUCTeX lets you process your source files by running TeX and related
tools (such as output filters, post processors for generating indices
and bibliographies, and viewers) from inside Emacs. AUCTeX lets you
browse through the errors TeX reported, while it moves the cursor
directly to the reported error, and displays some documentation for that
particular error. This will even work when the document is spread over
several files.
One component of AUCTeX that LaTeX users will find attractive is
preview-latex, a combination of folding and in-source previewing that
provides true "What You See Is What You Get" experience in your
sourcebuffer, while letting you retain full control.
More detailed information about the features and usage of AUCTeX can
be found in the remainder of this manual.
AUCTeX is written entirely in Emacs Lisp, and hence you can easily
add new features for your own needs. It is a GNU project and
distributed under the 'GNU General Public License Version 3'.
AUCTeX is a package distributed at ELPA, Emacs Lisp Package Archive.
You can manage it in Emacs package manager. (*note (emacs)Packages::)
WWW users may want to check out the AUCTeX page at
<https://www.gnu.org/software/auctex/> and
<https://elpa.gnu.org/packages/auctex.html>.
If you are considering upgrading AUCTeX, the recent changes are
described on the latter of the above WWW sites. You can see the same
change logs in 'NEWS.org' file available at your ELPA AUCTeX contents
directory, typically '~/.emacs.d/elpa/auctex-x.y.z/' where 'x.y.z' is
the version number of the installed AUCTeX.
If you want to discuss AUCTeX with other users or its developers,
there are several mailing lists you can use.
Send a mail with the subject "subscribe" to <auctex-request@gnu.org>
in order to join the general discussion list for AUCTeX. Articles
should be sent to <auctex@gnu.org>. In a similar way, you can subscribe
to the <info-auctex@gnu.org> list for just getting important
announcements about AUCTeX. The list <bug-auctex@gnu.org> is for bug
reports which you should usually file with the 'M-x
TeX-submit-bug-report <RET>' command. If you want to address the
developers of AUCTeX themselves with technical issues, they can be found
on the discussion list <auctex-devel@gnu.org>.
File: docerhJsA.info, Node: Installation, Next: Quick Start, Prev: Summary, Up: Introduction
1.2 Installing AUCTeX
=====================
AUCTeX is a package distributed at ELPA, Emacs Lisp Package Archive. To
install AUCTeX, simply do 'M-x list-packages <RET>', mark the auctex
package for installation with 'i', and hit 'x' to execute the
installation procedure. That's all.
Caution. If you have installed former AUCTeX as regular tarball
release, uninstall it and delete the initialization codes
(load "auctex.el" nil t t)
(load "preview-latex.el" nil t t)
in your init file. Otherwise you'll get into troubles.
'use-package' users can use this simple recipe in their
'user-init-file' which essentially does the same as the manual
installation explained above.
(use-package auctex
:ensure t)
For past ELPA releases, see
<https://elpa.gnu.org/packages/auctex.html>. Once the installation is
completed, you can skip the rest of this section and proceed to *note
Quick Start::.
* Menu:
* Prerequisites::
* Activating the package::
* Advice for package providers::
* Using AUCTeX from ELPA-devel::
* Using AUCTeX from local Git repo::
* Customizing::
File: docerhJsA.info, Node: Prerequisites, Next: Activating the package, Up: Installation
1.2.1 Prerequisites
-------------------
* GNU Emacs 28.1 or higher
Using preview-latex requires a version of Emacs compiled with image
support.
Windows
Precompiled versions are available from
<https://ftp.gnu.org/gnu/emacs/windows/>.
macOS
For an overview of precompiled versions of Emacs for macOS see
for example <https://www.emacswiki.org/emacs/EmacsForMacOS>.
GNU/Linux
Most GNU/Linux distributions nowadays provide a recent variant
of Emacs via their package repositories.
Self-compiled
Compiling Emacs yourself requires a C compiler and a number of
tools and development libraries. Details are beyond the scope
of this manual. Instructions for checking out the source code
can be found at <https://savannah.gnu.org/git/?group=emacs>.
* A working TeX installation
Well, AUCTeX would be pointless without that. preview-latex
requires Dvips or 'dvipng' for its operation in DVI mode. The
default configuration of AUCTeX is tailored for TeX Live-based
distributions, but can be adapted easily.
* A recent Ghostscript
This is needed for operation of preview-latex in both DVI and PDF
mode. Ghostscript version 7.07 or newer is required.
For some known issues with various software, see *note
(preview-latex)Known problems::.
File: docerhJsA.info, Node: Activating the package, Next: Advice for package providers, Prev: Prerequisites, Up: Installation
1.2.2 Activating the package
----------------------------
You can detect the successful activation of AUCTeX and preview-latex in
the menus after loading a LaTeX file like 'circ.tex': AUCTeX then gives
you a 'Command' menu, and preview-latex gives you a 'Preview' menu.
For site-wide activation in GNU Emacs, see *Note Advice for package
providers::.
Once activated, the modes provided by AUCTeX are used per default for
all supported file types, namely 'plain-tex-mode', 'latex-mode',
'doctex-mode' and 'texinfo-mode'. This might not match your preference.
You can have control over which AUCTeX mode is activated per file types
by 'TeX-modes' option. For example, you can use Emacs built-in
'plain-tex-mode' for plain TeX files while you can use AUCTeX
'LaTeX-mode' for LaTeX files.
-- User Option: TeX-modes
List of Emacs built-in TeX modes redirected to AUCTeX modes. If
you prefer a particular built-in mode over AUCTeX mode, remove it
from this list. Type
M-x customize-option <RET> TeX-modes <RET>
to manipulate the contents of 'TeX-modes'.
Don't remove 'tex-mode' from 'TeX-modes' unless you set 'TeX-modes'
empty to disable AUCTeX completely, otherwise it results in inconsistent
behavior.
On Emacs 29 and later, AUCTeX uses either 'major-mode-remap-defaults'
or 'major-mode-remap-alist' for redirection. But we recommend not to
customize them directly because the customization code for 'TeX-modes'
takes care of some other compatibility issues.
When there is a site-wide installation of AUCTeX and you don't want
to use it, you can disable it by
(push '(auctex nil) package-load-list)
in your early init file (*note (emacs)Early Init File::). (We recommend
this treatment over setting 'TeX-modes' to 'nil', because it doesn't
leave unused autoloads persisted.)
It is no longer possible to disable the site-wide installation by
(unload-feature 'tex-site)
, so don't use it. This was the instruction described in former
versions of this document, but now it causes error.
File: docerhJsA.info, Node: Advice for package providers, Next: Using AUCTeX from ELPA-devel, Prev: Activating the package, Up: Installation
1.2.3 Providing AUCTeX as a package
-----------------------------------
As a package provider, you should make sure that your users will be
served best according to their intentions, and keep in mind that a
system might be used by more than one user, with different preferences.
There are people that prefer the built-in Emacs modes for editing TeX
files, in particular plain TeX users. There are various ways to tell
AUCTeX even after auto-activation that it should not get used, and they
are described in the *note previous node: Activating the package.
So if you have users that don't want to use the preinstalled AUCTeX,
they can easily get rid of it. Installing AUCTeX as site-wide default
is therefore a good choice.
You can install ELPA AUCTeX package under a directory listed in
'package-directory-list' to have site-wide default.
File: docerhJsA.info, Node: Using AUCTeX from ELPA-devel, Next: Using AUCTeX from local Git repo, Prev: Advice for package providers, Up: Installation
1.2.4 Using AUCTeX from ELPA-devel
----------------------------------
It is possible to use the latest development version of AUCTeX
conveniently as a package installed from GNU-devel ELPA. This package
tracks the latest change in AUCTeX Git repository and is intended for
brave users who want to test the distribution and report possible
issues. The following addition to 'user-init-file' instructs Emacs to
change the archive AUCTeX is installed from:
(add-to-list 'package-archives
'("elpa-devel" . "https://elpa.gnu.org/devel/") t)
(setq package-archive-priority
'(("elpa" . 10)
("elpa-devel" . 5)))
(setq package-pinned-packages
'((auctex . "elpa-devel")))
In a nutshell, the code adds the new archive to the list of know
archives under the name 'elpa-devel', gives it a lower priority than the
regular archive, and instructs Emacs to fetch only AUCTeX from the new
archive and don't bother with other packages installed.
File: docerhJsA.info, Node: Using AUCTeX from local Git repo, Next: Customizing, Prev: Using AUCTeX from ELPA-devel, Up: Installation
1.2.5 Using AUCTeX from local Git repo
--------------------------------------
It is also possible to use AUCTeX directly from a local Git repository.
Let's assume you have your Git repositories under '~/development/'.
First, you have to fetch a copy of the AUCTeX Git repository. In a
shell, change directory to '~/development/' and do:
git clone https://git.savannah.gnu.org/git/auctex.git
Now change directory to '~/development/auctex' and run
make
Now you have to tell Emacs about the plan. Put the following code in
your init file:
(load "~/development/auctex/auctex-autoloads.el" nil t t)
(with-eval-after-load 'info
(add-to-list 'Info-additional-directory-list
"~/development/auctex/doc"))
and you're finished.
Note for 'use-package' users: you can wrap the above recipe with
'use-package' like this:
(use-package auctex
:init
(load "~/development/auctex/auctex-autoloads.el" nil t t)
(with-eval-after-load 'info
(add-to-list 'Info-additional-directory-list
"~/development/auctex/doc")))
File: docerhJsA.info, Node: Customizing, Prev: Using AUCTeX from local Git repo, Up: Installation
1.2.6 Customizing
-----------------
Most of the site-specific customization should already have happened
during installation of AUCTeX. Any further customization can be done
with customization buffers directly in Emacs. Just type 'M-x
customize-group <RET> AUCTeX <RET>' to open the customization group for
AUCTeX or use the menu entries provided in the mode menus. Editing the
file 'tex-site.el' as suggested in former versions of AUCTeX should not
be done anymore because the installation routine will overwrite those
changes.
You might check some options with a special significance. They are
accessible directly by typing 'M-x customize-option <RET> OPTION <RET>'.
-- User Option: TeX-macro-global
Directories containing the site's TeX style files.
Normally, AUCTeX will only allow you to complete macros and
environments which are built-in, specified in AUCTeX style files or
defined by yourself. If you issue the 'M-x
TeX-auto-generate-global' command after loading AUCTeX, you will be
able to complete on all macros available in the standard style
files used by your document. To do this, you must set this
variable to a list of directories where the standard style files
are located. The directories will be searched recursively, so
there is no reason to list subdirectories explicitly. Automatic
configuration will already have set the variable for you if it
could use the program 'kpsewhich'. In this case you normally don't
have to alter anything.
Note that 'TeX-auto-generate-global' is not so smart and it can
introduce unexpected side effects as discussed in
<https://lists.gnu.org/r/auctex/2021-01/msg00037.html>.
File: docerhJsA.info, Node: Quick Start, Prev: Installation, Up: Introduction
1.3 Quick Start
===============
AUCTeX is a powerful program offering many features and configuration
options. If you are new to AUCTeX this might be deterrent. Fortunately
you do not have to learn everything at once. This Quick Start Guide
will give you the knowledge of the most important commands and enable
you to prepare your first LaTeX document with AUCTeX after only a few
minutes of reading.
In this introduction, we assume that AUCTeX is already installed on
your system. If this is not the case, you should read the installation
instructions in this manual (*note Installation::). We also assume that
you are familiar with the way keystrokes are written in Emacs manuals.
If not, have a look at the Emacs Tutorial in the Help menu.
In order to get support for many of the LaTeX packages you will use
in your documents, you should enable document parsing as well, which can
be achieved by putting
(setq TeX-auto-save t)
(setq TeX-parse-self t)
into your init file. Finally, if you often use '\include' or '\input',
you should make AUCTeX aware of the multifile document structure. You
can do this by inserting
(setq-default TeX-master nil)
into your init file. Each time you open a new file, AUCTeX will then
ask you for a master file.
* Menu:
* Editing Facilities:: Functions for editing TeX files
* Processing Facilities:: Creating and viewing output, debugging
File: docerhJsA.info, Node: Editing Facilities, Next: Processing Facilities, Up: Quick Start
1.3.1 Functions for editing TeX files
-------------------------------------
1.3.1.1 Making your TeX code more readable
..........................................
AUCTeX can do syntax highlighting of your source code, that means
commands will get special colors or fonts. This is enabled by default.
You can disable it locally by typing 'M-x font-lock-mode <RET>'.
AUCTeX will indent new lines to indicate their syntactical
relationship to the surrounding text. For example, the text of a
'\footnote' or text inside of an environment will be indented relative
to the text around it. If the indenting has gotten wrong after adding
or deleting some characters, use <TAB> to reindent the line, 'M-q' for
the whole paragraph, or 'M-x LaTeX-fill-buffer <RET>' for the whole
buffer.
1.3.1.2 Entering sectioning commands
....................................
Insertion of sectioning macros, that is '\chapter', '\section',
'\subsection', etc. and accompanying '\label' commands may be eased by
using 'C-c C-s'. You will be asked for the section level. As nearly
everywhere in AUCTeX, you can use the <TAB> or <SPC> key to get a list
of available level names, and to auto-complete what you started typing.
Next, you will be asked for the printed title of the section, and last
you will be asked for a label to be associated with the section.
1.3.1.3 Inserting environments
..............................
Similarly, you can insert environments, that is '\begin{}'-'\end{}'
pairs: Type 'C-c C-e', and select an environment type. Again, you can
use <TAB> or <SPC> to get a list, and to complete what you type.
Actually, the list will not only provide standard LaTeX environments,
but also take your '\documentclass' and '\usepackage' commands into
account if you have parsing enabled by setting 'TeX-parse-self' to 't'.
If you use a couple of environments frequently, you can use the <up> and
<down> arrow keys (or 'M-p' and 'M-n') in the minibuffer to get back to
the previously inserted commands.
Some environments need additional arguments. Often, AUCTeX knows
about this and asks you to enter a value.
1.3.1.4 Inserting macros
........................
'C-c C-m', or simply 'C-c <RET>' will give you a prompt that asks you
for a LaTeX macro. You can use <TAB> for completion, or the <up>/<down>
arrow keys (or 'M-p' and 'M-n') to browse the command history. In many
cases, AUCTeX knows which arguments a macro needs and will ask you for
that. It even can differentiate between mandatory and optional
arguments--for details, see *note Completion::.
An additional help for inserting macros is provided by the
possibility to complete macros right in the buffer. With point at the
end of a partially written macro, you can complete it by typing
'M-<TAB>'.
1.3.1.5 Changing the font
.........................
AUCTeX provides convenient keyboard shortcuts for inserting macros which
specify the font to be used for typesetting certain parts of the text.
They start with 'C-c C-f', and the last 'C-' combination tells AUCTeX
which font you want:
'C-c C-f C-b'
Insert bold face '\textbf{-!-}' text.
'C-c C-f C-i'
Insert italics '\textit{-!-}' text.
'C-c C-f C-e'
Insert _emphasized_ '\emph{-!-}' text.
'C-c C-f C-s'
Insert slanted '\textsl{-!-}' text.
'C-c C-f C-r'
Insert roman '\textrm{-!-}' text.
'C-c C-f C-f'
Insert sans serif '\textsf{-!-}' text.
'C-c C-f C-t'
Insert typewriter '\texttt{-!-}' text.
'C-c C-f C-c'
Insert SMALL CAPS '\textsc{-!-}' text.
'C-c C-f C-d'
Delete the innermost font specification containing point.
If you want to change font attributes of existing text, mark it as an
active region, and then invoke the commands. If no region is selected,
the command will be inserted with empty braces, and you can start typing
the changed text.
Most of those commands will also work in math mode, but then macros
like '\mathbf' will be inserted.
1.3.1.6 Other useful features
.............................
AUCTeX also tries to help you when inserting the right "quote" signs for
your language, dollar signs to typeset math, or pairs of braces. It
offers shortcuts for commenting out text ('C-c ;' for the current region
or 'C-c %' for the paragraph you are in). The same keystrokes will
remove the % signs, if the region or paragraph is commented out yet.
With 'TeX-fold-mode', you can hide certain parts (like footnotes,
references etc.) that you do not edit currently. Support for Emacs'
outline mode is provided as well. And there's more, but this is beyond
the scope of this Quick Start Guide.
File: docerhJsA.info, Node: Processing Facilities, Prev: Editing Facilities, Up: Quick Start
1.3.2 Creating and viewing output, debugging
--------------------------------------------
1.3.2.1 One Command for LaTeX, helpers, viewers, and printing
.............................................................
If you have typed some text and want to run LaTeX (or TeX, or other
programs--see below) on it, type 'C-c C-c'. If applicable, you will be
asked whether you want to save changes, and which program you want to
invoke. In many cases, the choice that AUCTeX suggests will be just
what you want: first 'latex', then a viewer. If a 'latex' run produces
or changes input files for 'makeindex', the next suggestion will be to
run that program, and AUCTeX knows that you need to run 'latex' again
afterwards--the same holds for BibTeX.
When no processor invocation is necessary anymore, AUCTeX will
suggest to run a viewer, or you can chose to create a PostScript file
using 'dvips', or to directly print it.
Actually, there is another command which comes in handy to compile
documents: type 'C-c C-a' ('TeX-command-run-all') and AUCTeX will
compile the document for you until it is ready and then run the viewer.
This is the same as issuing repeatedly 'C-c C-c' and letting AUCTeX
guess the next command to run.
At this place, a warning needs to be given: First, although AUCTeX is
really good in detecting the standard situations when an additional
'latex' run is necessary, it cannot detect it always. Second, the
creation of PostScript files or direct printing currently only works
when your output file is a DVI file, not a PDF file.
Ah, you didn't know you can do both? That brings us to the next
topic.
1.3.2.2 Choosing an output format
.................................
From a LaTeX file, you can produce DVI output, or a PDF file directly
via 'pdflatex'. You can switch on source specials for easier navigation
in the output file, or tell 'latex' to stop after an error (usually
'--noninteractive' is used, to allow you to detect all errors in a
single run).
These options are controlled by toggles, the keystrokes should be
easy to memorize:
'C-c C-t C-p'
This command toggles between DVI and PDF output
'C-c C-t C-i'
toggles interactive mode
'C-c C-t C-s'
toggles SyncTeX (or source specials) support
'C-c C-t C-o'
toggles usage of Omega/lambda.
There is also another possibility: compile the document with 'tex'
(or 'latex') and then convert the resulting DVI file to PDF using
'dvips'-'ps2pdf' sequence or 'dvipdfmx' command. If you want to go by
this route, customize 'TeX-PDF-from-DVI' option. Then AUCTeX will
suggest you to run the appropriate command when you type 'C-C C-c'. For
details, see *note Processor Options::.
1.3.2.3 Debugging LaTeX
.......................
When AUCTeX runs a program, it creates an output buffer in which it
displays the output of the command. If there is a syntactical error in
your file, 'latex' will not complete successfully. AUCTeX will tell you
that, and you can get to the place where the first error occurred by
pressing 'C-c `' (the last character is a backtick). The view will be
split in two windows, the output will be displayed in the lower buffer,
and both buffers will be centered around the place where the error
occurred. You can then try to fix it in the document buffer, and use
the same keystrokes to get to the next error. This procedure may be
repeated until all errors have been dealt with. By pressing 'C-c C-w'
('TeX-toggle-debug-bad-boxes') you can toggle whether AUCTeX should
notify you of overfull and underfull boxes in addition to regular
errors.
Issue 'M-x TeX-error-overview <RET>' to see a nicely formatted list
of all errors and warnings reported by the compiler.
If a command got stuck in a seemingly infinite loop, or you want to
stop execution for other reasons, you can use 'C-c C-k' (for "kill").
Similar to 'C-l', which centers the buffer you are in around your
current position, 'C-c C-l' centers the output buffer so that the last
lines added at the bottom become visible.
1.3.2.4 Running LaTeX on parts of your document
...............................................
If you want to check how some part of your text looks like, and do not
want to wait until the whole document has been typeset, then mark it as
a region and use 'C-c C-r'. It behaves just like 'C-c C-c', but it only
uses the document preamble and the region you marked.
If you are using '\include' or '\input' to structure your document,
try 'C-c C-b' while you are editing one of the included files. It will
run 'latex' only on the current buffer, using the preamble from the
master file.
File: docerhJsA.info, Node: Editing, Next: Display, Prev: Introduction, Up: Top
2 Editing the Document Source
*****************************
The most commonly used commands/macros of AUCTeX are those which simply
insert templates for often used TeX, LaTeX, or ConTeXt constructs, like
font changes, handling of environments, etc. These features are very
simple, and easy to learn, and help you avoid mistakes like mismatched
braces, or '\begin{}'-'\end{}' pairs.
Apart from that this chapter contains a description of some features
for entering more specialized sorts of text, for formatting the source
by indenting and filling and for navigating through the document.
* Menu:
* Quotes:: Inserting quotes, dollars, and braces
* Font Specifiers:: Inserting Font Specifiers
* Sectioning:: Inserting chapters, sections, etc.
* Environments:: Inserting Environment Templates
* Mathematics:: Entering Mathematics
* Completion:: Completion of macros
* Marking:: Marking Environments, Sections, or Texinfo Nodes
* Commenting:: Commenting text
* Indenting:: Reflecting syntactic constructs with whitespace
* Filling:: Automatic and manual line breaking
File: docerhJsA.info, Node: Quotes, Next: Font Specifiers, Up: Editing
2.1 Insertion of Quotes, Dollars, and Braces
============================================
Quotation Marks
---------------
In TeX, literal double quotes '"like this"' are seldom used, instead two
single quotes are used '``like this'''. To help you insert these
efficiently, AUCTeX allows you to continue to press '"' to insert two
single quotes. To get a literal double quote, press '"' twice.
-- Command: TeX-insert-quote COUNT
('"') Insert the appropriate quote marks for TeX.
Inserts the value of 'TeX-open-quote' (normally '``') or
'TeX-close-quote' (normally '''') depending on the context. With
prefix argument, always inserts '"' characters.
-- User Option: TeX-open-quote
String inserted by typing '"' to open a quotation. (*Note
European::, for language-specific quotation mark insertion.)
-- User Option: TeX-close-quote
String inserted by typing '"' to close a quotation. (*Note
European::, for language-specific quotation mark insertion.)
-- User Option: TeX-quote-after-quote
Determines the behavior of '"'. If it is non-'nil', typing '"'
will insert a literal double quote. The respective values of
'TeX-open-quote' and 'TeX-close-quote' will be inserted after
typing '"' once again.
The 'babel' package provides special support for the requirements of
typesetting quotation marks in many different languages. If you use
this package, either directly or by loading a language-specific style
file, you should also use the special commands for quote insertion
instead of the standard quotes shown above. AUCTeX is able to recognize
several of these languages and will change quote insertion accordingly.
*Note European::, for details about this feature and how to control it.
In case you are using the 'csquotes' package, you should customize
'LaTeX-csquotes-open-quote', 'LaTeX-csquotes-close-quote' and
'LaTeX-csquotes-quote-after-quote'. The quotation characters will only
be used if both variables--'LaTeX-csquotes-open-quote' and
'LaTeX-csquotes-close-quote'--are non-empty strings. But then the
'csquotes'-related values will take precedence over the
language-specific ones.
Dollar Signs
------------
In AUCTeX, dollar signs should match like they do in TeX. This has been
partially implemented, we assume dollar signs always match within a
paragraph. By default, the first '$' you insert in a paragraph will do
nothing special. The second '$' will match the first. This will be
indicated by moving the cursor temporarily over the first dollar sign.
-- Command: TeX-insert-dollar ARG
('$') Insert dollar sign (or another math delimiter).
Show matching dollar sign if this dollar sign end the TeX math
mode.
With optional ARG, insert that many dollar signs.
TeX and LaTeX users often look for a way to insert inline equations
like '$...$' or '\(...\)' simply typing '$'. AUCTeX helps them through
the customizable variable 'TeX-electric-math'.
-- User Option: TeX-electric-math
If the variable is non-'nil' and you type '$' outside math mode,
AUCTeX will automatically insert the opening and closing symbols
for an inline equation and put the point between them. The opening
symbol will blink when 'blink-matching-paren' is non-'nil'. If
'TeX-electric-math' is 'nil', typing '$' simply inserts '$' at
point, this is the default.
Besides 'nil', possible values for this variable are '("$" . "$")'
for TeX inline equations '$...$', and '("\(" . "\)")' for LaTeX
inline equations '\(...\)'.
In addition, when the variable is non-'nil' and there is an active
region outside math mode, typing '$' will put around the active
region symbols for opening and closing inline equation and keep the
region active, leaving point after the closing symbol. By pressing
repeatedly '$' while the region is active you can toggle between an
inline equation, a display equation, and no equation. To be
precise, '$...$' is replaced by '$$...$$', whereas '\(...\)' is
replaced by '\[...\]'.
If you want to automatically insert '$...$' in plain TeX files, and
'\(...\)' in LaTeX files by pressing '$', add the following to your init
file
(add-hook 'plain-TeX-mode-hook
(lambda () (setq-local TeX-electric-math
(cons "$" "$"))))
(add-hook 'LaTeX-mode-hook
(lambda () (setq-local TeX-electric-math
(cons "\\(" "\\)"))))
Math mode which didn't start with dollar(s) shouldn't be closed with
dollar.
-- User Option: TeX-refuse-unmatched-dollar
This option _has no effect_ when 'TeX-electric-math' is non-'nil'.
This option determines the behavior when the user types '$' at a
position where AUCTeX thinks that it is in math mode which didn't
start with dollar(s).
When this option is 'nil', AUCTeX behaves in the same way as
non-math mode, assuming that the user knows it isn't in math mode
actually. This is the default.
When this option is non-'nil', AUCTeX refuses to insert '$' to
prevent unmatched dollar.
Note that Texinfo mode does nothing special for '$'. It inserts
dollar sign(s) just in the same way as the other normal keys do.
Braces
------
To avoid unbalanced braces, it is useful to insert them pairwise. You
can do this by typing 'C-c {'.
-- Command: TeX-insert-braces
('C-c {') Make a pair of braces and position the cursor to type
inside of them. If there is an active region, put braces around it
and leave point after the closing brace.
When writing complex math formulas in LaTeX documents, you sometimes
need to adjust the size of braces with pairs of macros like
'\left'-'\right', '\bigl'-'\bigr' and so on. You can avoid unbalanced
pairs with the help of 'TeX-insert-macro', bound to 'C-c C-m' or 'C-c
<RET>' (*note Completion::). If you insert left size adjusting macros
such as '\left', '\bigl' etc. with 'TeX-insert-macro', it asks for left
brace to use and supplies automatically right size adjusting macros such
as '\right', '\bigr' etc. and corresponding right brace in addition to
the intended left macro and left brace.
The completion by 'TeX-insert-macro' also applies when entering
macros such as '\langle', '\lfloor' and '\lceil', which produce the left
part of the paired braces. For example, inserting '\lfloor' by 'C-c
C-m' is immediately followed by the insertion of '\rfloor'. In
addition, if the point was located just after '\left' or its friends,
the corresponding '\right' etc. will be inserted in front of '\rfloor'.
In both cases, active region is honored.