Beyond the Basics

Configuring TeXWorks, TeXnicCenter or TeXShop

Some users are uncomfortable with the command line. Many TeX-oriented "integrated development environments" are available combining an editor, a previewer, and menus for various operations. One of these is TeXWorks, which is available in MiKTeX, TeXLive, MacTeX and BasicTeX. Here we explain how to configure TeXWorks to process input files using the musixtex script.

After starting TeXWorks, click on

Edit $\rightarrow$ Preferences $\rightarrow$ Typesetting

then click on + to add a new processing tool as follows:

MusiXTeX (or whatever you want)
You can move this processor up the list of available processors by using the up-arrow button.

TeXnicCenter is a TeX-oriented editor for Windows. To process files using the musixtex script, click on

Build $\rightarrow$ Define Output Profiles $\rightarrow$ Add

and provide a profile name, such as MusiXTeX => PDF; use musixtex as the (La)TeX compiler and choose "Main file's full path without extension" as the command-line argument. Click on "Do not use BibTeX" and "Do not use MakeIndex", and click OK.

TeXShop is available for OS-X and has similar capabilities; check out

TeXShop Help Menu $\rightarrow$ TeXShop Help Panel $\rightarrow$ Advanced Help $\rightarrow$ Additional Typesetting Engines

Problems with the Adobe PDF Reader

On many systems, the Adobe Reader is the default PDF viewer. But this application does not re-load the display automatically if the pdf file changes and, on Windows, the pdf file can't be overwritten while the Reader has it open. These properties make it difficult to use while editing a music file.

There are several ways to avoid these problems. One approach on Windows is to use the pdfopen/pdfclose applications available in MiKTeX with the Adobe Reader, as follows:

(process a source file) 
> pdfopen --file file.pdf
(edit the source file)
> pdfclose --file file.pdf
(process the source file) 
> pdfopen --file file.pdf
(edit the source file)
Note that you can only use pdfclose on a file that has been opened with pdfopen. The pdfopen/pdfclose applications in (the non-Windows versions of) TeXLive differ from those in MiKTeX.

Another approach is to use (while editing) a PDF viewer that allows the file to be overwritten and re-loads automatically when that happens. Here are some recommended applications.

On Windows:

On Mac OS-X: Preview, which is the default PDF viewer on OS-X (but check out this warning)

On Linux:

Any of these can normally be installed using your distribution's package manager.

Finally there are several TeX-oriented editing environments (such as TeXWorks, available in TeXLive, MiKTeX and MacTeX, or TeXShop, for MacTeX) which have an integrated PDF viewer and can be configured to use the musixtex script as the TeX processor.

Adding Non-Distribution Packages

Texmf Files

Normally, packages are updated or added to MiKTeX or TeXLive or to a Linux distribution by using the distribution's update or package manager, as discussed above. But if you want to add a package or an update that isn't (yet or any longer) in your distribution, such as one of the addon or beta packages described below or packages from CTAN (the Comprehensive TeX Archive Network), you should set up and use a "personal" texmf tree; do not modify or add to the distribution tree, which will confuse the package manager and may lead to instability. Normally, files in a personal texmf tree (or in a working directory) have precedence over files in the distribution tree.

Detailed instructions for setting up a personal texmf tree in MiKTeX can be found in Integrating Local Additions in Chapter 4 of the MiKTeX manual. Essentially, you create a new folder somewhere (even on your desktop), and populate it with subfolders and files following the TDS standards (discussed below). Then add the path to the new folder in the Roots option of the MiKTeX Settings wizard. Note that if you have admin privileges on your system, there will be both an Admin Settings and a User Settings wizard; use the former to make the added files accessible to all users. Update the File-Name Database (FNDB) in the Settings wizard after adding files to a personal or local texmf tree.

In TeXLive, personal additions are by default expected to be under $HOME/texmf; after any changes to this tree, execute texhash $HOME/texmf to update the data base of file names.

In MacTeX, $HOME/Library/texmf/ is by default a user's personal texmf tree. On Lion and Mountain Lion, the $HOME/Library folder is hidden; to open it, use the Finder's Go menu and hold down the Option key to reveal an extra item in the menu.

On all platforms, it is important to put files into suitable sub-directories, as specified in the TDS (TeX Directory Standard); the following is a summary of the most relevant paths:

TeX macros:
LaTeX macros and sty (style) files:
where texmf is the path to the root of the texmf tree and package-name is the name of the package; for Windows, replace / by \. Consistent use of package-name directories, as above, makes it easier to find and uninstall all the files of a package. For more information, check out A Directory Structure for TeX Files.

Executables (other than platform-independent scripts) do not appear in texmftrees; distributions deal with executables in different ways. If the package provides an executable suitable for your platform, you must move it to a directory on the PATH of executables; otherwise, you may need to first compile the program from source files extracted from an archive, typically doing ./configure && make && sudo make install.

Font Maps

If you have added new fonts to your personal texmf tree, it may be necessary to enable the relevant font-map file.

On all platforms, the command kpsewhich can be used to see where any TeX-related file is located; for example,


will tell you where the currently "active" map for Type 1 fonts is. You can check that the relevant lines have been added, but do not edit directly because your modifications will be overwritten when you install new packages.

Documentation for MiKTeX, TeXLive, BasicTeX and TeXWorks





Binaries and Scripts


A beta program or version is software that is released for testing by the developers but has not yet been deemed "stable" (ready for general use). Software referenced here is not for novices nor for "production" use. Bugs are to be expected and should be reported to the developers.

Bob Tennent