AutoTeX

AutoTeX for MacOS X

Table of contents

  1. Brief introduction
  2. Required system
  3. How to use AutoTeX
  4. Preferences settings
  5. Version history
  6. Tips and known problems

1. Brief introduction

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.

2. Required system

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.

3. How to use AutoTeX

3.1 Open a TeX document

3.1.1 Open an existing TeX document

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).

3.1.2 Create a new document using a template or an existing document

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.

Template1.png

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.

Template2.png

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.

DocFolder.png

3.2 A document window

3.2.1 Outline of a document window

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.

Initial.png

3.2.2 Details of a button part (default setting)

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.

[LaTeX] (Target Extension: tex)
Executes the latex command with ‘-src-specials’ option. The latex command should be placed in /usr/local/bin/ directory.
[BibTeX] (Target Extension: aux)
Executes the bibtex command. The bibtex command should be placed in /usr/local/bin/ directory. The latex command should be executed before this operation to generate an .aux file.
[DVI->PDF] (Target Extension: dvi)
Executes the dvipdfmx command. The dvipdfmx command should be placed in /usr/local/bin/ directory. The latex command should be executed before this operation to generate a .dvi file. The gs (ghost script) command should also be placed in the default binary path when the source file includes a graphics. If an error of missing gs occurs, create a symbolic link of /usr/local/bin/gs in /usr/bin/ directory.
[DVI->PS] (Target Extension:dvi)
Executes the dvips command with ‘-D 600’ option. The dvips command should be placed in /usr/local/bin/ directory. The latex command should be executed before this operation to generate a .dvi file. The gs (ghost script) command should also be placed in the default binary path when the source file includes a graphics. If an error of missing gs occurs, create a symbolic link of /usr/local/bin/gs in /usr/bin/ directory.
[Folder List] (Target Extension: None)
Executes the ls command with ‘-lb’ option.
[Edit TeX] (Target Extension: tex)
Opens a file with extension .tex with its default application (usually a text editor which creates the source file).
[View DVI] (Target Extension: dvi)
Opens a file with extension .dvi with its default application. You need to install DVI viewer application such as Mxdvi to open a DVI file.
[View PDF] (Target Extension: pdf)
Opens a file with extension .pdf with its default application (Preview application by default).
[Open Folder] (Target Extension: folder)
Opens an alias of a folder of which extension name is .folder. It is useful if you put an alias of the document folder with a name of “(basename).folder”, here (basename) is a base name of the document.
[Edit Bib] (Target Extension: bib)
Opens a file with extension .bib with its default application (usually a text editor which creates the database file). For BibTeX database editing, BibCompanion, which is also my work, may be a great help for you.

3.3 Basic operation

3.3.1 Edit a TeX document

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.

Status.png

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.

3.3.2 Auto compilation

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.

StatusLog.png

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).

Compiled.png

After the compilation, a DVI file is generated and related buttons becomes enabled. Click on [View DVI] to show the result.

3.3.3 Manual compilation

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.

3.4 Creating a symbolic link

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.

SymbolicLink.png

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.

4. Preferences settings

When you choose [AutoTeX - Preferences] menu, the following window appears.

Settings.png

4.1 Command Buttons

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.

4.2 Open Buttons

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.

4.3 Auto Procedure

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

[LaTeX] - [DVI->PDF] - [View PDF]
compiles a source and converts/shows a PDF file at a time.
[LaTeX] - [BibTeX] - [LaTeX] - [LaTeX] - [View DVI]
can compile and resolute cross references with BibTeX automatically.

Check Interval is a time interval of a source file modification check.

4.4 Output File Extension List

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.

4.5 On Startup

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.

4.6 Log Error Check/Encoding

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.

4.7 Window Behavior on Background

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.

4.8 [Revert to Defaults] button

If you click on this button, all settings are revert to the factory settings, which depends on the MacOS X language environment.

4.9 Edit Error Strings

[Edit Error Strings] button opens a setting sheet with four tabs below.

4.9.1 Severe Errors

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.

Errors.png

4.9.2 Warnings

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.

Warnings.png

4.9.3 Notes

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.

Notes.png

4.9.4 Pages

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.

Pages.png

5. Version history

6. Tips and known problems

6.1 Useful (risky?) tips

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”.

* Disable a function that a transparent floating window expands automatically when the mouse cursor moves into the window area.
Execute the following command in the Terminal;
defaults write com.hit-c.AutoTeX "Auto Expand Floating Window" -bool false
To enable the function, change the last ‘false’ to ‘true’.
* Suppress showing a button area when a transparent floating window expands automatically.
Execute the following command in the Terminal;
defaults write com.hit-c.AutoTeX "Auto Expand Floating Contents" -integer 1
Change the last ‘1’ to ‘0’ to show whole window contents. Do not set a value other than 0 and 1.
* Change display time of a log part after compilation process when [Log on Running] is set.
For example to set this time to 5 seconds, execute the following command in the Terminal;
defaults write com.hit-c.AutoTeX "Log Display Time" -float 5
A fractional number is also acceptable, however, too short time such as 1 second causes a problem when multiple step procedure is running. Never set a number less than or equal to 0. Set 2 seconds to change to the default value.
* Clear the template file list.
Execute the following command in the Terminal;
defaults delete com.hit-c.AutoTeX "Recent Templates"
There is no way to restore deleted list.
* Clear the symbolic link original list.
Execute the following command in the Terminal;
defaults delete com.hit-c.AutoTeX "Recent Symbolic Links"
There is no way to restore deleted list.
* Clear the extra folder name list.
Execute the following command in the Terminal;
defaults delete com.hit-c.AutoTeX "Recent Folder Names"
The default value “figures” remains by this method. To remove all strings including “figures”, execute;
defaults write com.hit-c.AutoTeX "Recent Folder Names" '()'
There is no way to restore deleted list in both cases.
* Change maximum number of files stored in the template list etc.
For example to set this number to 20, execute the following command in the Terminal;
defaults write com.hit-c.AutoTeX "Number of Recent Items" -integer 20
The number should be larger than or equal to 1. Set 10 to change to the default value. When the number decreased, this does not take effect immediately, but takes effect when a new file is added to the list. This number affects the template list, symbolic link original list and extra folder name list.
* Change a response string for an unix command.
For example to set to reply “yes[return]” for three input prompts, execute the following command in the Terminal;
defaults write com.hit-c.AutoTeX "Task Input String" 'yes\nyes\nyes\n'
Here ‘\n’ means a carriage return key. Similarly, ‘\t’ means a tab key. Put ‘\\’ for ‘\’ itself. There is no way to change the response depending on the situation. Change the last part of the command to '\nx\nx\nx\nx\n\\end\n\\end\n' to revert to the default value.

6.2 Known problems and workaround