LyX for Mac OS X

This is a HOWTO for LyX/Mac, a full-featured native implementation of LyX on the Mac OS X.

This document is based on LyX/Mac 1.4.0 or greater; if you are using an earlier version, the upgrade is easy to install and offers considerable new functionality. If for some reason you want to stick with an earlier version, you may want to look at this page devoted to LyX/Mac-1.3.x.

New users of LyX/Mac may want to follow the (somewhat outdated) Walkthrough.

New!

2008/11/14: LyX-1.6.0 has now been released as a Universal binary. And LyX-1.5.7 has been released as the final release of the 1.5 series. LyX-1.5.7 can open files saved in the LyX-1.6 file format.

Download

LyX/Mac is available as a binary for Mac OS X 10.3.9 and later. (Note additional prerequisites below.) The download page is here.

LyX/Mac is also available via fink as a native program and in an X11 version, although fink's releases are probably of earlier versions than the ones listed above.

If you prefer to build LyX/Mac yourself, instructions are included in the LyX source.

Users new to LyX/Mac may find useful this installation walkthrough for help installing teTeX. A French tutorial is also available.

For users who prefer emacs-like modifier key bindings, there is additional information on customizing these keys, including patched binary versions.

Notes on LyX-1.6

LyX-1.6 is a significant upgrade; you might want to look at this overview of changes in LyX-1.6 generally. In addition to these changes to LyX generally, there have been a few changes to LyX/Mac. In particular:

• The user's directory has moved to ~/Library/Application Support/LyX-1.6. This is to preserve compatibility with older versions of LyX, since LyX-1.6 uses new .bind and .ui files. (If you don't know what these are, don't worry: you can safely ignore them.)
• The example LyX files are actually now located inside the application. In Finder, highlight the LyX application, then select action "Show Package Contents". Follow Contents->Resources->examples.

Mac

Prerequisites

You need a TeX installation. There are four options for this:

1. Use MacTeX. The .dmg file is a bit big (1300+ MB), but it is a very complete distribution and installs right out of the box. It is a single-step installation and therefore recommended for beginners who do not know which components they need. MacTeX includes all the components necessary for TeX to work, plus the spellchecker Excalibur and the bibliography managing program BibDesk.
2. Use the fink package management system to install tetex, ghostscript, and imagemagick.
3. Use the MacPorts package management system.
4. Use Gerben Wierda's convenient i-Installer. Go here for clear and somewhat detailed installation instructions. Or go here for simpler, less detailed instructions. This distribution is now obsolete (since Jan 2007). Gerben Wierda has recommended MacTeX as the alternative.

To use other implementations of teTeX which do not install the binaries in /usr/texbin, /usr/local/teTeX/bin/powerpc-apple-darwin-current, /sw/bin, /opt/local/teTeX/bin, or /usr/local/bin, either link the teTeX binaries to one of those directories, or add the PATH of your teTeX binaries to the PATH prefix field in LyX -> Preferences -> Paths.

NOTE: If you wish to use xFig generated fig files with latex commands in Lyx, then use the i-Installer to install xFig (and its required packages). Remember to reconfigure Lyx after the installation.

Change Language of LyX's Menus and Dialogs

To change the GUI language, you'll need to modify your ~/.MacOSX/environment.plist file. For details, see the environment.plist page.

Useful Helper Programs

Previewers

LyX/Mac uses the system default viewers, and should require no configuration for PDF and HTML. If you have MacDviX or MacGhostView installed, LyX will use them to preview DVI and Postscript. Another good previewer for .dvi, .ps, and .pdf files is TeXShop, which is also an excellent stand-alone TeX editor. Although it's still in beta, TeXniscope is a fine, free DVI viewer.

Spellcheckers

• The easiest spellchecker to install is cocoAspell. CocoAspell provides an installation of aspell and a preferences pane for selecting and setting up dictionaries. It includes English dictionaries by default, and other dictionaries can be downloaded and installed according to the instructions on the cocoAspell page. To get cocoAspell to work with LyX, follow these installation instructions. (Note that some users have encountered difficulties with cocoAspell. If this doesn't work for you, you might try installing aspell directly.)
• Spellcheckers compatible with LyX/Mac include aspell, ispell, and hspell; these can be selected from the drop-down list in LyX -> Preferences -> Language settings -> Spellchecker. (Installation Instructions)

Bibtex tools

• BibDesk is a highly recommended tool for maintaining BibTeX databases. Other possibilities include JabRef, tkbibtex (used with Tcl/Tk Aqua) or its aquafied counterpart, AquaTkbibtex, respectively, and Endnote (used with scripts that convert Endnote citations to LaTeX citations).
• To define a path that will allow LyX to find your .bib files automatically, you may want to modify your ~/MacOSX/environment.plist file. For details, see the environment.plist page.

Envelopes

To print envelopes, install envelope in /usr/local/bin and make it executable. While you're writing a letter in LyX, do File -> Export -> Custom -> ASCII and give envelope as the command; it will parse the address from the letter and print an envelope, including the USPS barcode.

OmniGraffle converter

OmniGraffle is a great software for creating diagrams under Mac OS X (in particular, it works very well with LaTeXiT so that you can easily insert math formulae into diagrams). As it doesn't have a command line mode, you can use an AppleScript in order to insert ".graffle" files directly into LyX.

• Put og-export.scpt somewhere on your disk (e.g. in $HOME/Library/Scripts/).
• In order to use it, go to LyX preferences, add an OmniGraffle file format (just type auto for the editor), and then add converters:
  • OmniGraffle -> PDF (ps2pdf) converter: osascript replace/with/path/to/og-export.scpt `pwd`/$$i `pwd`/$$o pdf
  • OmniGraffle -> EPS converter: osascript replace/with/path/to/og-export.scpt `pwd`/$$i `pwd`/$$o eps
  • OmniGraffle -> PNG converter: osascript replace/with/path/to/og-export.scpt $$i $$o png
• Note that currently, LyX doesn't work with OmniGraffle packages (e.g. diagrams including images). This problem will hopefully be solved in the future (see this bug for details).

Beyond basics

More on Previewing

For on-screen preview of math with latex-preview (as in the screenshot), make sure you have ghostscript installed and set the Instant Preview option under Preferences -> Look & feel -> Graphics.

Interaction with X11. Xfig or X-windows previewers like xdvi or gv can be used with LyX/Mac if you modify your ~/MacOSX/environment.plist file. For details, see the environment.plist page. Alternatively, you can change the viewer for postscript or dvi with DISPLAY=:0.0 gv or DISPLAY=:0.0 xdvi. Note that X11 must be running first for either of these to work.

Reverse DVI search, which allows the cursor in LyX automatically to jump to the point where you OPTION-click (ALT-click) in the previewed DVI file, can be enabled with recent versions of teTeX and MacDviX or xdvi:

• Change Preferences -> Converters -> Latex -> DVI -> Converter to latex --src $$i or include \usepackage[active]{srcltx} in the preamble of your LyX files.
• For MacDviX, add at the end of /Applications/MacDviX_Folder/calleditor.script:

     /Applications/LyX.app/Contents/MacOS/lyxeditor "$2" $1
     exit 1

• For xdvi, change Preferences -> Outputs -> File formats -> DVI -> Viewer to

   DISPLAY=:0.0 xdvi -editor 'lyxeditor %f %l'

PdfSync

PdfSync is similar to reverse DVI search but is for the (now more common) method of directly producing pdf files. If you use the program Skim as your previewer you can COMAND-SHIFT-click in the previewed pdf file which causes the cursor to move to that point in LyX.

• In LyX > Preferences > File formats > PDF (pdflatex), enter open -a Skim.app $$i in the viewer setting. *Then* you need to click the Modify button, and then Save.
• In Skim > Preferences > Sync select LyX.
• Include \usepackage{pdfsync} in the preamble of your LyX files.

  Troubleshooting PdfSync

  Make sure that the .lyxpipe.in and .lyxpipe.out files do not exist when LyX is not running. (They are normally deleted when LyX quits, but if LyX crashes, they remain and prevent LyX from communicating with PDFView.) Their location can be found in LyX > Preferences > Paths.

XeTeX

XeTeX is "a typesetting system based on a merger of Donald Knuth's TeX system with Unicode and Mac OS X font technologies." In other words, it will let you use any of your standard Mac OS X fonts with TeX/LaTeX. For more information, check out the LyX/Mac XeTeX page.

Version Control

Version control is useful for managing large documents, or documents with multiple authors. In order to implement it, you need to have RCS (Revision Control System) installed. This is a standard part of Xcode. The simplest way to get version control working, is to install the Xcode Tools package contained on the OS X install DVD. See the Mac Version Control page for more information.

Pipes

BibDesk

There is now a newly modified version of Mark Reid's SendToLyX.scpt to allow BibDesk to send bibliographical citations to LyX. To use it, download the file to your disk, and move it to ~/Library/Application Support/BibDesk/Scripts. For more information on this script, see Mark's page, and there is also some information about using it to insert references for SGML output.

Name in Path Problem (JabRef)

Programs such as JabRef communicate with LyX via pipes, which are sometimes named incorrectly by default (e.g., they assume that the pipe is in a directory that has a space in its name, such as Application Support, but other programs often cannot deal with spaces in paths). You may need to fix the lyxpipe path in both LyX and JabRef in Mac OS X.

To fix the LyX pipe in JabRef, open JabRef and go to Preferences>External Programs and in "Path to LyX pipe" enter /Applications/LyX.app/Contents/Resources/lyxpipe. Close JabRef.

Then open LyX, go to LyX>Preferences>Paths, and in "LyXServer pipe" enter /Applications/LyX.app/Contents/Resources/lyxpipe. Reconfigure. Close LyX.

The next time you run LyX and JabRef, you should be able to push citations directly from your BibTeX bibliography in JabRef into LyX. If anything goes wrong, JabRef will return an error message, and you will have to redefine the pipe. You might try the following: (1) change the LyXServer path in LyX -> Preferences -> Paths back to ~/.lyx; (2) recreate the ~/.lyx directory by entering in a terminal session, "mkdir ~/.lyx"; and (3) restart LyX.

Known issues

1. To communicate with some programs, you may have to rename the lyxpipe.
2. Due to limitations in the Qt/Mac library, interface languages other than English modify the organization of the toolbar menus and it may not be possible to directly enter some special characters into the document preamble (you can copy them to the preamble).
3. If math fonts do not show up on the screen properly, it may be because you have the CMdfont files installed (as suggested by MacDviX). Try disabling the following fonts: AMS.dfont, CM_2.dfont, CM_4.dfont, LaTeX.dfont, CM_1.dfont, CM_3.dfont, Euler.dfont, WNCY.dfont. (You will then have to reconfigure -- Edit -> Reconfigure -- and restart LyX.)

Please report any other bugs to the appropriate LyX mailing list. A web gateway is also available.

The information on this page is believed to be accurate, has been used successfully on many systems and sites, and has benefited from the comments and suggestions of many users. Due to the variations in individual systems, this information and the various files and code available on this page are conveyed as is with no warranty of any kind.

More information

This group contains the following pages:

Categories

Mac JabRef lyxpipe TeX