PPTools/Guiguts/Guiguts 2 Manual/File Menu
GUIGUTS VERSION 2 MANUAL
Describes features included in release 2.0.3 (September 2025)
File Menu, Project Management
Some of the File menu's options are the standard ones found in most programs; others, particularly the ones on the Project sub-menu, provide capabilities tailored to the way DP and post-processing operate.
Because Guiguts is cross-platform, the screenshots seen in the manual may not match your version exactly. In general, however, if a shortcut is shown in a menu, where Ctrl is used for Windows and Linux, Mac users will see the ⌘ (command) symbol. A sample of both is included here, but throughout the manual, generally only one will be shown unless there are significant differences.
Overview of Guiguts File Management
The core unit of proofreading, formatting, and many aspects of post-processing, is the page in the original book: its image and the editable text in that image. When using Guiguts, you see the text in Guiguts' main window, and can see the corresponding image in the image viewer.
File Formats
Guiguts is a Plain Text editor. All of its files are encoded as UTF-8 and each line ends with the two-character Carriage-Return/Line-Feed (CRLF) sequence used by DP and Project Gutenberg.
The .json File (equivalent to the Guiguts 1 .bin file)
Guiguts keeps the editable text and the matching page image synchronized through the use of an extra file it creates and maintains in the same folder as the text file you are editing. It's called the .json file (pronounced "Jay-son"); its name is the same as the text file's name, including the filetype .txt or .html, but with an additional filetype of .json. For example, if you've just opened a newly-downloaded text file named projectID5c4e178999ae5.txt and you save it (without changing its name), Guiguts will create and save a file named projectID5c4e178999ae5.txt.json. The .json file does not contain the text; it contains information about where each page begins in the text (at the -----Separator lines-----), and some other information that was unique to this particular project when the file was saved.
Each time you save the text file, with whatever name you choose, Guiguts will save a corresponding .json file. Even after you've removed the Page Separator lines, the .json file will let Guiguts keep track of the page boundaries and the page images that correspond to the text. The .json file contains other project-specific information as well, e.g., where the cursor was when the file was saved.
Some file management systems, such as the Wiki, maintain a history of all changes since a document's creation. Guiguts does not do that. If you just use simple "Saves" that retain the same file name, Guiguts will not keep the previous copy.
The nature of post-processing is such that you don't necessarily develop in a straight line: sometimes, you'll want to go back several steps to try something different, or to retrieve an earlier version of a portion of the text. So, it's good practice to use "Save As" or "Save a Copy As" frequently, specifying a new file name that meaningfully describes the file's state.
Also, you will reach a point in post-processing beyond which the Plain Text and HTML versions must diverge. You can use "Save a Copy As" to create what will become the HTML version, and then keep working with what will become the Plain Text, using the same name as before, or a name you choose when using the normal "Save As".
Opening a File
If Guiguts already is running, select File>Open to bring up a file-open dialog. Use it to navigate to the desired file. Guiguts loads the file you choose as the current document and displays it in the window.
Guiguts also searches for a matching .json file and opens it to obtain page-boundary and other information about the file. Guiguts also scans the text for page-separator lines. See below for managing page separators and the .json file.
Line-end Conversion
Guiguts can read files with various kinds of line endings, but always saves files using DP-style line endings: CRLF. It does this on all platforms, including Unix, Linux, Mac, and Windows.
Recent Files List
Once a file has been opened, its name is pushed onto the top of the list of recently-opened files in the Recent Documents submenu of the File menu, where it is convenient for opening another time. Once the list grows 9, subsequent opens and saves will cause the oldest entry in the list to be dropped.
Revert/Reload from Disk
If you want to abandon any edits you have made since you last saved, you can reload the file from disk using this option. It is equivalent to loading the most recent document from the Recent Documents menu.
Saving a File
To save the current file select File>Save or type control-s (command-s on Macs). Guiguts saves the file to disk, and also saves (or creates) its .json file at this time.
To save the file in a different folder or under a different name, use File>Save As. A file-save dialog opens. Navigate to the desired folder and enter the filename to use. Guiguts also saves a .json file in that folder.
To save under a different name and continue editing under the current name, use Save a Copy As. This is useful to save a "safe copy" of your file in case you later want to go back it.
Including/Inserting a File
Use Include File to insert the contents of a file (perhaps some standard text for a TN, or some CSS you frequently include) into the current file at the cursor location.
Close
Select File>Close to clear all data. If any changes have been made you are prompted to save the file first.
The Project Sub-Menu
Add Good/Bad Words to Project Dictionary
This adds the contents of the good_words.txt and bad_words.txt files to the spelling dictionary used for this project. Adding these files will mean that when you later use the spelling checker, you will get fewer good words flagged as potential spelling errors, and also that bad words will be flagged, even if they are valid words in the main dictionary.
Note that for Guiguts to find the good/bad words, they must be located in the same directory as your current text or HTML file. If they are in a different location, just copy them into the same location as the active file.
Set Scan Image Folder/Directory
The image directory contains the page images for your project. By default, is the pngs sub-folder in the folder containing the text file you are editing. This lets you select a different folder. If you try to view an image before you set the Scan Image Directory, you will be prompted to select the directory at that point.
Set Language(s)
Like the Lang button on the Status bar, this shows the current language (or languages) and lets you change it. If you have a project which is English with some French, for example, you can enter "en fr" as the languages. The first named language is considered the main language.
The name of the language is used to find the dictionary for spell check operations, and is also used during HTML autogeneration to set the HTML language attribute. Although it is possible to use any word for the language if you have named the dictionary appropriately, it is recommended to use the official name (usually two letters) such as "en", "fr", etc. If you do not, due to using a custom dictionary, then you must change the HTML lang attribute after autogeneration to set a valid language code.
Configure Page Markers and Page Labels
This entry is equivalent to shift-clicking the "Lbl" field in the status bar. It is best to use this as soon as you start editing the project, even before going through the Proofer's Notes.
Image Numbers and Page Labels
The scanned pages we receive usually, but not always, are numbered sequentially from 1 and we casually refer to these as "page numbers." Confusion arises because these numbers often are not the same as the numbers printed on the pages of the book. The technical term for the number that is printed on a book page is folio. Within Guiguts, these are usually called Page Labels.
- image number: the sequence number of a scanned page image.
- page label: the number printed on the page of a book.
The distinction is important because the numbers in a table of contents, an index, or a cross-reference ("see p.196") are page labels—not image numbers.
Image numbers are a simple count of every scanned surface. Page labels are assigned using complex and not terribly consistent rules that reflect the logistics of printing technology. For example, the "front matter" (comprising title pages, preface, contents, etc.) was usually the last part of the book finished, after the body had been set up in type. That meant body page labels had to be assigned before the quantity of front-matter pages was known. Sometimes the front matter has no page labels, or sometimes they are lowercase roman numerals; then the body started over again with page label "1." When one or more glossy "plates" were inserted in the book, they might be numbered sequentially with the pages, or they might be referenced as "facing page nn." If a plate had a blank reverse, the blank face might count in the page label sequence or not—and it might have been scanned, giving it a page number, or not.
In summary: image numbers rarely match page labels and the numerical relationship between the two can change as you go through the book. However, when Guiguts auto-generates HTML it inserts an anchor at each page boundary with the label of the page. It is important that these anchors reflect the page labels, not the image numbers. Then it is easy to link the page references in the contents, the index, and in cross-references to the correct page.
Initially, the labels are the same as the image numbers: image 001 gets the label Pg001. You use the Configure Page Labels dialog to change the labels so that they properly reflect the page labels as seen inthe book.
This dialog has a table with one row for each page image in the book. The columns of this table show:
- the image file numbers in sequence, e.g. 019:. Guiguts takes these from the names of the files in the "pngs" folder. If there is no "pngs" folder, Guiguts will ask you to select the folder containing the page images.
- the Style of the page number: Arabic, Roman, or a ditto mark meaning "same as preceding page."
- which of three actions Guiguts will use to recalculate the page label: A number, such as "1", "+1", or "No Count". The default is +1 (next consecutive number in ascending sequence).
- The page numbers assigned to each image.
Using the Dialog
To change the settings for any page, you click in the relevant row in the table. The column you click in determines the action that is taken:
- click in the Img column and the main text window will jump to show you the start of that page. If you have Auto Img enabled, the image viewer will show you the scan for that page.
- click in the Style column to change the Style of the label. The style advances to the next one in the sequence Arabic → Roman → " → Arabic.... If you shift-click, style changes to the previous one in the sequence, i.e. Arabic → " → Roman → Arabic.... Once you are familiar with the order, a single click or shift-click is all that is needed to change any style into any other style. If you place the mouse pointer in the table header, a tooltip will appear to remind you of the options.
- click in the Number column to change the way the number is calculated. "+1" means use the next consecutive number after that used one the previous page; "No Count" means the page does not have a label and is ignored in the page numbering in the book (commonly used for plates); finally, you can set a specific page number for the label. As above, clicking cycles through the options, and shift-clicking cycles through in reverse order.
When you click or shift-click as described above, the final "Label" column will automatically update with the newly recalculated page numbers, so you can check you are matching the page numbers printed in the original book.
Dealing with Front Matter
Pages such as the title page and blank pages at the beginning of a book often are unnumbered, and other early pages often use Roman numbers. You can use combinations of "Roman," "No Count", a number, "+1", and eventually "Arabic" to match your page numbering to what's in the book.
Dealing with Plates
Some illustrations in our books are on unnumbered pages that were ignored in the page numbering sequence. They usually are photographs that were printed separately on higher-quality paper, and their obverses tend to be blank. We refer to such pages here as "plates". They were inserted between consecutively-numbered folios during the binding process, and we need to adjust our page numbering accordingly. We do this by using "No Count" (sometimes in combination with setting an explicit number).
Dealing with Skipped Blank Pages
Just as there are blank pages near the beginning of the book, there may be blank or other kinds of unnumbered pages elsewhere. We can adjust the numbering in such areas in the same way as we did in the Front Matter: set the "Number" for the blank or unnumbered pages to "No Count", then set the an explicit number for the next numbered page to the number shown in the image for that page.
Add/Remove Page Marker Flags
Add Page Marker Flags inserts a text string of the form [Pg003|Roman|+1] into the text following every (invisible) page marker. These markers correspond to the .png names of the page images of the original book, and the settings from the Page Label Configuration dialog that Guiguts uses to calculate the page labels.
If you save your file with the Page Marker Flags visible, you can then load it into recent versions of Guiguts 1 (1.62 or later). Guiguts 1 will then be able to recalculate the page labels, and you can use Remove Page Marker Flags in Guiguts 1. This means that you can easily complete some work on your book in Guiguts 2, then perform other operations, e.g. HTML generation, in Guiguts 1. The reverse process works too for beginning some work in Guiguts 1, then continuing it in Guiguts 2.
IMPORTANT NOTE: Do not try to make significant changes to your file while page marker flags are visible, such as wrapping or footnote fixup. The flags are only designed to aid transfer to and from other programs as described in this section. First Remove Page Marker Flags, then perform the wrap, footnote fixup, etc., then if needed, Add Page Marker Flags again.
In summary, to transfer in either direction between Guiguts 1 & 2:
- In the first program, Add Page Marker Flags then save the file.
- In the second program, load the file and Remove Page Marker Flags.
The Add & Remove Page Marker flags also make it possible to edit your file in a non-Guiguts editor. Before the inclusion of this feature, using a non-Guiguts editor would mean that the locations of the page breaks would be lost, but using this feature preserves them.
To use this feature to make some edits using another editor:
- Use the Add Page Marker Flags option in Guiguts and then save the file;
- Load the file in the other editor and make whatever changes you like. Be sure not to delete or modify the added flags, but you can cut/paste them to move them if you wish to change where the page boundaries are;
- Save the file from the other editor;
- Load the file back into Guiguts;
- Use the Remove Page Marker Flags option to remove the flags;
- Save the file.
The Content Providing Sub-Menu
See the Content Providing Menu page for features relating to Content Providing.
Quit
Closes the current file and closes Guiguts.
If the current file has been changed since the last Save, Guiguts will prompt you to save it first.
Page Markers and the Metadata File
Many useful Guiguts features depend on knowing where the text from each page-image begins and ends. For example, this is what allows Guiguts to display the scan image file for the cursor location.
Page Separator Lines
Initially, data on page-image boundaries comes from the page-separator lines in the downloaded text file. These lines may look like:
-----File: 004.png---------------------------------------------------------
When Guiguts opens a file it scans the text looking for the page-separator lines. For each page separator, Guiguts notes the scan image filename.
The .json Metadata File
Page-separator lines are not a permanent part of the book. Part-way through the post-proofing workflow you tell Guiguts to delete them. In order to be able to keep track of page-image boundaries after the visible separator lines have been deleted, Guiguts records the page boundary points in a separate file. This .json file also holds other metadata about the file, such as the page label numbers and bookmarks you have set. But the most important data in the .json file is a list of the page boundary locations as offsets. The .json file is rewritten every time you save the file.
The full name of the .json file is filename . type .json that is, .json is appended to the full filename of the document. If the document is volume_2.txt then its .json file is named volume_2.txt.json.
If you use File>Save As to create volume_2.html, you will then have four files: volume_2.txt and volume_2.txt.json, and volume_2.html with its related volume_2.html.json.
Cautions on .bin File Use
Guiguts looks for the .json file only in the same folder as the document file. When you move a file from one folder to another, you need to move its matching .json file also. If you do not, Guiguts cannot load your bookmarks and data on page boundaries and proofers.
You can tell when Guiguts lacks page-boundary information. After the file is open and you click in it, the status bar ought to display the current Img number. If it does not, there was no .json file or it was not readable.
If you lose the .json file after you have cleared the page separator lines, there is no good way to recover the data.
If you use a different editor to modify a document (for example, WordPad, BBEdit, vi or emacs), that editor will not know about the .json file, and will not update it to reflect changes in the relative position of text as Guiguts would do. Thus if you do not use Add Page Marker Flags as described above when you modify a document outside of Guiguts, Guiguts may no longer have correct page boundary information. The results can be unimportant (Guiguts displays the wrong page image), or they can be serious (Guiguts generates improper HTML). If Guiguts already has generated the HTML version and the pagenums are in place, the file still is usable, even though Guiguts sometimes may display the wrong page image to you. Otherwise, consider the consequences of the external edit.
Opening Multiple Files
Toward the end of the PP process you typically will have two versions of a book: Plain Text and HTML. Often, as you edit one version, you will find errors that should be corrected in both versions. You can open, fix and save each version serially, but that is tedious.
It would be convenient to have all versions of a book open at the same time, so you can make fixes in each and save them simultaneously. To do this in Guiguts, you need to launch multiple copies of the Guiguts program. Each instance of the program edits one document file, but you can copy from one document and paste into another.
Guiguts is not written to be used in this way but it does work. As long as each instance of Guiguts is editing a different document file, there is no interference. (It would be unwise to edit the same document in two instances of Guiguts; unpredictable things would happen if both tried to autosave at the same time.)
When each copy of Guiguts is terminated, it updates the settings file, so your preferences (for example, your saved search-and-replace patterns and window position on the screen) will reflect the usage in the copy of Guiguts that terminates last.