PPTools/Guiguts/Install/Mac

From DPWiki
< PPTools‎ | Guiguts‎ | Install
Jump to: navigation, search
Exquisite-khelpcenter.png Note

Some of this document may be out of date. For the most up-to-date instructions on installing Guiguts on a Mac, please read the installation instructions included with the latest release.

You can obtain the latest release of Guiguts from the Guiguts GitHub page.


Version information

10:04, 22 July 2011 (PDT) -- Warning: With a basic install of Lion (Mac OS 10.7), there seem to be some problems installing the right Perl tools to get guiguts running. The instructions below have been tested only through 10.6 with version 3.2.5 of the Developer Tools, and there seem to be also some problems getting a full install of the necessary Perl tools in later versions of 10.6 with 3.2.6 of the Developer Tools.

The current version of the Mac guiguts install wiki was created in October of 2009. After much editing and rearranging and testing, it goes live: 21:43, 17 June 2010 (PDT).

If you are using Mac OS X 10.4.11, check out Tiger gg install. This is the last version of the instructions before the change in instructions for the early versions of 10.5.

Administrator Privileges and other Setup Details

Administrator access

You MUST have a password protected administrator account for your computer because you MUST have an administrator password for parts of the guiguts install. You will need to use the unix command "sudo" several times throughout the process. If you did not set up a password when you first set up your account because you are the only user on your computer, even if you set yourself up as the administrator, you will not be allowed to use "sudo" on the command line!

The following steps will create many files, some requiring Administrator privileges to create. However, they must be owned or accessible to the Guiguts user, or there will be annoying file-ownership issues later. To check to see if you have admin privileges, launch System Preferences and click on Accounts. Your own account is highlighted. If your account has the word "Admin" under it, and "Allow user to administer this computer" is checked on the right side of the window, you have administrative privileges. If you have not already set up a password, do so now.

If your working account does not now have administrator privileges, log out and log back in as a user who does. Then looking at the accounts pane in System Preferences,

  • Click the padlock icon and when asked, enter the admin password.
  • Select the account under which you'll normally use Guiguts.
  • Activate the button "Allow user to administer the computer."
  • Set up a password if you do not already have one.
  • Log out and log back in as that user (the account in which you will normally be using guiguts).

For the remaining steps we assume you are logged in as the Guiguts user and that you have administrator privileges for the duration of the installation process. Later, when Guiguts is fully installed, you can go back and remove administrator privileges from the Guiguts user, if that is desirable for security.

Visible file extensions

By default, Mac OS has file extensions invisible. If you cannot see the .app on any of your applications, and wish to be able to see extensions (like .app, .doc, .txt, etc.), make sure you are in Finder (the menu next to the Apple menu in the upper left-hand corner of the screen will say "Finder". Just clicking on the desktop should get you there), and under the Finder menu, choose Preferences .... Click on the Advanced tab (looks like a gear of sorts), make sure there is a check-mark beside "Show all filename extensions", and close the preferences pane.

Unix, Perl, and Tk, Oh My!

Since Apple's OS X is basically a Unix system, it supports the many open-source programs available for Unix and Linux, including the ones that create the environment in which Guiguts can run: the Perl language, the Tk interface toolkit, the Aspell spellchecker, and the HTML Tidy utility. Other than Perl these items do not come installed in your OS X system, but you can add them. However, doing so requires you to be a Unix user. You must either be unafraid of the Terminal application and its command-line interface or else recruit a Unix (or Linux) guru to help you.

These instructions are based on OS X 10.5.8 "Leopard" and were tested on both an Intel-based Mac and a PPC based Mac, and have also been tested on "Snow Leopard" 10.6.2. There are similarities between the install for Leopard 10.5.8 and that of Snow Leopard 10.6.1. The chief difference noticed is that the latest version of Xcode (Developer Tools) for 10.5.8 is 3.1.4, and, as of this writing, the latest available for 10.6.2 is 3.2.1.

To discuss Mac installation problems try this forum thread. Please feel free to update this information if your experience is different, or post in the forum thread so someone else can.

Step One: X11

Guiguts uses the Tk interface kit to create its user interface. Tk uses the X window system. X11 was not installed by default on older systems, but should be on both 10.5.8 and 10.6. To confirm that it is present, look in the Utilities folder in the Applications (/Applications/Utlities) folder for a program named X11.app. If it's there, proceed to Testing X11.

If not, continue on to the next step and install X11 on your system.

Installing X11 if it is not already on your system

If you are installing Leopard for the first time, on top of an existing system, or as a Clean Install, click the Customize button. Find X11 in the list of packages, and make sure it is selected. (You can also customize the installed printer drivers and languages at this time.)

If you are starting with an existing installation of Leopard, and for some reason X11 was not installed initially, you can add it. Mount the installation DVD. Open the Optional Installs folder.

Guiguts MI 1optionalinstalls.png

Doubleclick Optional Installs.mpkg to start an installer for the optional items. After selecting a target drive and agreeing to the license, you get a check list that contains X11. Select it and complete the installation.

Guiguts MI 2x11install.png

Now that you've got it installed, it's time to proceed to testing X11.

Terminal and X11

During the rest of the installation, you will primarily be using the command line in Terminal.app, and X11 will be used during the installation processes for testing. In versions of OS X before 10.5 you had to manually launch the X11 application before you could run programs that used it. This is no longer true. Now you simply start an X11-using program from the terminal command line, and the X11 environment automatically initializes.

Testing X11

To see if X11 is working, open the OS X Terminal application (/Applications/Utilities/Terminal.app). On the command line enter the command

xclock -analog &

The xclock program creates its window and runs.

Guiguts MI 4xclock.png

The ampersand means "start it and don't wait for it to complete." If you omit it, you can't enter another command in that terminal window until you terminate xclock (click on the "close" button on the xclock window or "ctrl-c" from the Terminal window. There are other ways if you're familiar with unix, but one of those should do it with no problem).

You probably do not need to specify "-analog". Note also that the appearance of the clock in the X-window is not instantaneous.

Occasionally, xclock will not appear to work. If you're invoking it for the first time, it may seem to take a very long time. If X11 is already running, you can try quitting X11 and having Terminal bring it up fresh. If this still doesn't work, go on and try the xeyes command. If neither of them works, post in the Mac gg install thread and yell for help.

Another fun test of X11 is the command

xeyes &

Move the cursor around and watch what happens. :-)

Later you will start Guiguts in just this way (following the invocation of the program with an &).

Note: if you are an experienced UNIX user and have customized your shell initialization files (your ~/.profile , ~/.login, ~/.tcshrc or similar files) to include a command to initialize the DISPLAY environment variable with set DISPLAY=:0. For Leopard, you need to remove any such statements. You must allow the system to set your DISPLAY variable for you. If it does not, you will get plaintive messages from X11 applications about being unable to connect to the display. (Note: This note is included from an earlier version of installing gg on earlier versions of Leopard using Xcode 2.5--it is not tested as of 10.5.8 using Xcode 3 or later, or 10.6.2, as I have never customized shell initialization files in this way.--Sharon, 20100401.)

Step Two: Developer Tools

Please read through the following section, whether you think you need to install the Developer Tools/Xcode or not.

Getting the Developer Tools

You need Apple's Developer Tools, including Xcode, because the installation process for various open-source packages requires compiling source code. Unlike Linux, OS X doesn't come with a compiler by default. You may have already installed the Developer Tools; if you have, there is a top-level folder named Developer on your boot drive. You can either do a Spotlight search for Xcode or check in your /Developer/Applications folder to make sure that it's there, because you can have a top level Developer folder without Xcode being present.

Important: Shortly you will be installing programs which require make. If you get an error saying that make is unavailable, or something similar, this means that it is either unavailable on your system, or for some reason cannot be found. If this happens, (1) find the Disk Utility program in /Applications/Utilities, and run "Repair Disk Permissions". (2) Reinstall Xcode.

If you do not have the latest version of the Developer Tools available to you on your OS X install disk, you can find them as a free download at developer.apple.com. The downloads are free as of this writing.

Click on "Xcode". Both Xcode 3.1.4 and 3.2 are available as downloads from the linked page.

If you are installing on Leopard 10.5.8, you should download Xcode 3.1.4; if on Snow Leopard 10.6.x (latest version as of 2010-11-11 is 10.6.5), then you should download the latest version of Xcode 3.2 (the latest version available to download is 3.2.2, but it updates to 3.2.4 after running Software Update (2010-11-12)).

Note: As of 2014/07/16, only Xcode 5 and 6 are available from developer.apple.com. However, Xcode should be available as an optional install from your system disc.

Install Developer Tools

The following illustration shows the dialog box for installing Xcode 3.1.4. If you downloaded a .dmg file from the Apple Developer Connection as detailed above, double-click on it to mount it. In the virtual disk, you should see a file named "XcodeTools.mpkg". Double-click on this file to start the installation process.

Image of Xcode 3.1.4 install dialog box.

The first three items on the list should be checked by default. You should not not need to install the other two. Click "Continue" and complete the installation process.

Starting with 10.7, the Developer Tools do not install a working C compiler by default. To install a C compiler, launch Xcode, go to Preferences/Downloads/Components, check the box labelled "Command Line Tools" and click INSTALL.

Create a DP folder

In order to keep everything dp organized, it is advisable to set up a dp folder/directory on your computer somewhere. Earlier instructions recommended putting this directory at the root level, but it is not really necessary.

If more than one person uses the computer for PP'ing, and each uses a separate account, you may want to install a /dp folder at root level so that everyone is using the same copy of the software. However, it really doesn't take up that much room, and everyone who is PP'ing should have their own dp space to work in.

If you're the only person using the computer for PP'ing, there's no reason to bother to put it at root level. Note that one very good reason to have the dp folder in your home directory is that if you are running backup software that automatically backs up your home directory, you don't have to make a point to get the root level directory backed up separately.


Both sets of instructions are below:

dp directory in the user's home directory

You don't even need to use Terminal to do this (you can if you really want to, but it is not necessary). Open a Finder window and click on the house icon on the left-hand side of the window. In the menu-bar at the top of the page, choose New Folder, and name it dp. Your new dp folder should appear in the Finder window just below your Downloads folder.

As this dp directory is inside your account, and only someone signed into your account could be using it, there should be no access permission issues.

/dp directory at root level

If you opt to put your dp folder at the root level, open a window in Terminal, and enter these commands to make a top-level (root level) folder for your PGDP work.

sudo mkdir /dp  sudo tells the system to execute a command that requires super user privileges. You will have to enter your password if you haven't invoked the command in the previous 5 minutes.
sudo chmod 777 /dp    You are creating this at the root level, but anyone other than the creator will not be able to use it unless you make it accessible to everyone.

To make sure that it shows up, open a new OS X finder window. The new dp folder should be at the top level, just after Developer.

Wherever you locate your dp directory/folder, you might make an alias of this folder and put it on you desktop for convenient access, or drag it into the sidebar of the finder window.


IMPORTANT: When you back up the rest of your system remember to back up your /dp directory as well. This is especially important if you create a /dp directory at the root level. If it's in your user directory, it should be backed up automatically.

Create a pp directory

Whichever place you put your dp directory, one directory you will want inside it is one to keep your pp projects in. You can easily create right now, by opening a Finder window to your dp directory, choosing New Folder from the File menu, and naming it pp.

Referencing your dp directory

Two sets of instructions are given above for creating your dp directory. This is likely to cause confusion if you don't keep clearly in mind how to reference it, and as of 2010-06-17, there are inconsistent references in the rest of this article on how to refer to it when changing directories. Eventually they will hopefully be all cleaned up, but I'd like to document here what each means.

/dp

Where the first character is a / (slash character) is a reference to the dp directory at root level. This means that the directory can be seen by any account on the computer, if your computer has multiple accounts. cd /dp is the command you use to get to your dp directory from anywhere.

dp

or

~/dp

is a reference to the dp directory in your user directory. Both are used below. With the ~/ it is an absolute reference, and cd ~/dp will take you directly there. Without the ~/, it is a relative reference. If you are using Terminal, and your current location is a directory other than the top level of your home directory, and that directory does not have a dp directory inside it, cd dp will only get you a response something like:

-bash: cd: dp: No such file or directory

Bear in mind in the commands below where you have chosen to put your dp directory, and adjust the commands accordingly.

Install Perl Extensions

You have now prepared OS X to compile and run open-source software. The first packages of open-source software are extensions to the Perl language. Thousands of Perl extensions are maintained by devoted volunteers at the Comprehensive Perl Archive Network, better-known as CPAN. CPAN is not only a software archive and a website, but a standard extension to Perl, cpan, whose purpose is to make it easy to install copies of software maintained by CPAN. Perl and cpan are both included automatically in OS X.

To install Perl extensions we will invoke cpan in an OS X terminal window.

Note: In sanity checking these instructions I have noted that when setting up cpan the first time, the 10.5.8 dialog defaults to manual, and the 10.6.x dialog defaults to automatic. Because you want to choose mirror sites you should choose the manual configuration option.

Start and Configure CPAN

In your terminal window, start CPAN in privileged mode with the command

sudo cpan
Password:

The sudo command is shorthand for as super-user, do... and it tells UNIX to run the following command "as root," that is, with the ability to create directories and files anywhere, change file ownerships, etc. As shown, you are prompted for your login password. When you give it correctly, the cpan program runs and will shortly prompt with cpan>.

  • If, instead, you get a response like
    sudo: cpan: command not found
    Open the Disk Utility program inside the /Applications/Utilities folder, choose your drive from the side-panel, and choose Repair Disk Permissions and try again.

If this is the first time you have invoked cpan on this computer, you will be asked whether you want to configure cpan manually or not. I have seen the default answer be both yes and no, so read the first message carefully. You do want to configure manually if this is the first time. If you accidentally or on purpose choose the automatic configuration, then change your mind, type o conf init at the cpan prompt, and you'll be allowed to restart the configuration dialog. In general the default responses are appropriate, but there are two points in the process might require more attention.

You are asked for the locations of various utility programs:--

10.5.8 style:

Where is your gzip program? [/usr/bin/gzip]

Where is your tar program? [/usr/bin/tar]

Where is your unzip program? [/usr/bin/unzip]

Where is your make program? [/usr/bin/make]

Warning: lynx not found in PATH

Where is your lynx program? []

Warning: wget not found in PATH

Where is your wget program? []

Warning: ncftpget not found in PATH

Where is your ncftpget program? []

Warning: ncftp not found in PATH

Where is your ncftp program? []

Where is your ftp program? [/usr/bin/ftp]

Warning: gpg not found in PATH

Where is your gpg program? []

What is your favorite pager program? [/usr/bin/less]

What is your favorite shell? [/bin/bash]


10.6.x style:

<bzip2>
Where is your bzip2 program? [/usr/bin/bzip2]

<gzip>
Where is your gzip program? [/usr/bin/gzip]

<tar>
Where is your tar program? [/usr/bin/tar]

<unzip>
Where is your unzip program? [/usr/bin/unzip]

<make>
Where is your make program? [/usr/bin/make]

<curl>
Where is your curl program? [/usr/bin/curl]

Warning: lynx not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]
<lynx>
Where is your lynx program? []

Warning: wget not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]
<wget>
Where is your wget program? []

Warning: ncftpget not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]
<ncftpget>
Where is your ncftpget program? []

Warning: ncftp not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]
<ncftp>
Where is your ncftp program? []

<ftp>
Where is your ftp program? [/usr/bin/ftp]

Warning: gpg not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]
<gpg>
Where is your gpg program? []

<patch>
Where is your patch program? [/usr/bin/patch]

Warning: applypatch not found in PATH[/usr/bin;/bin;/usr/sbin;/sbin;/usr/local/bin;/usr/X11/bin]
<applypatch>
Where is your applypatch program? []

<pager>
What is your favorite pager program? [/usr/bin/less]

<shell>
What is your favorite shell? [/bin/bash]

The default locations in brackets are the actual locations on your system and show that the needed program was found. The only critical programs are gzip, tar, unzip, make and ftp. If any of these are not found, you need to find out why cpan could not find them in your execution PATH list, and obtain them if necessary.

The second thing that requires user input is later in the configuration, where you are asked to choose one or more locations for downloading software. Somewhere in the extensive list of candidates (probably at the end) is http://www.perl.com/CPAN/. Be sure to choose that one, as well as a couple of well-known university or other sites. The list is presented in four sections. I suggest writing down the mirror sites you would like to use and entering them when you get to the last page, to avoid confusion. When you have entered the numbers for your chosen sites, separated by spaces, press return twice and the process will complete.

For the 10.5.8 install, you may need to call o conf commit to make the configuration file permanent.

Note: You may get a warning at this point that your version of cpan is out of date. If you do:

install CPAN

and

reload cpan

as per the instructions given.

You will probably have to press return several times during this process to give permission for various dependencies to be fetched and added to the list of things to be installed.

Install Software

With configuration out of the way, we can start installing. In the following, remember that CPAN module names are case-sensitive; "ToolBar" is not equal to "Toolbar."

Also understand that you can end the cpan session at any time by entering a command quit, and restart it later with another sudo cpan.

LWP

Begin with the LWP bundle, comprising code that lets Perl programs browse the web:

install Bundle::LWP

Moderately voluminous output follows, in the course of which you may be asked a number of questions. The default answer, which you enter by just hitting return, is satisfactory.

The output should end in /usr/bin/make install -- OK. If it does not, enquire in the Guiguts forum.


Tk

This is where these instructions differ radically from previous instructions for installing gg on Mac OS. The version of Tk available directly through cpan will not install well enough to allow guiguts work with either the 3.1.4 or the 3.2 versions of the Developer Tools (as of October of 2009). A version of Tk has been found at http://search.cpan.org/~srezic/Tk-804.028_501/ that will install enough of Tk to allow guiguts to work. (September 2016: OS X 10.11.5 works better with Tk-804.033)

For now, quit cpan by typing quit, and, in a Terminal window, change to your home directory by typing:

cd

Download Tk-804.028_501 (dated 04 Nov 2008, and tagged as a Developer Release). The file should automatically be downloaded to your Downloads directory. Open Downloads in a Finder window, and double-click on Tk-804.028_501.tar to unpack it. Then, in a Terminal window:

cd Downloads/Tk-804.028_501/

Now to install Tk. Type each of the following lines is an individual command, followed by a return. You'll spend a fair amount of time watching text scroll past (as with the LWP install, above)(a.k.a. "Watching Paint Dry").

perl Makefile.PL
make
make test

The output of make test will be augmented by a large number of X11 windows flashing in and out of existence. This is supposed to happen. Not all of the tests will be passed. Most of them, should, however.

And finally:

sudo make install

Tk Extras

The following commands install smaller modules that Guiguts uses. First return to cpan with

sudo cpan

Then:

install Tk::CursorControl

The above command will bring up a window for you click on various buttons that have different functions. Even without user input, this box will go away in 60 seconds, so don't be disturbed if you follow the directions and the box doesn't disappear immediately. It will time out. Then continue with:

install Tk::ToolBar
install Module::Build::Compat
install Image::Size

The install process for each command is like, but shorter than, the process for Tk.

Levenshtein module

This is optional, but makes the word-harmonics feature work much faster:

install Text::LevenshteinXS

On completion of the installations, you can terminate CPAN with a quit.

When things fail

Sometimes the CPAN "make" process ends, not with the welcome word OK but with some type of failure. If the failure affects only one or a few of the many self-tests that each module runs, you may decide that it can be ignored. Perhaps after consultation with the Guiguts forum you can decide to "force" the installation. You do this by including the word force before the word install, for example

force install Bundle::LWP

This makes CPAN complete the installation regardless of test results.

Install and Test Guiguts

Get the latest version of the guiguts code from the Sourceforge site. Note: As of March 2010, the most recent stable version of guiguts is 0.2.8. Some PPers are also using 0.2.9. The most recent available for download as of 20100616 is 0.2.10, however, this version is buggy as of this writing. This distribution contains guiguts plus all the associated files.

If you didn't right- or control-click and download it directly to your dp folder, it will be in your Downloads folder. Open your Downloads folder in a Finder window, and drag the guiguts-0.2.8 folder to your dp folder.

  • Note: If you choose to use a stable version of guiguts older than 0.2.8, be aware that the guiguts-0.2.4.zip file contains only the perl file. In order to have everything you need, you must also scroll down the list and download guiguts-0.2.0.zip, which will decompress into a folder titled guiguts-0.2.0. These files should be in your Downloads folder. Open your Downloads folder in a Finder window. Drag the guiguts-0.2.4.pl file into the guiguts-0.2.0 folder, and then drag the guiguts-0.2.0 folder to your dp folder. Inside the folder/directory, you will have two guiguts perl files. The one that is just named "guiguts" is version 0.2.0, and can be deleted at this point. After you delete that file, you can either rename guiguts-0.2.4.pl to guiguts.pl or keep it as is to remind yourself which version you have. It will work just fine either way.

Now, let's test and see if guiguts comes up. If all has gone well before this point, it should.

Open the OS X Terminal application and enter these commands (substitute the appropriate version number if you have a version number associated with the guiguts you are using):

cd If your dp directory is in your home directory
cd dp/guiguts-0.2.8       Change directories to the guiguts directory inside your dp directory    
ls List the files inside your guiguts directory

or

cd /dp/guiguts-0.2.8       If your dp directory is at root level    
ls  

Note that it is fine to rename the guiguts directory and program to exclude the version number if you wish to. Adjust the command accordingly, depending on the name of the folder.


You should see

guiguts.pl or guiguts-0.2.8.pl     The Guiguts program--depending on which version you have.    
header.txt   The HTML header used by automatic HTML generation.
scannos folder containing the scanno search files

and many others.

Now type the command

perl guiguts.pl &

(This is how you launch Guiguts. Later there are instructions for creating a command file to bring up guiguts.) Very shortly a single large window should open with the title bar Guiguts.nn - No File Loaded (where nn stands for the version number).

Operate some of the menus. Select File> Open. The peculiar and rather Windows-like open-file dialog used by X11 appears. Figure out how it works: navigate to select some text file, for example header.txt in /dp/guiguts or ~/dp/guiguts ... for now, you can either choose File->Exit to quit guiguts, or leave it open. We will come back to it later.

Install Helper Applications

There are a number of applications that guiguts can link to that make a PPer's life somewhat simpler. These are called "Helper Applications"

Compile Gutcheck

In the Terminal window enter:

cd /dp/guiguts/tools/gutcheck

or

cd ~/dp/guiguts/tools/gutcheck

and

cc gutcheck.c -o gutcheck

These commands compile the gutcheck source program and leave the resulting executable program gutcheck in the gutcheck folder. Note: If you have not renamed your guiguts directory to not include the version number, substitute for guiguts, above, whatever the name of your guiguts directory is.

When you compile gutcheck.c, you will probably get several lines of warnings. As long as all you get are warnings, there shouldn't be a problem. Once the compile is finished, you should see, within the gutcheck directory, a file named gutcheck with no extension. This is your executable that you will link to when setting up the guiguts preferences.

gutcheck.exe is the precompiled Windows executable that comes with the installation--this can safely be deleted.

Select an Image Viewer

You use an image viewer to look at page images while editing page text in the Guiguts window. Guiguts will automatically call the selected viewer to show the current page when you click the See Image button.

In order to enable guiguts to call one of these programs, we will set up a script that we will link in as one of the helpers. Here are some of the choices.

The simplest way to create the script file is with guiguts (other options include TextEdit and TextWrangler, but instructions are given for guiguts). Choose which Image Viewer you wish to use, then, if you can, copy the two line script from the chosen section below using command-c. Bring the guiguts window to the front if it is still open, and clear the screen by using File>Close if there is another file open (or bring guiguts back up using the command above).

With a blank page open, paste the two lines into the open guiguts window using control-v . In X11, the control key is used for keyboard shortcuts, instead of the Mac default command key.

Note: Some people cannot copy from other applications and paste into guiguts. I have yet to figure out what the issue is and how to fix it. If this affects you, then you will need to type the appropriate command in as it appears below. If using a keyboard designed for a Windows system, you may need to use the Windows key instead of the control key.

There should be no space at the beginning of either line. The first line that should go in the file is the same for all three versions, and contains no spaces within the line.

Use File> Save As to save the two-line file in dp/guiguts or /dp/guiguts under the name launchimage.sh.

Using Preview

To use Preview:

#!/bin/sh
/usr/bin/open -a Preview "$@"

Among the advantages of Preview are that it is free, and presumably optimized for them Mac, as it comes with the system.

You can also start the program without opening an image, then go to File->Open, and choose a folder instead of an individual image. This will open all images in the folder, and do it much more quickly than selecting all the images in the folder and opening them that way. One word of caution, though--if you have several folders with images nested inside the folder you have Preview open, it will cheerfully open all the images in the nested folders, as well.

Using GraphicConverter

To use GraphicConverter:

#!/bin/sh
/usr/bin/open -a /Applications/GraphicConverter "$@"

My understanding is that GraphicConverter is a good program--however it is not free.

Using XnView

To use XnView:

#!/bin/sh
open -a /dp/XnView.app "$@"

Use the above if you put XnView.app in your /dp directory. If your dp directory is in your home directory, substitute ~/dp for /dp. If, instead, you put it in your system's Applications folder, substitute in /Applications

The recommended page viewer for Guiguts under Windows is XnView. XnView is a free program that under Windows, does much of what GraphicConverter does in OS X.

There are a couple of versions of XnView for Mac--one is an X11 program, and the other is not. The version available here is the X11 version, and expands to create a file named xnview.app; You can download an OS X version of XnView; it is an X11 application. The downloaded file expands to create XnView.app. Drag this to your dp folder.

This is the version of XnViewMP.app that I have. However, I have no opinion of it, because I have not tested it. It is not an X11 program. I checked just now, and found that the beta is up to .26, now, and available here. I haven't tested it, either. (Sharon 21:20, 16 June 2010 (PDT))

This page now contains a download of a new XnViewMP.app for the Mac which works with guiguts. Set the "Mode When Starting A File" to Normal in the General tab of Preferences. (2016-10-01)

Using Xee

To use Xee:

#!/bin/sh
/usr/bin/open -a /Applications/Xee "$@"

Xee is a "real" (non-X11) Mac OSX application for viewing images, it's freeware and it's fast.


Make image launcher script executable

Whichever image viewer you choose, the launchimage.sh shell script needs to be made executable. In Terminal, change to the directory in which you have placed the launchimage.sh script (probably dp/guiguts):

cd /dp/guiguts or cd ~/dp/guiguts     change into the guiguts directory
chmod 777 launchimage.sh   make launchimage.sh shell script executable.    

Now, find launchimage.sh in a Finder window, and select it (click once; you don't want to open it). Choose Get Info from the File menu. In the "Open with:" section, choose Terminal. You may need to scroll to the bottom of the list, and choose Other ..., and locate Terminal. It should be inside the Utilities directory in the Applications directory.

Once you've finished this step, you can test that it works by opening a Terminal window, navigating to the directory where launchimage.sh is located, and typing open launchimage.sh.

Later you will tell Guiguts that this file is the image viewer. When you click the See Image button in Guiguts, it invokes this file, which passes the open message to whichever image viewing application you chose to use, which displays the page in a new window.

Install Aspell

Guiguts uses the open-source program Aspell to perform spellchecking (an essential post-proofing step). Currently Guiguts requires version 0.5x of Aspell. Although this is not the latest version, it is still available; there is a link to it half-way down the linked page.

If you have Fink, and are comfortable using it, you may want to install Aspell 5 and dictionaries using it. However, only major language dictionaries are currently available. If you don't have Fink, and don't want it, do the following:

Download the file aspell-0.50.5.tar.gz and double-click it so that OS X unpacks it to form a folder aspell-0.50.5. Drag this to your dp folder (dragging to dp folder is not necessary, but you will have to cd into the directory in which it is located in order to install).

In your terminal window perform the installation (the following assumes that you have moved the aspell directory into the dp directory):

 cd /dp/aspell-0.50.5 or  cd ~/dp/aspell-0.50.5       change into the aspell directory
 ./configure These last three commands configure and install
 make   aspell in a system directory, not the local
 sudo make install    guiguts directory.

These commands produce voluminous output.

If the process worked, the aspell executable should exist; let's see:

ls -l /usr/local/bin/aspell

From the archive of Aspell dictionaries you need to download at least one dictionary. The following link: dictionaries is an ftp link.

Firefox and other browsers display it as a web page containing a list of sub-pages with two-letter names. However, if you are using Safari, clicking that link will open a new Finder window named dict containing many folders with two-letter names that stand for languages. Navigate in it and copy files from it just as you would in any Finder window.

If you will be Post Processing only English language books, you may just want to get the English dictionary. However for many people, French (fr), German (de), Italian (it) and Spanish (es) may also be necessary. There may not be dictionaries for every language, but there are a whole lot more there than most of us are likely to ever need.

When you are done, click the "eject" symbol to eject volume "dict."

Download at least one dictionary. The latest English dictionaries for Aspell 5 are in a single zip file aspell5-en-6.0-0.tar.bz2. Download this file and double-click it. OS X unpacks it to make a folder aspell5-en-6.0-0; drag this into the ~/dp folder.

For each set of dictionaries you download you must perform an installation. The process is just like the Aspell installation. Note that the export command below may not be necessary if /usr/local/bin is one of the locations searched for executable programs. It will not harm anything to do it, and it need only be done once per session.

If you have moved the downloaded folders to your ~/dp folder, type the first instruction below as is. Otherwise, substitute the proper path to the location where the aspell dictionary is located.

 cd ~/dp/aspell5-en-6.0-0   change into the appropriate dictionary directory. If your dp directory is at root level, remove the ~
 export PATH=$PATH:/usr/local/bin   Tell the shell to look for commands in /usr/local/bin (where aspell is installed) too
 ./configure   These last three commands configure and install
 make   aspell in a system directory, not the local
 sudo make install    guiguts directory.

After you have installed a dictionary you can trash its folder and the zip file from which it came.

Install Tidy

The open-source HTML Tidy program is a utility that reformats HTML and finds errors in it. If you have a Tidy executable, Guiguts will invoke it for you from the HTML Palette.

To get Tidy for OS X, visit the Tidy Project Page. Scroll down near the bottom where Mac OS X, dated 5 July, 2004, is listed. Click on that link to download a file tidy_mosx.tgz. Double-click this file and OS X unpacks it to create a folder named tidy_mosx containing two UNIX executables named tidy and tab2space. Drag the tidy_mosx folder to your dp/guiguts/.

Note that the guiguts folder contains a tidy folder with a "tidy.exe" file. This is a Windows executable, and should be deleted to avoid confusion--in fact, you can just remove the tidy folder altogether, as the version of tidy you will be using is in the tidy_mosx folder. As mentioned above, the download of tidy, once unzipped, also contains a unix executable called tab2space, which I have not seen mentioned as something that guiguts uses. See tab2space below for a discussion.

Tidy is also available from Fink.

Install Jeebies

There should be a jeebies folder within the guiguts folder that you downloaded earlier. If you don't see it there, download Jeebies.zip from this page and place it in the guiguts folder. Compile Jeebies in exactly the same way as you compiled Gutcheck above.

In the Terminal window enter:

 cd ~/dp/guiguts/jeebies      changes into the ~/dp/guiguts/jeebies directory within the user's home directory
 cc jeebies.c -o jeebies   compiles the program into a unix executable

These commands compile the jeebies source program and leave the resulting executable program, jeebies, in the jeebies folder.

Set up guiguts command script

To bring up guiguts, you can call it from the command line in Terminal every time you want to start it using the perl guiguts.pl & command from the guiguts directory, or you can set up an executable command script that you will put in your Dock and be able to start it with a mouse click whenever you want to.

In order to set up the command file, you need to know the exact name of the guiguts perl file and the exact path of the directory in which it resides. For this example, the guiguts directory is guiguts-0.2.8/ and the program file is guiguts.pl.

In a text editor (it can be guiguts or TextWrangler, or whatever you choose, as long as you can save it as plain text), type the following two lines (substitute the proper path components if they are not the same given here):

#!/bin/sh
perl ~/dp/guiguts-0.2.8/guiguts.pl &         the ~/ before the dp tells the computer to look in your home directory for the dp folder
(September 2016: leave off the final & for OS X 10.11)


Note: If you copy and paste from this file, make sure that the first line does not have a space in front of it. The two characters #! must be the first ones on the first line. Extra blank lines at the end of the file make no difference. Save this file as guiguts.command in your guiguts directory. If you have multiple versions of perl, and use other than the default to run guiguts, you will need to substitute the full name of the version of perl you use (e.g. perl5.8.9).

Two more things need to be done before you can use this to bring up guiguts.

1. In a terminal window, make sure you're in the directory with the guiguts.command file. Type

chmod 755 guiguts.command         makes the command file executable        

2. Find guiguts.command in a finder window. Click on it once to select it. Go to the File menu and choose Get Info or use the keyboard shortcut cmd-I. Under the Open with: menu, choose Terminal.app or Terminal, depending on whether your system is set up to show extensions. Close the Get Info window.

Now, from a Finder window, you can drag it to your dock. Note that you cannot put it in the top part of the Dock where you keep applications, but must put it in the bottom part where you can keep files and folders. I keep mine as the top item in this section of the dock.

If guiguts doesn't launch properly from the dock, try changing the "Open with:" program from "Terminal" to "X11".

Set up Helpers

You need to tell Guiguts where to find all these helper programs. Start Guiguts and select Prefs> Set File Paths> Locate Gutcheck Executable.

Guiguts MI paths.png

A file-open dialog appears. Browse to find the gutcheck program you compiled earlier. It should be ~/dp/guiguts-0.2.8/gutcheck/gutcheck. Click Open.

Select Prefs> Set File Paths> Locate Jeebies Executable. Browse to find ~/dp/guiguts-0.2.8/jeebies/jeebies. Click Open.

Select Prefs> Set File Paths> Locate Aspell Executable. Browse to find /usr/local/bin/aspell. Click Open.

If you downloaded Tidy, select Prefs> Set File Paths> Locate Tidy Executable. Browse to find ~/dp/guiguts-0.2.8/tidy_mosx/tidy. Click Open.

Note: If you can't find an executable, it might be in a different place. For example, if you got a program via Fink, it will probably be in /sw/bin. Type "which aspell" (or jeebies or tidy or gutcheck) at the Terminal prompt to find out where it is.

Select Prefs> Set File Paths> Locate Image Viewer Executable. Browse to find one of the files you created, such as ~/dp/guiguts-0.2.8/launchimage.sh to launch Graphic Converter (or Preview or XnView), and click Open.

Your Guiguts installation is now ready to use!

Know the zip Utility

When you download an archive compressed with zip (the Guiguts distribution folder or a folder of text or images from PG), the browser may automatically unzip it for you. Or if it does not, you can always double-click the .zip file and OS X will unzip it then. No separate unzip utility is needed.

You will need to be able to zip files at several points, for Smooth Reading (SR), for uploading to PPV, and also to upload to PG, once you have earned Direct Upload (DU) privileges.

Because the OS X Finder's Compress option from the contextual menu (right- or control-click) has no way of excluding Mac specific invisible files, which files need to be removed before uploading anything either to DP or to PG, you need another option.

One way to create a zip archive is to use the zip command in the command line in a Terminal window. Make sure you're in the directory containing the files you wish to zip, and type the command zip file.zip [list of files to zip separated by spaces]. The list of files can contain multiple types of files, and can also include wildcards. For instance zip file.zip *.txt *.png is a legitimate command (it will zip all of the files in the current directory with .txt or .png extensions into a zip named file.zip). One other thing that, as a Mac user, you might want to be aware of, is that zip -l [zipfilename.zip] [files to zip] will replace all Unix line endings (LF) with Windows line endings (CRLF)--which is important for all of Smooth Reading, PPV and PG. (zip -ll converts the other way.) Warning: there are multiple ways of converting line endings. Make sure that you only use one.

See also Creating zip archives on the Mac for a more in-depth look at some utilities that are available for creating clean archives on the Mac.

Get X11 to Use DPCustomMono2

The Unicode font we now have available at DP is DP Sans Mono.

If you're going through this install process on a clean install of the Operating System, you probably don't have DPCustomMono2 installed yet. If you would like to be able to use it in guiguts, go to the linked wiki page and download and install it per instructions, then continue with the following instructions

The following instructions are only for 10.5.8 and 10.6.1 or later. Edits that include info about 10.4 have been moved here temporarily, pending updating the 10.4 gg install wiki.

To introduce X11 to DPCustomMono2:

  • Open a new Finder window and navigate to wherever you stored DPCustomMono2.ttf—either /Library/Fonts or Library/Fonts in your home directory.
  • Open a new Finder window, select Go > Go To Folder, and enter /usr/X11/lib/X11/fonts/TTF if you are running Mac OS X 10.5 or later.
  • Hold down the option key and drag (copy) DPCustomMono2.ttf from one window to the other.
  • In 10.5.8, Finder tells you that TTF cannot be modified, but offers the choice "Authenticate." Choose that and give your password. The file is copied. In 10.6.1, Finder simply brings up an authentication dialog box with your username in it, and prepares to copy once you've entered your password.

Now in a terminal window, type in these commands:

 cd /usr/X11/lib/X11/fonts/TTF   Move working directory to the TTF fonts directory for X11
 sudo mkfontdir   These two commands set things up so that DPCustomMono2
 sudo mkfontscale   is recognized as a valid font.

After quitting and restarting the X11 application, you should find DPCustomMono2 as an option in the Guiguts font preference dialog. If you still don't see it in the fonts menu, try logging out and back in again or rebooting.

Finishing Up

That completes a working Guiguts installation for OS X. If you normally run your user account with standard (rather than administrator) privileges, you can switch back now. You should look at the Setup topic to complete setting your work preferences.

And a final reminder--make sure that your dp directory is part of your backup process. If it is in your user directory, it is probably backed up automatically, but if you created a /dp folder at root level, this will not be backed up unless you specifically make sure that it is.


Troubleshooting

If you have problems that you think may be common gotchas, please post them here. This wiki article is on my watchlist, but it wouldn't hurt to post in the Help installing guiguts on Mac OS X forum topic, also. The goal of this section is to have a list of common problems that crop up in the install process, for whatever reason (mostly instructions not detailed enough (grin)).


Other useful applications to have for post processing

Information about TextWrangler

TextWrangler is a free text editor, a stripped down version of Bare Bones Software's BBEdit program, which has a lot of functionality to it. It is quite a bit more flexible for purposes of Post Processing than is Apple's own TextEdit, because you can change encoding type and line endings with pull-down menus at the bottom of the text window. This is very important if you are working on a Mac, because before you upload any file back to DP, or to PG, you must make sure that your file has Windows style (CRLF) line endings, not Mac or linux line endings! Using TextWrangler is an easy way to check this.

Information about GraphicConverter

You may already have the excellent image viewer and converter, GraphicConverter, by Lemkesoft. Note that while this is an excellent program, and an inexpensive one, it is not free.

If you are not familiar with it, and also need a program that will allow you to process book illustrations, and don't already have another image processor, you might want to consider getting GraphicConverter. You can use it as the page-viewer from Guiguts. You can also use it on its own to process book illustrations, either singly to crop, align, and adjust contrast, or in batch mode, for example to make scaled-down copies of every image in a folder. Tip: When you are looking at a page image in GraphicConverter, typing cmd-right-arrow causes GraphicConverter to open the next file in name sequence from the same folder, in the same window. Typing command-left-arrow opens the preceding image. Thus once you have one page image open in GraphicConverter, you can step forward and backward through the book.

Information about Preview

(((Check this out. I tried it, and I don't think it worked the way I expected it to: Preview has a useful option that makes it open page images at a good zoom factor. Launch Preview and select Preview> Preferences. Click the Images button. Set the choice Default image size: Scale large images to fit window. Also set the option "Respect image DPI...")))

If you choose Preview as your page-viewer, you can work in either of two ways. The simple way is to let Guiguts call Preview for any page you want. You click the See Image button; Guiguts calls Preview; Preview opens the page image in a new window.

However, instead of asking guiguts to open the images using Preview, you can navigate to the folder containing the images and select all of the images that you want opened, then either control- or right-click in the window containing the images and choose Open with Preview or choose File->Open with->Preview from the Finder's File menu. This can be done either before or after opening guiguts.

Preview takes a deep breath and opens all the pages of the book. The pages appear in the thumbnail drawer and you can rapidly scroll through them. Cmd-up/down arrows step through the pages one by one. Now you can view any page without clicking the Guiguts button; just bring Preview to the front and click on the page thumbnail. However, you can also click on the Show Image button in guiguts, and it will navigate to the proper image among the open images in Preview--either way works.

Information about XnView

XnView has many features and a plethora of options that can be set. Possibly you can find a combination of options that make it work smoothly as a page viewer from Guiguts. (Update this section if you do!)

tab2space

tab2space appears to be a handy little unix command line utility which will:

  • set line ends to CRLF (very, very important for Mac PPers)
  • set line ends to CR (Classic Mac OS)
  • set line ends to LF (Mac OS X and Unix)
  • preserve tabs
  • replace tabs with the specified number of spaces.

If you're interested in using it, keep it in your guiguts folder (as a good place to keep it), cd to the guiguts folder, and type tab2space -h to get the help screen for exact syntax.

Note to self: test out tab2space.

about fonts

Edit concerning installing DPCustomMono2 on Tiger (10.4). I tried the instructions in the table on 10.5, and they did not work, so I've gone back to the original version for 10.5 and 10.6 (srjfoo--20091012) To introduce X11 to DPCustomMono2:

  • Open a new Finder window and navigate to wherever you stored DPCustomMono2.ttf—either /Library/Fonts or Library/Fonts in your home directory.
  • Open a new Finder window, select Go > Go To Folder, and enter /usr/X11R6/lib/X11/fonts/TTF if you are running Mac OS X 10.4.
  • Hold down the option key and drag (copy) DPCustomMono2.ttf from one window to the other.
  • The Finder tells you that TTF cannot be modified, but offers the choice "Authenticate." Choose that and give your password. The file is copied.

Now in a terminal window, type in these commands:

 cd /usr/X11*/lib/X11/fonts/TTF   Move working directory to the TTF fonts directory for X11
 sudo /usr/X11R6/bin/mkfontdir $PWD   These two commands set things up so that DPCustomMono2
 sudo /usr/X11R6/bin/mkfontscale $PWD   is recognized as a valid font.