AutoTeX is an utility program that automates routine works in editing a TeX document, such as TeX/BibTeX compilation, PDF conversion of DVI files etc. When AutoTeX detects a change in a source file, it executes a user defined procedure automatically. It is possible to float its transparent window on top of the desktop, you can check compilation results even if you are editing a source file in front. It is also possible to execute each command manually. Because it has functionality to open a TeX source, DVI, PDF, and BibTeX files, all works can be connected via AutoTeX.
You can use favorite application for each work (editing a source file, showing a DVI file etc.) because AutoTeX is not an integrated environment but a distributed environment. You can easily start a new document with a template or an existing document using AutoTeX. Creating a symbolic link is also very easy, so that you can place an alias of shared BibTeX database file in the same folder as the document (a symbolic link is similar to an alias made by Finder, but most of unix commands can not resolve an alias).
Main target of AutoTeX is supporting a TeX document editing, but it can customize almost all functionality. Therefore it can also support any kind of work using unix commands, per scripts etc.
It runs under MacOS X 10.3 (Panther) or later. 10.4 (Tiger) is recommended because it has not been fully tested under 10.3. It is an universal binary so that it runs optimally both on PowerPC and Intel Macs.
AutoTeX does not provide a TeX environment such as latex, bibtex commands. You need to get them elsewhere before using AutoTeX.
If you already have an TeX document, drag it onto the AutoTeX icon or choose it in an open dialog which appears when AutoTeX launches. The extension name of the document file should be .tex (case sensitive).
If you want to create a new document based on a template or an existing document, choose [File - New from Template] menu and the following dialog appears.
New document name and its location is assigned in the upper part of the dialog box. Extension name of the new document is set as same as a chosen template (.tex). A template is chosen in the lower part of the dialog box. Initially, no template is chosen, so that the template menu is grayed out and a red warning icon is shown at the left. Press [Append a Template File] to append a template file to the template menu. The contents of the template menu is saved and can be reused later (at most 10 files).
In addition to copying a template, you can do more things at the same time. If [Create an Alias of the Document Folder] is checked, an alias of the document folder is created in itself. The name of the alias is like (basename).folder, where (basename) is a base name of the document (a filename without extension). With this alias, you can open the document folder directly from AutoTeX window.
If [Create an Extra Folder in the Document Folder] is checked and a certain folder name is assigned in the field below, a folder is created in the document folder. It is useful if you always need a certain folder for figures etc. The name created is saved for later use, and you can choose from the menu.
If [Create a Symbolic Link] is checked, a symbolic link to a file selected in the below menu is created in the document folder. The base name of the link is the same as the document and the extension name is the same as an original file to link. As same as the template menu, you can add files to the symbolic link menu using [Append an Original File] button. For example, you can create a link to a BibTeX database file (.bib file), then you can open the database directly from AutoTeX window.
The figure below shows an example with full options.
An example of a document folder contents is shown below. As shown below, a symbolic link and an alias is identical in Finder view, however, these are treated completely different in the system level. So that most of unix commands can handle only symbolic links but not aliases.
An example of a new document window is shown below. The document window has three parts, a status part at the top, a log part (white area at the middle), and a button part at the bottom.
At the top of the status part, executing/executed unix command is shown. [Run] button at the right is a button to run an automatic sequence manually. This button changes to a [Stop] button when a command is running. By default, the automatic sequence is set to run the latex command once. The sequence is a set of 10 commands explained below and can be customized in the preferences setting. The lower half of the status part shows number of errors and processed pages. Errors are classified into severe errors, warnings and notes.
In the log part, output log text of running commands are shown. Errors are colored and you can check error messages here. The log text can be selected and copied but not edited.
The upper half of the button part has 10 buttons to run respective function. 5 upper buttons correspond to unix commands and the lower 5 is used to open corresponding file. Buttons whose target file is absent are disabled (grayed out). Details of these 10 buttons are explained below.
In addition to the 10 buttons, there are one button and a checkbox at the bottom. [Clear All Output Files] button removes all output files generated by compilation processes. By default, files whose extension name are one of aux, log, bbl, blg, dvi, dep, toc, pdf, ps, are deleted. The list of extensions can be customized in the preferences. [Check Modification of the Source File] checkbox enables/disables the source modification check. If it is checked, AutoTeX checks whether the source file is modified or not in every 2 seconds and execute the auto sequence if it is modified. You can temporary turn off this functionality. The check state is not saved, so that this is always checked when you open the window.
The followings are detailed explanations of 10 buttons in the button part. Each button has a predefined extension name of file to operate. The base name of the target file should be the same as the source file (i.g. if a source file is “abstract.tex” and a button target extension is ‘bib’, the button works with “abstract.bib” file). Refer to respective command help for functions and option parameters of the command. All buttons can customize freely with the preferences.
Since AutoTeX does not provide a text editing feature, you need to edit a source document with your favorite text editor. You can open the source file from Finder but also clicking on the [Edit TeX] button at the bottom left of the AutoTeX document window opens it. When you open the source with a text editor, AutoTeX becomes a background application and its window changes to transparent mini window with only the status part as shown below. This transparent mini window always floats on top of the desktop.
When the mouse cursor moves into the transparent mini window, the window expands to the original size while it stays background. As the mouse moves out, the window shrinks as before. Using this function, you can check the output log without switching applications. You can choose window behavior on background in the preferences setting.
When you overwrite the source file, AutoTeX detects the modification and runs the auto sequence. During compilation process, the mini window expands to show the log part as shown below, and it returns to the status size after the process. By default, the auto sequence execute the latex command once, you can customize it in the preferences.
The figure below shows an example of a document window after TeX compilation. At the top, executed command was shown, and number of errors and processed pages are shown at the next. A green line in the log means a warning and a blue line is a note. A severe error is in red (not shown here). A severe error is an error that the process could not be continued (such as a command syntax error). A warning is an error that can continue processing but the result may be incorrect (such as an unresolved reference). A note is an error or notice that the result is essentially correct but its appearance my not the best (such as an overflown line).
After the compilation, a DVI file is generated and related buttons becomes enabled. Click on [View DVI] to show the result.
You can also run the auto sequence by pressing [Run] button on the status part. You can also execute each command with a button in the button part.
Using the [File - Create a Symbolic Link] menu, you can create a symbolic link of any kind of file. When you choose the menu, the following sheet appears.
As same as creating a new document using a template, choose an original file to link from the menu and put a link name in the upper field. You can append a file to the menu using the [Append an Original File] button. An extension name for the link is the same as its original file, however, if you choose a folder as an original, .folder is used as an extension.
When you choose [AutoTeX - Preferences] menu, the following window appears.
This section defines command buttons (5 upper buttons in the button part of a window). Name is a name of a button, Extension is a corresponding file extension which is needed to execute a following command. Command Syntax defines a UNIX command line to execute. Here, ‘%1’ will be replaced by a base name of an opened document (for example, if you opened a file named ‘HelloWorld.tex’, ‘%1’ is ‘HelloWorld’). On execution, current directory is set to that include the opened document. All commands should have full paths such as “/usr/local/bin/command”. Commands with pipes and redirections (‘ | ’ and/or ‘>’, ‘<’) does not work.
This section defines open buttons (5 lower buttons in the button part of a window). Name is a name of a button, Extension is an extension of a file to be opened. Base name of the file is identical to that of an opened document.
This section defines an automatic procedure that is executed when an opened document was modified. You can choose up to 8 steps of commands and/or open functions in any order. By default, only the first step sets to execute latex command. For example, setting as
Check Interval is a time interval of a source file modification check.
This section defines file extensions which can be generated during compilation processes. Any files that has the same base name as an opened document with those extensions will be deleted when you press [Clear All Output Files]. Unused field should be blank.
You can choose an action when AutoTeX application launches. Do Nothing does nothing upon startup, Open Dialog opens a dialog to choose a document, Open Last opens the last opened document. If the last document could not be found, an open dialog will be displayed.
Here you can choose whether AutoTeX checks errors and pages in a log text or not. Check Errors checks a number of severe errors during a process, Check Warnings checks a number of warnings that is not severe but an output may not correct. Check Notes checks a number of cautions that may or may not affects an output. Check Pages checks currently processed page number. All of errors/warnings etc. definitions can be edited by clicking on the button [Edit Error Strings] which will be explained later.
Log Encoding selects a text encoding system (such as Unicode, ASCII, Japanese Shift-JIS etc.) of log text. LaTeX compilation for european languages, “Western (ASCII)” may work well. For Japanese and other languages, choose appropriate encoding for the language.
Window behavior when AutoTeX moves to background is defined here. If Floating is checked, the front most AutoTeX document window always floats in front of the other windows (the other AutoTeX windows stays as usual). If it is not checked, all window hides behind other windows as usual. When floating mode in turned on, window contents menu and transparency slider accepts changes.
If All Contents is chosen in the menu, whole window contents are displayed in the floating window. Status & Log hides only the button part of the window. Log on Running shows only the status part in the normal state, the log part appears during auto procedure is running. Status Only always shows only the status part of the window.
Transparency slider sets transparency of the floating window. The left edge of the slider corresponds to complete opaque state.
When AutoTeX window is floating in front and the mouse cursor goes onto the window area, AutoTeX automatically expands its window to the original size. At present, you can not turn off this function via preferences settings. If you want to do by any means, see Risky Tips section.
If you click on this button, all settings are revert to the factory settings, which depends on the MacOS X language environment.
[Edit Error Strings] button opens a setting sheet with four tabs below.
A log line starts with one of these strings is treated as a severe error line. To edit a string, double click on it. To remove a string, just put an empty string. To add a new string, double click on a space just below the last line. String order is automatically sorted when saving. Log Text Color is a color used to display a line contains a severe error in the log text.
A log line starts with one of these strings is treated as a warning line. To edit a string, double click on it. To remove a string, just put an empty string. To add a new string, double click on a space just below the last line. String order is automatically sorted when saving. Log Text Color is a color used to display a line contains a warning in the log text.
A log line starts with one of these strings is treated as a note line. To edit a string, double click on it. To remove a string, just put an empty string. To add a new string, double click on a space just below the last line. String order is automatically sorted when saving. Log Text Color is a color used to display a line contains a note in the log text.
You can define processing page format in this page for respective commands. ‘%n’ in a string is treated as a decimal number that correcponds to a page number in progress. If the string is “[%n]”, “[12]” in a line is treated as a page number 12. If the string is “[%n”, any of “[12]”, “[12(”, “[12x” in a line is treated as a page number 12. If the same format appeared multiply in one line, the last value is used. Leave it empty if corresponding command does not need page checking.
All tips shown here changes AutoTeX internal functionality. You should quit AutoTeX before modification. These modification only applies to the user who do the work.
All modification use a unix command ‘defaults’ via Terminal application. It can affects not only AutoTeX but other applications or the operating system if you make a mistake. Even an extra space or lack of a letter causes a severe problem, it is recommended to copy & paste a colored command line below onto the Terminal window. Be sure that the author will NOT take responsibility for any kind of damage to your system or loss of your data resulted by the following operation.
These tricks take effects even if you do [Revert to Default] in the preferences setting. If you really want to revert everything, remove a file “Home/Library/Preferences/com.hit-c.AutoTeX.plist”.