Installing and Tuning OpenOffice on Mac OS X

This article gives a few tips for users of OpenOffice on Mac OS X.

My reason for looking into this was that I need to produce long technical documents as PDF files. It is important that these PDFs come with structured bookmarks that correspond to and are created from the heading structure in the original document (in my case MS Word).

<rant>MS Word and Adobe Acrobat are useless for this because sadly enough there is just no way to get structured PDFs out of Word on Mac OS X. Adobe’s PDFMaker Plugin for Mac OS X is a sick, cruel joke. It takes ages to create flat PDF files without any bookmarks. A technical document without these is unacceptable. PDFMaker’s output doesn’t have any advantage over the PDFs produced using Apple’s standard Print dialog, and it’s slower. The Windows version of the plugin works fine and does everything I need. I wish Adobe would get its act together...</rant>

Using

• OpenOffice 1.1.x,
• Apple’s X11 server package
• a third-party macro called extendedPDF
• a custom hybrid Perl/AppleScript
• Adobe Acrobat Distiller (could also be replaced using GhostScript)
• EPS images in my document,

Along the way, I also had to tweak some font settings and libraries to get our corporate font working and to fix the ugly font rendering in the OpenOffice GUI, so that it is easier on my X11-weary, Aqua-spoiled eyes :-)

Installing X11

If you don’t already have X11 installed, you can download it from Apple. You can check if it’s already installed by looking for an application called X11 in your Utilities folder.

Installing OpenOffice

There are several versions of OpenOffice for Mac OS X. A very nice, Mac-like and easily installed package is called NeoOffice/J, but unfortunately that is based on version 1.0.x of OpenOffice, and the setup described in this article requires version 1.1.x.

The package we’re going to use is the so-called X11 version. At the time of writing, OpenOffice 1.1.2 was current, you can download it from http://porting.openoffice.org/mac/ooo-osx_downloads.html.

After downloading it, follow the installation instructions carefully. Basically you just have to launch the installer application on the disk image. One problem I experienced was that the installer got stuck at the very end of the process, the status line read convert_lucida.sh. If that happens to you, go and read this FAQ entry.

The following subsections are not required, but kind of neat.

Preferences settings

I disabled the Enable Key Equivalents under X11 option, because that way all keystrokes with the ⌘ key get sent to OpenOffice, which means that commands like ⌘-C, ⌘-V etc. will just work as expected.

Creating X11 application shortcuts

Apple’s X11 application allows you to define shortcuts for often-used applications. You can then access these from X11’s dock icon, as shown here:

You can also fire up OpenOffice the usual way, using the Start OpenOffice.org.app program installed in your /Applications/OpenOffice folder, but I like it this way as I usually launch X11 first using LaunchBar and then start OpenOffice from within X11.

This is how I configured the shortcuts (under Application -> Customize...):

Changing the X11 server clickthrough mode

By default, Apple’s X11 server “swallows” clicks that bring a window to the front. This drove me nuts whenever I wanted to activate an icon or an entry in one of the palette windows, e.g. the style sheet list.

Luckily the setting can be changed. Type this command into a Terminal window:

defaults write com.apple.x11 wm_click_through -bool true

This and many more useful hidden settings can be found in the man pages for quartz-wm and Xquartz (I stumbled upon these here)

Testing OpenOffice

At this point you should test your installation to make sure everything installed so far works correctly. Try to launch OpenOffice and create a new text document. Play around with the program.

If it doesn’t work, you need to fix that first. The Trinity forums are probably a good place to go for information and assistance.

Installing the extendedPDF Macro

OpenOffice has the ability to export directly to PDF starting with version 1.1.x. However, these PDFs do not have the structured bookmarks that we’re after here. To get these, you have to install the extendedPDF Macro by Martin Brown.

Follow the installation instructions in the documentation. I installed the button next to the New button in the toolbar:

After you followed all the installation instruction steps, you should have a button there:

Configuration and first test

This assumes that you have Adobe Acrobat Distiller available.

What the extendedPDF macro does is to add special commands to the PostScript code generated by OpenOffice. This code is written to a temporary .ps file on disk. Acrobat Distiller or GhostScript can read this PostScript file and convert it to a nicely formatted and structured PDF file.

When run, the extendedPDF macro invokes an external program with the name of the temporary .ps file and expects that program to create the PDF file. By default, extendedPDF is configured to run the external program gs, the GhostScript PostScript interpreter. It can be configured to use Acrobat Distiller instead.

For a quick test and for less frequent use, it’s also possible to create the temporary PostScript file and then drop that into the Distiller window. Another possibility is to use Distiller’s Watch Folder feature to have it pick up and convert the new temp files automatically.

Let’s do a quick test first. Create a document in OpenOffice that includes some body text and a few paragraphs to which the Heading 1 and Heading 2 styles are applied:

Save the document and then click on the extendedPDF button you created earlier. In the File Settings pane of the dialog, set the Temporary folder location to your Desktop folder and uncheck the Delete temporary files option.

All other settings are fine for now. Click OK to start the conversion. You will probably get an error message at the end, because extendedPDF tries to launch the gs program which is not available. It should have created the temporary .ps file on your desktop, and that’s what we’re interested in.

Drag this onto the Acrobat Distiller icon to convert it to the final PDF file:

Open the PDF in the Preview application. You should see a drawer with bookmarks in it, corresponding to the headings in your document:

Automatic Invocation of Distiller

(See below if you want to use GhostScript instead)

The above procedure is OK for creating PDFs once in a while, but it’s not elegant, especially because of the error message after each conversion. I wanted to hand over the temporary .ps file to Acrobat Distiller automatically after clicking OK in the extendedPDF screen, so I wrote this little Perl/AppleScript:

#!/usr/bin/perl
#
# OpenOffice helper script to invoke Adobe Acrobat Distiller
# in place of ghostscript on Mac OS X from the extendedPDF
# Macro (http://www.jdisoftware.co.uk/pages/epdf-home.php).
# 
# Install this somewhere on your machine, make it executable
# and then configure its path instead of the "gs" command
# in the "Configuration" dialog of the extendedPDF GUI. 
#
# Written by Marc Liyanage, see http://www.entropy.ch
#
#
use warnings;
use strict;

use IO::File;

my ($outputfile) = map {/^-sOutputFile=(.+$)/; $1 ? $1 : ()} @ARGV;
my ($inputfile) = $ARGV[-1];


my $applescript = <<"EOF";

with timeout of 600 seconds
 tell application "Acrobat Distiller 6.0.2"
  Distill destinationPath "$outputfile" sourcePath "$inputfile"
 end tell
end timeout


EOF

my $pipe = IO::File->new("|/usr/bin/osascript");
$pipe->print($applescript);
$pipe->close();

Save this or something similar to a file on your system, e.g. with the name oo_pdf_helper.pl. I keep scripts like these in a bin folder in my home directory. You have to make sure that it has the UNIX executable flag set (chmod 755 filename in the terminal).

When the script is ready and executable, you have to tell extendedPDF to use it. Click on the extendedPDF button again and switch to the Configuration tab. Enter the path to the script into the text field. Mine is /Users/liyanage/bin/oo_pdf_helper.pl in the example:

You can enable the Delete temporary files option again in the File Settings tab.

If you click on the OK button you should get a PDF automatically. You can watch Distiller do its thing after you click OK in OpenOffice. After a few seconds, the PDF file should appear.

Automatic Invocation of GhostScript

Install GhostScript first, e.g. using Fink. Find out the path to the gs program, for Fink that’s usually /sw/bin/gs.

Click the extendedPDF macro button and switch to the Configuration tab. Enter the path to gs into the Path to GhostScript text field and click OK.

Installing fonts

I had to install our custom corporate PostScript Type 1 font family so my documents look right. OpenOffice cannot work with the font files used on the Mac directly. PostScript Type 1 fonts need to be converted to the pfb/afm formats. The installation procedure for OpenOffice will convert the fonts and add them to OpenOffice’s collection automatically if possible. To convert additional fonts later on, take a look at the fondu program.

In my case I was lucky because we already had the fonts in UNIX-style pfb/afm pairs so I used those and didn’t have to convert any Mac fonts.

Once you have converted or otherwise obtained the UNIX-ready fonts, you have to tell OpenOffice to add them to the font menu. You do that in the spadmin program, see the shortcuts in the X11 application I configured above to launch it. In spadmin, click on the Fonts button:

Choose Add and click the browse button under Source directory. Navigate to the directory that contains the pfb/afm font files and click on Select. You should see a list of the fonts that were found. Select the ones you want to import and then click on OK:

This takes you back to the font list. You might have to rename some of the new fonts if their names were not recognized correctly, as in my case here (Interstate, Regular is wrong for most of the fonts). After I fixed it, it looks like this:

Click Close twice to leave spadmin. Quit and relaunch OpenOffice and you should see your fonts in the font menu:

Replacing libfreetype (optional)

I’m a total font junkie. I absolutely cannot bear to look at badly rendered fonts.

You might notice that TrueType fonts look awful in OpenOffice in the default environment.

The reason is that the library used by the X11 application to render TrueType fonts (called FreeType) does not have the so-called bytecode interpreter enabled. This is usually disabled for legal/patent reasons and has to be switched on when the software is compiled. Ironically, Apple is the holder of those patents :-) No idea why they didn’t enable it on their own OS...

Even with the bytecode interpreter enabled, FreeType still does not deliver good results. So in addition, some patches to the software by David Chester have to be applied, and the results of those patches alone are truly stunning. Every single font in the GUI now looks very nice, including the body text in the online help pages.

Compare the two versions (click onto the image for a larger list with more fonts):

The top one is with the original libfreetype installed, the bottom one with the improved version. Compare the stroke weights and the overall look in the different fonts.

After all those tweaks, the font rendering will still be slightly inferior to Mac OS X’s native Quartz rendering because OpenOffice does not use subpixel rendering, but it’s absolutely usable now.

I replaced the Apple-supplied libfreetype library with one I patched and compiled myself. If you’re adventurous enough to overwrite Apple-supplied system components, you can do the same thing. Download the tar file and unpack it in the /usr/X11R6/lib directory. Quit and relaunch OpenOffice and check to see if the font rendering is improved.

Here are the exact steps:

% cd
% curl -O 'http://www2.entropy.ch/download/libfreetype-2.1.9-davidchesterpatch.tar.gz'
...
% cd /usr/X11R6/lib/
% sudo mkdir libfreetype-orig
Password:
% sudo mv libfreetype.* libfreetype-orig
% sudo tar -xzf ~/libfreetype-2.1.9-davidchesterpatch.tar.gz

This will leave a backup of the original files in the directory libfreetype-orig.

More GUI / Config Tips

Since I will probably spend a lot of time in OpenOffice, I went through all options to tune it a bit more to my taste.

Change GUI Font

I didn’t like the default GUI font. To change it to one of the other fonts, you have to go to Tools -> Options -> OpenOffice.org -> Fonts. There you can activate the replacement table. You have to add a font replacement rule; the font to replace is called Andale Sans UI. Replace it with the font of your choice, make sure to check the Screen checkbox. Your change should be reflected immediately after you click on OK.

After trying out lots of the fonts available in OpenOffice, I can highly recommend Luxi Sans. It’s what I use now and it works well in all GUI situations.

Disable Help Agent and Tips

In the Help menu, I disabled the Help Agent as well as the two Tool Tip options.

No icons in menus

The icons in all the menus clutter up the interface IMHO, therefore I unchecked the Show icons in menus option in Tools -> Options -> OpenOffice.org -> View.

Mac Look and Feel

Again in Tools -> Options -> OpenOffice.org -> View, I picked the Macintosh look and feel. I did not do this to get the (OS-9) look of the buttons etc. (I think Standard would look better), but to get rid of the awful underlines in all menu items and user interface element text labels.

Keyboard Shortcuts

Look at the table of keyboard shortcuts I put together.