6

Advanced use: Scripting

6.1 Introduction to Scripting

All the functions and utilities described so far were built into TEXworks by default. While some of them could be congured or customized to a certain extent, they are intended to suit the most common needs of a general audience. However, the TEX world is very large and diverse. In order to enable users to address their special needsfrom simply making some text bold to fullling special requirements for the next book or scientic paper you want to publish, the core functionality of TEXworks can be extended or modied by the use of scripts.

Scripts are simple text les that you can open, read, or modify in any text editor (including TEXworks, of course). They are written in a specic scripting language that is essentially a programming language. At the time of writing, TEXworks supports QtScript1 (built-in), Lua (with a plugin), and Python (with a plugin). To see which scripting languages are available on your system, use the Scripts!Scripting TEXworks!About Scripts… menu item.

Writing scripts is beyond the scope of this manual, but is documented elsewhere2. Here, only the installation and usage of scripts will be discussed.

TEXworks distinguishes between two types of scripts: standalone scripts and hook scripts. The primary purpose of standalone scripts is to add new functionality to the program. If you need a new function, such as a command to make the selected text bold, a standalone script is the one to choose. These scripts get an item in the Scripts menu, and you can run them simply by clicking on that menu item (or by using a keyboard shortcut, if the script provides one).

Hook scripts, on the other hand, are meant to extend existing TEXworks functions. They are hooked into the code at specic places, e.g., after the typeset process has nished or after a le was loaded, and can add or modify whatever TEXworks is doing. One example for this would be a script that analyses a newly loaded le and sets the spell-checking language based on babel commands found in the document. Thus, hook scripts do not show up in the Scripts menu but are instead run automatically when the TEXworks function they modify is used.

You can easily determine which type of script you have by opening the script le. Near the top of the le, you should nd a line similar to

  // Type: standalone

Alternativelyonce the script is installed, you can use the dialogue available from Scripts!Scripting TEXworks!Manage Scripts to display this information.

6.2 Installing Scripts

A word of caution rst: do not install scripts from a source you do not trust! Before installing scripts, you should make sure that the le you are about to install indeed does what you expect. Scripts are very powerfulthey can do almost everything a normal program can do. So while there are some security precautions built into TEXworks, you should still be aware that scripts could potentially harm your computer and cause (among other things) crashes and data loss. In particular, scripts can read, create, and modify arbitrary les on your hard drive.

That said, installing scripts is very simple. Script les are generally installed in <_resources>_/scripts or subdirectories of it. These subdirectories are shown as submenus of the Scripts menu, so they can be used to group and categorize scripts. This is especially useful if you use many dierent scripts that would otherwise make the Scripts menu very confusing. One easy way to open the scripts folder is the Scripts!Scripting TEXworks!Show Scripts Folder menu item.

Since scripts are usually simple plain-text les, they do not come with fancy installers. To install them, simply copy or decompress (if archived, e.g., in a .zip le) the script leand any other required les that you may have receivedinto <_resources>_/scripts or a subdirectory of it.

After having installed a new script le, TEXworks needs to become aware of it. It automatically scans for all scripts during start-up, so you could close all TEXworks windows and restart the application. An alternative is provided by the Scripts!Scripting TEXworks !Reload Script List menu item which rescans all scripts without otherwise interfering with the program.

You can also disable scripts (or whole directories of scripts) if you want to. This can be useful if you do not need some scripts for some time and do not want them to clutter the Scripts menu, but do not want to uninstall them entirely. Or if you want to prevent hook scripts from being run automatically. To do this, open the Manage Scripts dialogue with the Scripts!Scripting TEXworks!Manage Scripts menu item. Simply uncheck the script you want to disable and it won't bother you again.

6.3 Using Scripts

Using scripts is simple. Hook scripts are used automaticallyyou don't need to do anything. Standalone scripts show up in the Scripts menu or one of its submenus. If you cannot nd a script you are looking for, or if you nd a script you do not know the purpose of, you can use the Manage Scripts dialogue to get additional information (like the author, a brief description, etc.) about it.

Some scripts need to run other programs on your system. One example would be a script that opens the pdf in the system's default previewer, e.g., for printing. Since running arbitrary commands can in some situations be particularly dangerous, this functionality is disabled by default. You will notice this when a dialogue pops up informing you of an error in the script, or a similar message is displayed in the status bar. To enable scripts to execute system commands, open the preferences dialogue via the Edit!Preferences… menu item. There, go to the Scripts tab and check the Allow scripts to run system commands option. If you want to disable this function again later just uncheck the option. Note that this option applies equally to all scriptsthere is currently no way to allow command execution only for some scripts.