GUIGUTS

Installing Under Linux

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 Install: Linux Check basic stuff Perl modules Make DP Folder Install Guiguts Compile Gutcheck Image Viewer Install Aspell Install Tidy Set Up Helpers DPCustomMono2 Update Guiguts First-Time Setup   PP Workflow Checklist Hotkey Reference Regex Reference Topical Index

Because every Linux distribution has a slightly different selection of commands and a different kind of software package manager, the following writeup is a generic guide. Expect details not to match your Linux. Ask specific questions in the PP forum. This forum posting is about Guiguts on Linux; start there.

Step One: Verify Basic Software

Let us assume you have a basic working installation of Linux, including X-windows and some desktop package such as KDE or Gnome. You have working internet access of course, or how would you be using PGDP? But this is preferably broadband access (DSL or Cable) because you do large downloads and uploads, both while installing and later, while postproofing.

Perl and Cpan

Your installation should already include perl. Check for the existence of /usr/bin/perl. Look in /usr/lib for a directory full of perl modules, for example /usr/lib/perl5/5.8.5/ might contain many files of type .pm including, most importantly, CPAN.pm.

The file CPAN.pm is the core of a system for downloading and installing open-source software written in Perl; you can read about it at Cpan.org.

If your system lacks Perl, you need to install it. It should be a single "package" which you can install using your "package manager." Every Linux has a software package manager of some sort; it might be called apt or rpm or something else.

Find out how to use your package manager to install a current release of the package called Perl. For example in a Debian system, the command (issued as root) would be
apt-get install perl

If you've never installed a software package, ask for help in an online forum for users of your Linux distribution.

Zip and Unzip

Your system likely already has zip and unzip utilities. The unzip command is used in the process of installing downloaded software, and also when downloading a new book to process. The zip command is used to compress a book for uploading. Test for their existence with the command which unzip. It should produce a response like /usr/bin/unzip. The command which zip should produce a similar response. If instead the result is "no unzip found in..." you need to obtain these commands.

Some systems may contain a command gzip (Gnu zip). This is probably usable for unpacking downloaded files. It cannot be used for compressing a book for upload. You must have plain zip for that.

If you lack unzip, you can download a copy from this site. The companion zip program is on another page of the same site.

Unix-Dos Line End Conversion

The ASCII text files kept at PGDP are in DOS/Windows format, which means that each line ends in the two characters CR and LF. Under Unix and Linux, lines of text files end with LF only. Conversion from the CRLF to just LF is handled automatically by Guiguts when it loads or imports a file. However, it saves the edited file with LF endings. If you upload this it might or might not look wrong to the PPVer.

Simple utilities to convert between the two conventions are included in most Linux systems; their names are dos2unix (DOS-to-Unix conversion) and unix2dos (vice versa). Try which dos2unix to see if you have them. If not, use your package manager to install them. Alternatively, download the free Tofrodos utility.

Step Two: Install Perl Modules

Guiguts is written in the Perl language but it depends on a number of modules that are not normally included in the default Perl installation. You use the CPAN system to get them. CPAN is in effect, a package manager written in Perl, devoted to installing packages written in Perl.

Open a terminal window and su to root. Issue the following command:

You will be asked a bunch of questions; the defaults are usually fine. When the moderately lengthy installation of LWP completes, continue with 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; don't interrupt them.

When that finally completes, continue with:

This pops up a test widget—play with it, then close it.

Step Three: Make a DP Folder

For consistency with the other installations, you should make a new folder named dp at the root level of the disk:

When these are complete, logout of the root ID.

Step Four: Install and Test Guiguts

Download guiguts.zip from its home page. Unzip it. Move the resulting folder named guiguts into the /dp folder.

Test Guiguts

Guiguts should be ready to run now. Let's see.

There should be a moment of disk activity and then a single large window should open, looking much like the one shown here.

If instead Perl complains about "Can't find (something) in @INC" use CPAN to install what's missing. For example, if the message is "Can't find Tk/Toolbar.pm" then something went wrong in the earlier step

The rule for converting a name from the "Can't find" message for use in the "install" command is: change a slash to double-colon ("Tk/Toolbar" becomes "Tk::Toolbar"); drop the suffix ".pm"; retain capitalization exactly.

Step Five: Compile Gutcheck

Guiguts ships with a program called gutcheck in source form. The following commands compile this to an executable.

Step Six: Set Up an Image Viewer

In order to view page images out of Guiguts, you need to find a Linux program that will take as its argument the path to a .png file and display that image on the screen. It helps if you can configure the program to:

• Always open its window at the same size and zoom factor
• When called a second time, re-use the existing instance of the program rather than launching a new instance and window.

For Windows, the free XnView program meets the need very nicely. Although you can download a Linux version of XnView, it does not behave as nicely as the Windows version. Depending on how you set its options, it always opens the page image too large or too small, so every time you display a page you have to reposition and resize and rezoom the window.

Many Linux distributions come with image viewers by default. The Gnome desktop usually contains ee (electric eyes), while the KDE desktop environment should contain Kview. Some other free viewers are:

• qiv, which definitely has command parameters to set the zoom percent and window size.
• kuickshow
• GQview

For a long list of these and other open-source image viewers see this page.

Select an image viewer and study its documentation so you know how to launch it from the command line. Download a couple of page images from PGDP (you can get to the page images from any book's project page). Try issuing a series of commands, like

This simulates what Guiguts will do when you click on the Page Image button twice in succession. If you find that you need certain command parameters (besides the path to the file) to make things look right, you can create a tiny shell script to launch the viewer with these parameters. It might read something like this: Call it /dp/viewer.sh and make it executable (chmod 777 viewer.sh).

Step Five: Install Aspell

Many Linux installations have the Aspell spelling checker installed by default. Use which aspell to test for it. If it doesn't exist, use your package manager to install the Aspell and at least the English dictionaries (other dictionaries if you expect to post-process books in other languages).

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 Linux visit the Tidy Project Page. Scroll down near the bottom where "Linux/x86" is listed. Click on the link to download tidy_linux_x86.tgz. From the file suffix (.tgz) we can tell this is Gnu-zipped; you need the gunzip program to expand it. Do so; it results in a folder bin containing a single executable tidy. Move this executable to the /dp folder (or to /usr/bin if you prefer).

Step Six: Set Up Helpers

You need to tell Guiguts where to find the programs that it will call. Start Guiguts as before, and select Prefs> Set File Paths> Locate Gutcheck Executable.

A file-open dialog appears. Browse to find /dp/guiguts/gutcheck/gutcheck. Click Open.

Select Prefs> Set File Paths> Locate Aspell Executable. Browse to find the aspell executable (the command which aspell will show its path). Click Open.

If you downloaded Tidy, select Prefs> Set File Paths> Locate Tidy Executable. Browse to find /dp/tidy (or /usr/bin/tidy if that's where you put it). Click Open.

Select Prefs> Set File Paths> Locate Image Viewer Executable. Browse to find the executable of the image viewer you think will work best. (You can change this choice later.) If you prepared a shell script, browse to find /dp/viewer.sh instead. Click Open.

Your Guiguts installation is now ready to use. Turn to the setup page for final setup.

Optional: Install DPCustomMono2

The DPCustomMono2 font is very helpful in spotting common OCR typos. Possibly you have installed it already so you could use it when proofing the 400 pages you've done before becoming a post-proofer. If so, no further work should be required to use it from Guiguts.

If you have not yet installed the font, see this forum topic for directions (for Windows) and a link to the font file. Download it and use the facilities of your system to install the font.

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 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 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
• The header.txt file, which some users modify to change the look of books

To update Guiguts, use your graphical file browser (e.g. KDE Konqueror) to open the old and the new guiguts folders in separate windows. 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 to the old folder so they replace the older versions.

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 before.

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)