PPTools/Guiguts/Guiguts Manual

From DPWiki
Jump to navigation Jump to search





Guiguts is a free software, cross-platform tool designed to speed and simplify every phase of post-processing an e-text. This manual covers the current version of Guiguts, with some notes about differences between this version and its predecessor. For earlier versions, see Guiguts 1.0 and Guiguts 0.2. See the Guiguts PP Process Checklist for a suggested post-processing procedure using Guiguts.

At heart, Guiguts is a simple text editor. You open a file; you scroll the text to view it; you change the text by selecting, cutting, pasting and overtyping using familiar commands and keystrokes; then you save the file.

Under this modest exterior, Guiguts has many special features designed to speed your work as a post-processor, such as built-in searches for stealth scannos (the common OCR text errors), automatic moving and renumbering of footnotes, and automatic generation of HTML that complies with Project Gutenberg standards.

What's New in Guiguts

HERE is a summary of the new and changed features beginning with Guiguts version 1.1.0 in August, 2020. The "CHANGELOG.MD" file included with Guiguts lists every change and bug fix since the initial release of Guiguts 1.0.0 in 2003 or 2004.

Purpose of this Manual

This manual's objective is to explain what Guiguts does, not how to post-process with it. For such information, please see the resources listed below.

The manual is organized based on the premise that there are three main phases to post-processing. The first one corrects errors, makes the text consistent, and produces a result that will be used by the other two phases. The second phase converts a copy of the first phase results into the final Plain Text that will be published. The third phase converts another copy of the first phase results into the final HTML document that will be published.

Other Resources

Downloading and Installing Guiguts

  • To download the current version of Guiguts, please visit the Github releases page.
  • To install Guiguts after downloading it, see the Guide to Installing Guiguts. After installing Guiguts, but before attempting to run it, follow the instructions to install Strawberry Perl and the additional Perl Modules.

Summary of Post-processing Workflow

  • Before you start using Guiguts
    • on your computer, create a folder to contain everything for this project.
    • download the text and image zips for the project, and unzip them into appropriate folders.
    • prepare the illustrations, including a cover. You won't need them until you are creating the HTML version of the book, but if there are missing or unusable ones, or they don't match what you will find in the text file you downloaded, you will want to resolve those discrepancies before spending (or wasting) your time preparing the text.
      • Illustrations will look better if you calibrate your monitor and occasionally clean the screen.
      • Other people may be able to help you prepare some illustrations or covers, if you ask in the Illustrators' Forum.
  • Using Guiguts
    • open the project's text file in Guiguts.
    • configure page labels so the image names in the Rounds are matched with the page numbers printed in the book (optional, but recommended).
    • correct errors, organize the text, resolve inconsistencies in what the author wrote, what the publisher printed, what the proofreaders did, and how the formatters marked various elements and aligned tables. Generally, these steps will take at least one third of the total time you spend on the project.
    • finish preparing the text for conversion to the two final versions of the book: Plain Text and HTML.
    • make a separate copy for later use in preparing the HTML version.
    • process the current copy into the final Plain Text version.
    • open the copy you saved for use in preparing the HTML version.
    • prepare it for conversion to HTML.
    • convert it to HTML.
    • process the HTML copy into the final HTML version. Generally, these steps will take at least one third of the total time you spend on the project.
    • make sure the HTML version also works well on handheld devices.
  • Other than later corrections and improvements to what you've done, the post-processing steps after this do not use Guiguts and are not addressed here.

Guiguts Main Window

Guiguts opens a single document window where you will do most of your post-processing, and (at least in Windows) it also opens a command-line window that is only used by the Perl interpreter that is running Guiguts. Normally, you will ignore that command-line window, and keep it minimized.

Guiguts will only edit one document at a time. However, it is possible to launch multiple copies of the Guiguts program and open a different document in each one. The title bar of the window reflects the current file. You view, edit, and scroll the file in the window in ways that are familiar to anyone who has used a text editor. You can resize, minimize, or move the window on the desktop using the mouse, using the normal methods of your operating system.

When you want to close Guiguts, do it from the document window. That also closes the command-line window.

NOTE: Don't close the command-line window unless Guiguts stops working. If you close the command-line window, the Guiguts document window will close immediately, without any chance to save the changes you might have made in it.

Guiguts main window

Guiguts functions are initiated from the menu bar or by clicking in the status bar or toolbar, or with keyboard shortcuts. Most menus can be "torn off" and set on the desktop as dialog windows; see Tear-off Menus below. You also can access what's on the menu bar by pressing Alt and then one of the letters underlined on the menu bar.

Menu Bar

The links immediately below and in the Table of Contents lead to explanations of each function of each menu. Some of those functions also are on the Status and Tool bars, and on Function keys and keyboard shortcuts.

Status Bar

The status bar is always at the bottom of the window. Some fields are only displayed when Guiguts has data about the page separators in the document (read about page separators). These status bar fields are not shown until you open a file with page separators and click in its text. If you click in a file and the Page-number field does not show, the file had no page separator data, or has lost it.


The fields of the status bar are buttons, most of which also display current status information. From left to right, they are used as follows:

L:1/18001 C: 0 Line number and column of the character to the right of the insertion point, or the first selected character, and total lines in the document. Left-click in this box to open a go-to-line dialog. Right-click (Mac: ctl-click) to show or hide the display of line numbers down the left edge of the document. Shift-right-click to show or hide the display of column numbers across the top edge of the document.
H Button H starts and stops automatic Highlighting of all words in a list of words as discussed here.
Img:001 Current page-image number, corresponding to the page image file nnn.png. Left-click to open a go-to-image dialog. Right-click (Mac: ctl-click) to open the page marker adjust dialog.
< Button to go back one page and display its image.
See Img Button See Image opens the current page image in an image viewer. Right-click (Mac: ctl-click) to open a dialog for locating the folder of page images.
> Button to go forward one page and display its image.
Auto Img Button Auto Image automatically shows the page image in an image viewer any time the cursor moves to a different page--which is normally an annoyance when the image viewer takes the focus from Guiguts, but is handy when you are paging through with < and > or doing a spell check or a search.
Lbl: None Field initially reads "No Labels" to show that page labels have not been assigned. Right-click to open the Configure Page Labels dialog. After labels are assigned, this will show the assigned page, or "None" when the insertion point is in an unnumbered page. Left-click (Mac: ctl-click) to open a go-to-page dialog.
I Button sets insert mode (what you type is inserted) and overtype mode (what you type replaces text). Left-click to toggle between modes, or use the Insert key on your keyboard.
No Selection Displays the start- and end-point of the current selection, or No Selection. Double-click to open the selection dialog. Right-click (Mac: ctl-click) to restore the last selection.
Dec 10: Hex 000A   Displays the value of the character at the insertion point, or the first character in the selection, in decimal and hex. Left-click to toggle the display of the name of the character.
Lang:en Button Lang: en shows the current language (English in this example). Click it to change languages.

Tool Bar

The toolbar provides quick access to some often-used functions. All toolbar functions are also available through menu choices. Using Preferences>Toolbar, you can place the toolbar along any of the four sides of the document window, or hide it completely if you want more document space.


From left to right (or top to bottom) the items on the toolbar are as follows:

Guiguts Tb-open.png   Button that calls File>Open.
Guiguts Tb-save.png   Button that calls File>Save. Background is green when Autosave is enabled, and flashes yellow for several seconds before an autosave begins. Shift-right-click (Mac: shift-ctl-click) to toggle the autosave option on/off.
Guiguts Tb-clear.png   Button that calls File>Close.
Guiguts Tb-undo.png   Button that calls Edit>Undo.
Guiguts Tb-redo.png   Button that calls Edit>Redo.
Guiguts Tb-srch.png   Button that calls Search>Search & Replace, opening the search dialog.
Guiguts Tb-wf.png   Button that calls Tools>Word Frequency, opening the word-frequency report.
Guiguts Tb-bl.png   Button that calls Tools>Bookloupe, opening the Bookloupe report.
Guiguts Tb-spell.png   Button that calls Tools>Spellcheck, opening the spell-check dialog.
Guiguts Tb-arid.png   Button that calls Tools>Stealth Scannos, opening a file browser to select a scannos data file.
Guiguts Tb-common.png   Button that calls Tools>Character Tools>Commonly-Used Characters, opening a list of commonly-used special characters. (This replaces the Latin-1 Chart used in earlier versions. Those characters still are available in the Unicode Menu.)
Guiguts Tb-greek.png   Button that calls Tools>Character Tools>Greek Transliteration, opening the Greek dialog.
Gg1.0-03f-unicodebutton.png   Button that opens the Unicode menu.
Guiguts Tb-html.png   Button that opens the HTML menu.
Guiguts Tb-tfx.png   Button that calls Txt>ASCII Table Special Effects, opening the table formatting dialog.
Guiguts Tb-eol.png   Button that calls Tools>Remove End-of-line Spaces.
Gg1.0-03g-footnotebutton.png   Button that opens the Tools>Footnote Fixup dialog.

Tear-Off Menus

All menus display a dashed "perforation" line at the top:


It shows that the menu can be "torn off" by clicking or clicking-and-dragging on the "perforation." The torn-off menu is placed on the desktop as an independent menu. It can be moved to any convenient location and resized like any other window. (The example below shows it on top of the editing window, but you'll want to move it out of the way.) The original drop-down menu still can be used in the normal way.


Torn-off menus disappear when you close them or when Guiguts terminates. Menu status is not saved; you must tear them off afresh each time Guiguts launches.

Where to go from Here

The Table of Contents at the top of this page is approximately in the sequence many people use when post-processing, and it has links to explanations of every menu and function in the current version of Guiguts. The Overview has links to Wiki articles to help you learn to Post-process, and to DP Help resources.