Alpha-TeX Typesetting Help
| Name: | Alpha-TeX |
| Version: | 6.2 |
| Last update: | 2019-12-12 16:14:38 |
Introduction
Welcome to Alpha's TeX Mode for editing (La)TeX files and for
interacting with tex and related programs.
Alpha enters TeX Mode when opening a document with an appropriate
extension such as .tex. For an editable list of the file extensions
that will cause Alpha to enter TeX Mode see the Typesetting section
of TeX Mode Preferences. Click here to display the TeX Mode Preferences.
Alternatively, the active window can be put into TeX Mode by
selecting TeX Mode from the popup menu of modes on the left-hand
side of the window toolbar.
Editing TeX Documents
For editing, TeX Mode provides facilities for syntax and keyword
colouring, command completion, comment manipulation, menu items and
keyboard equivalents for almost all commands and environments, as well
as user defined templates, automatic marking of tex documents and many
other navigation facilities. Menus and keyboard shortcuts are user
configurable. See the options available in the
LaTeX Menu ↣ LaTeX Menu Options submenu.
For detailed information about the facilities for editing tex
documents, see the LaTeX Mode User's Guide, which is available as a pdf document.
There are a number of additional Alpha packages which enhance the use
of LaTeX mode (click to read more about them):
You may wish to activate these via Alpha ↣ TeX Mode Prefs ↣ Features (click here)
and test some of these to see whether you'd find them useful.
Finally, be sure to check out the Completions tutorial,
TeX Mode Tutorial.
Interaction with tex
For interaction with tex programs, TeX Mode provides its own interface
to any standard unix tex installation, and also allows interaction
with external integrated tex frontends like TeXShop.
Alpha's built-in interface to tex and friends is referred to as
Alpha-TeX. The main element in this interface is the TeX Console:
it is a small window that pops up when you do Typeset (⌘T),
in which the messages from tex roll down, and you can interact with it
like in standard command-line tex. The TeX Console has many other
features which are described in this document. Only when it comes
to viewing do you leave Alpha, which automatically launches a pdf
viewer to display the pdf produced by tex.
Alpha-TeX assumes that you already have tex installed on your system.
The recommended way to install tex is via the MacTeX distribution from TUG:
http://www.tug.org/mactex/.
You also need a pdf viewer. Although in principle Preview or Acrobat Reader
work, they are not the most convenient, as they do not support automatically
refreshing the view when the tex document is recompiled, and they do not
support synchronisation either. One recommended pdf viewer (which comes with
preset configuration for synchronisation with Alpha) is Skim:
http://skim-app.sourceforge.net/.
Finally, as an alternative to the Alpha-TeX interface, Alpha can act
as an external editor for integrated TeX environments like TeXShop or the
venerable OzTeX. In the TeX pane of Alpha ↣ Global Setup ↣ Helper Applications, you can choose such an implementation
for Typeset. Interaction with such external typesetting
environments may involve further settings: see
QA #8: How to use Alpha as an external text editor ?.
Typesetting
The subsections
Viewing,
Synchronisation and
Typeset selection
below are not specific to Alpha-TeX, but work also for external frontends.
Format/command selection
The Alpha-TeX interface is unaffected by the particular settings of the TeX
Program and TeX Format preferences, being more concerned with what you
would write in a command-line environment (where for example typically a
command latex exists as a convenient shortcut for invoking tex with the
latex format).
If no other indications are found, Alpha-TeX will run pdflatex by
default. You can change this setting via the prefs variable Default
Command in the TeX preference pane (found in Alpha ↣ TeX Mode Prefs, in the Typesetting section). The
default setting is overridden on a document-by-document basis by magic
first lines in the TeX source file. This means that a first line like
%&latex
instructs Alpha-TeX to use latex. Other typical instructions are %&plain, %&pdflatex, and so on. In the TeX Preference Pane, you
can also turn on a semi-heuristic Guess Format From Log mechanism.
More fine-grained control over the tex invocation can be achieved
through the prefs variable Additional TeX Flags. A typical use of
this variable is to specify
--shell-escape
in order to allow for example on-the-fly conversion of eps files to
pdf using pstricks. Another interesting flag to specify is
--interaction nonstopmode
which is particularly useful in view of Alpha-TeX's error browser
facility, cf. below.
Two common flags, --src-special and --synctex=1 can
alternatively be specified by ticking the corresponding checkboxes, still
in the TeX Preference Pane under Typesetting. (It should be noted
that these two checkboxes will be ignored if there are explicit Additional TeX Flags specified.)
Error browsing
If there is an error during the tex run, tex gives a question mark prompt
and then you can type one of the following letters (precisely the same as
work in any command-line tex)
| Key | Description |
Return | try to continue |
e | edit the source document where the error occurs |
q | enter batch mode |
and many others. See the tex manual page for a
complete list. In addition, the standard Macintosh keyboard shortcut Command-. will interrupt the tex run.
When the tex run has finished, you are given various options in the
TeX Console, among which:
[V]iew the resulting dvi/pdf file: Control-v (or just v)
see list of errors and [W]arnings: Control-w (or just w)
After the tex run, if there were errors, Control-W brings up a list
of all errors and warnings (inside the TeX Console) from where you can jump
to the appropriate line in the source file by pressing return when the
error is selected in the list.
Next action
When the tex run finishes, there is a smart mechanism which figures out
what is the most likely next action the user will take (this is done by
parsing the log file). This next action could be error browsing (if
there were errors), viewing (if no errors occurred), running bibtex (in
case of an undefined cite reference), and so on. This next action is
dynamically bound to <space> in the TeX Console, so in normal operation,
running tex and viewing becomes a matter of slapping the space bar.
The TeX Console has support for several degrees of automatisation of
Next Action, controlled by the autoView whose values can be for
example no automatisation, autoViewWhenNoErrors (default),
or autoNextAction. The latter means for example that tex runs
several times until all references are resolved, and then the viewer is
invoked in the end.
Each next action is associated with a letter as follows:
| Action | Letter |
| view | v |
| typeset | t |
| error-browse | w |
| bibtex | b |
| makeindex | m |
| view log file | l |
After a tex run (or a bibtex run, or whatever) you can invoke a specific
next action by pressing its associated letter (no modifier key is needed,
but ⌃letter works too). Such a letter can also be
pressed while tex is running to force a specific action immediately after
the tex run finishes. This can be used as an alternative to AutoNextAction, or it can be used to override the automatic mechanism.
For example, if AutoNextAction is set, and if you want to view
immediately after the tex run, independently of missing bibs or changing
label, press 'v' while tex is running. (These features are inspired by
OzTeX.)
Below is a complete list of keyboard shortcuts associated with the TeX
Console:
| Combo | Description |
| ctrl-B | Run BibTeX |
| ctrl-shift-D | Select DVI viewer |
| ctrl-D | View .dvi file |
| ctrl-E | Edit Source file |
| shift-cmd-E | Obtain unix prompt |
| ctrl-L | View .log file |
| ctrl-M | Run Makeindex |
| ctrl-shift-P | Select PDF viewer |
| ctrl-P | View PDF |
| ctrl-T | Typeset |
| cmd-T | Typeset |
| ctrl-U | Obtain unix prompt |
| ctrl-shift-V | Select PDF viewer |
| ctrl-V | View current |
| ctrl-W | Display errors and warnings |
Viewing
A crucial point of the interface is of course where the viewer is invoked.
Which viewer is invoked depends on your choice of DVI viewer and PDF
viewer, which can be set in the Helper Applications dialog: Alpha ↣ Global Settings ↣ Helper Applications.
You can also access these settings in the Viewing section of
the TeX Mode Preferences. Finally, you can choose viewer on the fly
at invocation time, doing ⌃S ⇧V instead of just
⌃V in the TeX Console: this brings up a listpick
dialogue for choosing a viewer.
The choice between DVI viewer and PDF viewer is made automatically
according to the newest output file (dvi or pdf), hence ultimately it
depends on the tex engine, whose choice you control via magic first lines
or via your Default Command setting, as explained below. If in some
situation the automatic dvi/pdf viewing choice is not what you wanted, for
example in debugging situations, you can also specifically request to see
dvi or pdf output, using the shortcuts ⌃D and ⌃P respectively.
Synchronisation
Synchronisation (i.e. reverse and forward navigation between source file
and previewer window) is supported in various incarnations: recommended as
of MacTeX-2008 is the synctex technology which is now an integrated part of
tex itself. Among the previewers that support it is Skim, which also sports a preset
for specifying Alpha as sync partner.
Older sync technologies should still work, though. Dvi src-specials
can be enabled by checking a box in the TeX prefs. For pdfsync (deprecated
precursor to synctex), you need to use the pdfsync.sty file.
To tell the viewer that Alpha is the editor to invoke, you should
give it the string
/Applications/Alpha.app/Contents/Resources/alphac +%d %s
at the appropriate place in its settings (assuming that Alpha is in
the Applications folder, of course). (In TeXniscope 0.3.4 or newer,
this is split into two preference variables: as Editor command choose
/Applications/Alpha.app/Contents/Resources/alphac
and as Editor arguments choose
+%line "%file"
not +%d %s (see TeXniscope's documentation).)
Typeset selection
With the Typeset Selection command (in the Process submenu of the
TeX Menu; shortcut ⇧⌘T), you can typeset only the
current selection, and view the result. This feature can be useful to fine
tune a complicated diagram or drawing. This works using temporary files
behind the scenes, but everything works transparently: viewing, error
navigation, synchronisation automatically relates to the original source
file.
Alpha-TeX specific preferences
All preference flags are set in the TeX Mode preference pane, most easily
accessed when a tex document is frontmost by choosing Alpha ↣ TeX Mode Prefs ↣ Preferences (usually just F12). The
Alpha-TeX specific prefs are in the Typesetting section or in the
Viewing section. Click here to display the TeX Mode Preferences.
An important setting is Default Command. This may be pdflatex, but you might rather want latex. This is the command
that will be used to typeset all documents that do not have a magic first
line.
There are also pop-up menus for chosing PDF and DVI viewers. These
popups are aliases to the general helper settings.
Some other settings include:
- Auto Save On Typeset
- If checked, will automatically save the document before running tex. If
unchecked, you'll be asked if you want to save.
- Send Console To Back While Viewing
- This does what you would expect from the name. The reason for wanting this
is that after viewing, when you come back to Alpha, what you want is much
more likely to edit the source file than to see the TeX Console.
- Guess Document Root From Log
- If this flag is set, there is a mechanism that will try to guess which is the
document root. Typically this is just the frontmost file itself, in which
case the flag has no effect. If the frontmost window is part of a tex
fileset, the tex fileset info is respected independent of the guess flag.
Otherwise the guessing works by scanning log files; it is very accurate and
goes so far as to also scan tex files in order to give a correct result. If
no information is found, just use the calling file like all other tex
implementations do. (In rare cases where the calling file is part of two
different projects, the user will be asked to choose.) All this is also very
fast: it is unnoticeable in usual operation, and for complicated situations
it takes a fraction of a second. You should be warned that this is only a
heuristic helper that can sometimes be confused if your tex run fails and
produces an incomplete log file. It is always preferred to create a tex
fileset.
- Guess Format From Log
- If this flag is set, there is a mechanism that guesses which format or
command should be used for this tex job. It works also by log file scanning.
Again this is just a hack that may be useful in some situations, but it can
also be very annoying in extreme cases where suddenly you are trapped in a
deceitful log file. Use this flag with caution. In any case it is
recommended to use magic-first-lines as explained above. These always take
precedence over guess work (and indeed take precedence over everything.)
Some more advanced scenarios
Alpha-TeX allows many expert settings and fine tunings that are not
accessible from the prefs pane. The power user is referred to the Tcl tetexComm.tcl (found in the Latex Mode folder) which
contains detailed technical comments and instructions on expert settings.
Then to change some setting, copy it from the file and write it in your prefs.tcl file. Here are some examples and scenarios
(explaining in particular the notion of override commands):
- You realise that error-browsing is far more efficient than running tex
again and again, once for each error. Then you can take the consequence and
write this line in your TeXPrefs.tcl file (via the
Alpha ↣ TeX Mode Prefs ↣ Edit Prefs File menu
item when a tex document is frontmost):
set TeX::tetexComm::overrideCommands(latex) "latex --interaction nonstopmode"
This will instruct Alpha-TeX always to run latex in nonstopmode,
and if there are errors, <space> will be bound to error-browse, and this
will now be the preferred interface to correcting errors (and you might
furthermore set the prefs variable AutoView equal to AutoNextAction, which will automatically go to error browsing when
there are errors.
The raison-d'être for the override facility compared to specifying
Additional TeX Flags is that you can specify them on a
command-by-command basis. For example, if you want to run simpdftex, you
will need to specify several flags in another syntax than tex accepts, and
it would be inconvenient to have these flags specified in the general
Additional TeX Flags, since they make no sense for real tex commands.
- You like the crisp display of a pdf viewer (native graphics format in
Mac OS X), but your files use eps graphics or ps rotates,
so they don't work with pdflatex. One choice is then to use Gerben Wierda's
simpdftex script (formerly altpdftex) which is a wrapper for
tex-dvips-ghostscript. Using this as magic line or Default Command will
always produce pdf, and hence your pdf viewer will be invoked.
A typical simpdftex invocation may look like this:
simpdftex latex --extratexopts "--synctex=1" <NAMEOFFILE>
so it would make sense to have an override specification like
set TeX::tetexComm::overrideCommands(simpdftex) \
"simpdftex latex --extratexopts \"--synctex=1\""
(note the required escaping of quotes). (If no overriding of simpdftex
is specified, Alpha-TeX will default to appending latex to the command,
and also "--extratexopts \"--synctex=1\"" if the Use Synctex flag is
checked.)
- But there is an alternative to simpdftex which is meant to be
better: stick with
%&latex in the magic line and latex as default
command, but choose a pdf viewer as dvi viewer: this is the menu item
called usingPDFViewer in the DVIViewer popup menu. This instructs
Alpha-TeX to run dvips and ghostscript behind the scenes to
produce a pdf for the viewer. The advantage over simpdftex is that
you only run dvips and ghostscript when you are about to
actually view the result, not if you are going to correct and error or edit
further. (With simpdftex, you are forced to go through the whole
sequence of programs latex-dvips-ghostscript each time you typeset.)
Another approach, if the problem is eps graphics, is to use the epstopdf
package (pdftricks) to convert eps graphics to pdf on the fly. In that
case you need to enable shell-escapes, so you'll write this in your
prefs.tcl file (for example):
set Tex::tetexComm::overrideCommands(pdftex) "pdftex --shell-escape"
Note: As of the 2010 release of TeXLive (and, as a consequence,
MacTeX) pdf(la)tex now automatically converts a requested eps figure to
pdf, via the epstopdf package, when and if the latex graphics.cfg configuration file is loaded, and pdf is being output. The
default options are intended to eliminate any risk of hand-created pdf
files being overwritten, but you can also prevent epstopdf from
being loaded at all by putting \newcommand{\DoNotLoadEpstopdf}{}
(or \def...) before the \documentclass declaration. It is also not
loaded if the pst-pdf package is used. For more details, see the epstopdf package documentation http://ctan.org/pkg/epstopdf-pkg.
- xdvi is a very powerful dvi viewer (needs X11 running). You can
completely control it from within Alpha by writing a custom xdvi command:
set TeX::tetexComm::xdviCommand [list xdvi -display :0.0 \
-geometry 1028x768 -s 5 -expert +statusline -hushstdout \
-editor "[file norm [file join $HOME Tools alphac]] +%l %f"]
Here -geometry 1028x768 is a full screen of some portable
computers, -s 5 is shrink factor 5, which corresponds to filling
that full screen, -expert means no buttons, +statusline
-hushstdout means no statusline and no messages... Another approach is
to write all these settings in your xdvi.cfg file --- see the
xdvi manual page for all details.
- Occasionally it is practical to run some unix command between tex
runs, for debugging purposes, or to move some file.
⌘S ⇧E inserts a prompt in the TeX Console, from which you can issue any
unix command (the pwd will be that of the previous tex job). This can be
very useful to send a quick query like 'ls -l' or 'kpsewhich
diagrams.sty', or to run some exceptional tex command like 'etex
--initex "&latex" someFile'. Once such a command is running it behaves
like any other tex run in the TeX Console. (In a sense such custom commands
have been supported all the time, except that you had to issue them from
the AlphaTcl shell, since there was no other prompt to send them from...)
- While tex is running in the TeX Console (and has not given you an
error prompt) you can type 'v' to instruct Alpha-TeX to procede directly to
viewing as soon as the tex run has finished, or type 't' to force an extra
tex run. You can also type <space> to instruct Alpha-TeX automatically to
take the Next Action (similarly to what happens if the NextAction
variable is set to AutoNextAction). This functionality is inspired
by OzTeX.
Known problems
Please report any problem or bug you encounter to
Alpha's Bug Tracker.
License and Disclaimer
TeX Mode was written mainly by Richard Austin, Tom Scavo, Vince Darley,
Frédéric Boulanger, and Joachim Kock, but with numerous contributions from
the Alpha community. See the document TeX Mode Version History for details.
This document was written by Chris Skeels, based on the document
'teTeX Help' by Joachim Kock.
This document has been placed in the public domain.
Copyright (c) 1992-2019, the Alpha Community.
All rights reserved.
The TeX package is free software and distributed under
the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
- Neither the name of the Alpha Community nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ALPHA COMMUNITY BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.