GUIGUTS

Installing Under Mac OS X

Overview The Interface Explored File Open/Save/Include Navigating in the File Editing Text Search and Replace Apply Fixup Remove EOL spaces Fix Page Separators Apply Word Frequency Apply Gutcheck Apply Spellcheck Fix Sidenotes Fix Poetry Line Numbers Rewrapping Fix Footnotes Fix ASCII Tables Adjust Page Markers Generate HTML Alphabets and Codes   Install: Windows Install: Mac OS X X11 Developer Tools LWP & Tk DP Folder Guiguts Gutcheck Image viewer Aspell Tidy File Paths Zip Utility DPCustomMono2 Updating Guiguts Install: Linux First-Time Setup   PP Workflow Checklist Hotkey Reference Regex Reference Topical Index

Apple's OS X is basically a UNIX system; as such 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 spelling checker, and the Tidy utility. These items are not installed in your OS X system by default, but you can add them. In the process you will need to become something of a UNIX expert.

The following page covers two topics: first, the lengthy process of installing Guiguts and its open-source environment for the first time. A much shorter topic at the end tells how to update Guiguts for a new version.

These instructions are based on OS X 10.4 "Tiger." The process in Tiger is somewhat easier than in the older OS X 10.3 "Panther." If you are still using Panther you might postpone this installation until you are ready to upgrade to Tiger.

Preparation for UNIX

Open-source installations require you to issue UNIX commands. Some of these are "privileged," that is, issued under the authority of a system administrator, so that files can be written into system-owned folders.

The following steps are for the person who has never used the UNIX command-line. If you have already ventured into the open-source world, for example using the Fink and Fink Commander tools, follow along to make sure you have all the right environment variables set.

Using Terminal.app

Launch the program Applications> Utilities> Terminal.app. Enter the command

There are the same files you would see if you opened a Finder window and clicked the cute little house icon.

Open the menu item Terminal> Window Settings... and from the popup menu, select Buffer. Click the choice for Unlimited Scrollback. Now there will be a complete transcript of everything that happens in a Terminal window. You can select text in the Terminal window and paste it into other programs; for example, you can email a transcript of a failed installation to another user for help.

Optional fun: in the Window Settings, pop up the Color choice. Set the color of text to white; set the background color to a nice deep blue or purple; and set the Transparency slider to the second or third division. Now your Terminal windows look like blue glass.

Being an Administrator

In most single-user OS X systems, there is only one user defined; that user is automatically logged-in when the system boots; and that user is also an administrator. Are you, in your normal work as a post-proofer, an administrator? Launch System Preferences and click on Accounts:

Look at the account name under which you will be doing your Post-Proofing with Guiguts. That account needs, at least for the duration of these installations, to have the magic word "Admin" under it. If it does not,

• Log in now to a name that is an Admin.
• Click the padlock icon and when asked, enter the admin password,
• Select the account under which you'll be using Guiguts.
• Click the button "Allow user to administer the computer." (Under 10.3 Panther, click Security to see this button.)
• Log out and log back in as that user.

The point of this exercise is to make sure that all the files we create are owned by the Guiguts user. To do that, the Guiguts user has to run the following the steps. Otherwise the Guiguts user will have irritating problems later with file ownership.

The bash Profile

When you enter commands in a Terminal window you are entering them to a command shell. There is more than one of these, but if you've not used the terminal before, you almost surely are using the default bash shell. (If you know enough UNIX to have set yourself up with a different shell, you know all this.)

One service of the shell is that it maintains a set of environment variables which you can think of as a set of extra input values to any program you run. There are a few of these environment variables that are not set by default, and that need to be set for all normal use. You can arrange for all the needed values to be set automatically whenever you open a new terminal window, by creating a file named .profile (note the leading dot) in your home directory. Enter the following two commands in your terminal window:

The TextEdit application pops up with an open window named .profile. Into that window paste the text from this page. Save the file. Quit Terminal and restart it. The command prompt should now look like [12:58 ~].

If you know UNIX and have set up to use ksh or tcsh instead of bash, review this page and make sure your login sets the same items in some fashion.

Step One: Install and Test X11

Guiguts uses the Tk interface kit to create its user interface. It would be nice if Tk supported the OS X Aqua window manager but it does not; it uses instead the X window system, an older window manager that is not installed in OS X by default. See if you already have X11 installed: look in the Utilities folder in the Applications folder for a program named X11.app. If it's there, proceed to testing it.

Installing X11

X11 is one of the optional packages in the Tiger distribution. If you are installing Tiger for the first time, find X11 by clicking Customize instead of Easy Install. The X11 package is the last item in the list. Select it to include X11 as part of your Tiger ugrade.

If you have already installed Tiger, mount the Tiger DVD and scroll down its window until you find Optional Installs package:

Double-click this to get an installer window listing various packages. Open the "Applications" group to see X11. Select only X11 and click Upgrade to install X11.

Testing X11

Double-click the X11 application. After a few moments a very plain little window titled xterm opens. This is a UNIX terminal; enter a command like ls -l to verify it's working.

The X11 environment lets you start multiple programs, each using X11 to create its user interface. Enter the command

The xclock program creates its window and runs. 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 xclock terminates. Later you will start Guiguts in just this way.

Step Two: Install Developer Tools

You need Apple's Developer Tools package 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.

Mount the Tiger distribution CD (see picture earlier) and double-click the folder Xcode Tools, and in it, double-click the package XcodeTools.mpkg. This brings up an installer in which, by clicking Customize, you can select the minimum tools you need:

You need the Developer Tools, both versions of gcc (compiler), and the first three Software Development Kits (SDKs). Only select any other components if you are actually planning to develop software.

Step Three: 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 or CPAN. CPAN is not only a software archive and a website, but a standard extension to Perl. Perl and CPAN are both included automatically in OS X.

To install Perl extensions we will invoke cpan in a terminal window. We will use the OS X terminal because, unlike the Xterminal, it keeps a scrolling history of commands.

Some of the installations that follow expect that X11 will be running when they perform functional tests. So start X11 and leave it running in the background.

Start and Configure CPAN

In your terminal window, start CPAN in privileged mode as follows:

This should produce a prompt of cpan>.

If this is the very first time you have ever used cpan, you may be prompted to enter a rather lengthy manual configuration process. Open this commented transcript in a separate window and proceed through the interrogation.

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 of quit, and restart it later with sudo cpan.

Install Software

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

The following moderately voluminous output should look like this commented transcript, and especially, should end in /usr/bin/make install -- OK.

Now the big one: the Tk bundle of code that lets Perl programs use the Tk user interface package. Guiguts uses this for its entire interface.

A very lengthy process ensues in which much data is downloaded, programs are compiled, and a whole suite of tests runs. The tests pop up lots of little X-windows. Most go away by themselves. A few are interactive; you need to click on them somewhere to finish them. Here is a commented transcript. If your installation does not end with /usr/bin/make install -- OK see the note in the transcript under the word "FINALLY" and then contact the author.

The following commands install three smaller modules that Guiguts uses:

The install process for each command is like, but much shorter than, the process for Tk. On completion of the last, terminate CPAN with a quit.

Step Four: Create a DP folder

Guiguts and friends work best when file pathnames are short and simple, like /dp/pp/bookname (note the leading slash, indicating the folder is at the top level of the boot drive—not in your user folder). Enter these commands to make a top-level folder for your PGDP work.

Double-click your boot drive to open a new OS X finder window. The new dp folder should be at the top level, just after Developer. You might make an alias of this folder and put it on you desktop for convenient access.

Also use the Finder to make a new folder pp (for "post-proof") inside /dp. This is where you can keep your projects: each book will be a folder /dp/pp/bookname.

Step Five: Install and Test Guiguts

Go to the Guiguts site and click on the link to download guiguts.zip. Double-click the downloaded zip file to unpack it. Drag the resulting folder named guiguts into the dp folder. Then you can throw away the zip file.

In a Terminal or an Xterminal window,

You should see guiguts.pl (the Guiguts program), header.txt (the HTML header used by automatic HTML generation), the scannos folder containing the scanno search files, and others.

Use the Xterminal window (so you know that X11 is up) and issue the commands

(This is how you launch Guiguts.) Very shortly a single large window should open with the title bar "Guiguts.nn - No File Loaded." 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 from /dp/guiguts. Leave Guiguts running and bring the Xterminal window to the front once more.

Step Six: Compile Gutcheck

In the Xterminal window do:

These commands compile the gutcheck source program and place the resulting executable program gutcheck in the gutcheck folder.

Step Seven: Select an Image Viewer

Using GraphicConverter

You may already have the excellent image viewer and converter, GraphicConverter. If not, consider using it to display and manage PGDP image files. 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.

Download GraphicConverter and, following its instructions, just drag the application GraphicConverter into the Applications folder.

Now, to make it possible for Guiguts to invoke GraphicConverter when you want to view a page image, you need to create the following, two-line file:

The simplest way to create the file is with Guiguts. Copy the pair of lines above with command-c. Bring the Guiguts window to the front. If there is a file loaded, use File> Clear to clear it. In the world of X11, copy/cut/paste are control-keys, so click in the Guiguts window and use control-v to paste the copied lines into the Guiguts window.

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

In the Xterminal window, make the file executable:

When you click the See Image button in Guiguts, it sends the open message to GraphicConverter, which displays the page in a new window. When you are looking at a page image in GraphicConverter, typing cmd-right-arrow causes GraphicConverter to open the next file in sequence 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.

Using Preview

An image viewer is included with OS X, the Preview application. You can use Preview as your Guiguts image viewer by preparing the file launchgc.sh as described above for GraphicConverter, but with the following contents:

Preview, in Tiger, 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.

Here's another way. Before you start Guiguts to work on a book, launch Preview. Select File> Open. Navigate to the pngs folder of the book. In the open dialog, select all the pages of the book (click any one, then type cmd-a to select all) and click Open. 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. When you do this in Tiger, if you click Guiguts's See Image button, nothing will happen. It sends the "open file" message to Preview and Preview says, I already have that file open, and does nothing.

Using XnView

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. You can download an OS X version of XnView; it is an X11 application. The downloaded file expands to create a folder named viewer. Drag this folder to your /dp folder. You can launch the program from the Xterminal window with the command /dp/viewer/xnview &.

Unfortunately there does not appear to be any way to control the window size, window location, or zoom factor with which XnView for OS X opens an image. If you use XnView for your viewer you will have to move, resize, and re-zoom every image you display. (In fact, from the lack of change on the program website, it appears that XnView may be dying or losing its maker's attention.)

Step Eight: 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; this is a link to the zip file.

Download that file and double-click it so that OS X unpacks it to form a folder aspell-0.50.5. Drag this to your dp folder.

In your terminal window perform the installation. Interestingly, this installation will not work in Tiger with the new, gcc 4.0 compiler; you must switch to the older gcc 3.3. Here are the commands to issue:

These commands produce voluminous output; here is a commented transcript to compare. If the process worked, the aspell executable should exist; let's see:

From the archive of Aspell dictionaries you need to download at least one dictionary. The following link: dictionaries is an ftp link. With most browsers you navigate it as a web page, clicking on a filename to download it. if you are using Safari, clicking it 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 as you would in any Finder window; 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:

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

When you finish installing Aspell and its dictionaries, you should probably put the gcc compiler default back to 4.0.

Optional: 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" is listed under "Other Builds." Click on that link, which downloads a file tidy_mosx.tgz. Double-click this file and OS X unpacks it to create a folder named bin whic contains a single UNIX executable named tidy. Drag the tidy executable to /dp.

Step Nine: 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.

A file-open dialog appears. Browse to find the gutcheck program you compiled in step 6, which should be /dp/guiguts/gutcheck/gutcheck. 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/tidy. Click Open.

Select Prefs> Set File Paths> Locate Image Viewer Executable. For use of GraphicConverter or Preview, browse to find the file /dp/guiguts/launchgc.sh that you created, and click Open. For use of XnView, browse to find /dp/guiguts/viewer/xnview and click Open.

Your Guiguts installation is now ready to use!

Step Ten: 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.

When you are going to upload a finished book, the PPVer expects to receive the folder of completed files compressed with zip. The OS X Finder offers a convenient option: File> Create Archive of... (also available by control-clicking any folder). The Finder uses Gnu Zip (gzip), whose output is acceptable to some PPV persons, but not to all. If you use this method to create your upload, be sure to document "compressed with gzip" in the comments field of the upload page.

If the PPVer says they couldn't open your uploaded archive, you need to use the basic Zip utility, which is run from a command line. The zip command is installed as /usr/bin/zip as part of the Developer Tools package in Step Two. Suppose you have a folder /dp/pp/projectID406d17b43e9c9 containing a book ready to upload. The following commands create a zip file:

The options -rv9 say "descend into subfolders, display verbose results, use highest compression factor." The next parameter is the name of the zip archive you want to create. The final parameter is the name of the folder to be compressed.

Optional: Get X11 to Use DPCustomMono2

The DPCustomMono2 font is very helpful to proofing. No doubt you have installed DPCustomMono2.ttf into either /Library/Fonts or Library/Fonts in your home directory, so you could use it when proofing the 400 pages you've done before becoming a post-proofer.

You might imagine that since OS X and all your different browsers can access this font, an X11 program should also. Well ha, ha! X11 has an amusing surprise for you! It doesn't.

The font technology of this current version of Apple's X11 is completely independent from the font technology used by the rest of OS X. X11 has its own font collection and knows nothing about the fonts managed by OS X.

If you really want to post-proof using DPCustomMono2, set aside a couple of free hours and follow the instructions in this post, after which you can pass yourself off as a real UNIX geek. "Oh, I was just editing my dot-x-init-r-c file..."

Updating to a New Version

Thundergnat often updates Guiguts with fixes and new features. You can find if there is a new version by selecting the Guiguts menu option Help> Check for Updates. When you learn that a new version is available, go to the Guiguts site and click on the link to download guiguts.zip. (Alternatively, you may see a link to the new version in a forum posting.)

The downloaded guiguts folder is basically a duplicate of your /dp/guiguts folder except that it lacks your versions of two, and possibly three, files that you have modified:

• The settings.rc file (described here), which contains your preference settings including the paths you have set to the helper applications
• The gutcheck executable you compiled
• You may have modified the header.txt file to change the look of books

To update Guiguts, open the old and new guiguts folders in the Finder. Select all the files in the new folder except for the gutcheck folder (and except for header.txt, if you have modified it). Drag the selected files and drop them onto the old folder. When the Finder asks if you want to replace a file, click Yes To All. This sequence updates the distributed files without replacing settings.rc or the gutcheck folder.

Compare the modification dates of the new and old gutcheck.c files. If the one in the new folder has been updated, replace it also and compile it anew as you did in step Six.

If you had modified header.txt, open the old and new versions in an editor, figure out what has changed, and resolve any updates so that the new version contains the class-names on which Guiguts depends with your styling.

(Prior) Guiguts and this manual are protected by the Perl Artistic License (Next)