PPTools/Guiguts/Guiguts 2 Manual/HTML Menu

GUIGUTS VERSION 2 MANUAL

Describes features included in release 2.0.0 (July 2025)

HTML Menu

• • • SCREENSHOT: HTML menu

HTML Generator

The HTML Auto-generator dialog is shown with a few settings that can be changed before clicking Auto-generate HTML.

• • • SCREENSHOT: HTML Auto-generator dialog

The text shown in the Title field at the top is Guiguts best guess at the title of the book. This may be incorrect, if there is other material at the start of the book before the title. This text will be used in the <title> field of the generated HTML file. You can edit it before generating the HTML so that your HTML will have the correct title.

The Inline Markup radio buttons below the title control how various types of DP markup in your master file will be converted to HTML. For example, by default, <i> markup will be remain as it is, but you may prefer it to be represented by <em class="italic">. You can set similar options for bold, gesperrt, font and underline markup to match your preferences.

Before HTML Auto-generation begins, a copy of your current file will be automatically saved. If your file was named myfile.txt the backup file will be named myfile-htmlbak.txt. This is similar to the behavior of Guiguts 1.

If an error occurs during HTML Auto-generation, for example if there was some unclosed poetry markup, an error box will pop up with the approximate line number where the error has occurred. After you have noted the line number and dismissed that error, a dialog will appear, asking if you would like to re-load the pre-conversion backup file. Usually, you will click OK, then go to the line number mentioned in the earlier error message to fix the problem that auto-generation has detected. If you have forgotten the error or line number, you can use View-->Message Log to see the errors that have occurred during this run of Guiguts.

Occasionally, if an error is hard to diagnose, it may be helpful to explore the partly-converted file and see what auto-generation had managed to complete successfully before it detected the error. In that case you would click Cancel in the "Re-load backup file?" dialog. You should not try to continue with, or correct, the partly-converted file. Once you know what the error was, return to your own most recent saved file, or the automatically saved "htmlbak" file (suitable renamed), make the corrections there, then re-run HTML Auto-generation.

Auto-Illustrations

With your help, Guiguts can convert [Illustration: caption] to HTML that will display the appropriate illustrations and let you fine-tune the layout and formatting.

Note: This dialog is also used by the HTML Images feature to insert illustration HTML markup that does not have corresponding DP [Illustration] markup.

• Begin by clicking "Auto-Illustrations" on the HTML menu

• The first time you do this in each project, Guiguts will ask you where the images are, by opening a standard File dialog.
• Select the "images" folder to see its contents; choosing a view that shows thumbnails of the images, rather than just their names, will make the selection process easier:

• • SCREENSHOT: Image file selection dialog showing thumbnails

• Select the image that matches the highlighted text in the main editing window, which will be the first illustration in the project, and Guiguts will show you the Auto-Illustration dialog:

• • SCREENSHOT: Auto-illustration dialog

• Guiguts will automatically select the next image file alphabetically, which will often be the correct one for the next illustration being converted. If it is not, you can either use the Browse button to manually select the correct image file, or the Prev File or Next File buttons to step backward or forward through the files in the image folder. Each time a file is loaded, a thumbnail image will be displayed below the filename.
• Guiguts will also attempt to extract the caption text, if any, from the [Illustration: caption] markup, and will calculate the width and height of the image stored in the file.
• You may edit the caption text if you wish, and adjust how the width and height are used as described below.
• You should complete the "alt" field if appropriate for the image to aid accessibility.
• In the geometry section, some behavior is determined by the setting of the "%"/"em"/"px" selection. The primary effect is to control the units of measurement used to specify the image width in the HTML.
• In "em" or "px" mode, the width and height shown initially are taken from the image file that has been loaded. You may adjust these if you wish by editing the width - the height will be automatically calculate to remain in the correct proportion. The original file size in px and em will continue to be shown in a label immediately below the measurement unit selection.
• In "%" mode, the image size is controlled by a percentage width - e.g. 50% means the image will fill half the width of the reader's screen; it does not mean the image is scaled by 50% from the original size in the image file. The program calculates what is the maximum percentage width that would allow the whole of an image to fit within a landscape screen with aspect ratio of 4:3. Again, you may edit this percentage width either larger or smaller, bearing in mind that if you make it larger than the maximum shown in the label below the file size label, the image will not fit vertically on a 4:3 landscape screen. In any case, the image will not be scaled to a larger pixel size than the original natural size of file.
• Also in "%" mode, the "Override % with 100% in epub" checkbox means that even if you specify 50% width for an image when viewed in a browser, the image will be displayed at 100% width in epub versions, i.e. the image will take up the whole width of the epub screen.
• It is recommended that "%" is used with [very] large original images, but if you have a small image, such as a logo or something that should occupy only a small part of the screen, then "em" will most likely be a better option, so that the HTML will cause the image to be displayed using its actual width and height.
• The default alignment is "Center". If you want the image to be floated to the left or right instead, select one of them.

Once you have made any adjustments for this image, click Convert to HTML, then check that the inserted HTML looks satisfactory. After that, the Find [Illustration] button will select the next illustration markup, and also advance which file is loaded. The Convert & Find Next button combines the operation of these two buttons.

• As well as inserting the necessary HTML to display the image, any required CSS will be generated (at the end of the <style> section at the top of the file) to define the "illowp' class that sets the width, for example:

.illowp75 {width: 75%;}

• If percent is chosen as the unit of measurement, the <div> also will contain style="max-width: nnem;".
• if px is chosen as the unit of measurement, the <figure> will contain style="max-width: nnpx;" but no classname, and no CSS will be generated.

Auto-Table

• • SCREENSHOT - AutoTable dialog

This menu entry opens the Auto-Table dialog, which can be used to convert the current selection into an HTML table. When the Multi-line switch is off, each line of the selection is marked as a table row. If Multi-line is set on, each group of lines separated by a blank line is made into one table row (see examples, below).

Columns are defined by two or more spaces OR a vertical bar | between elements. Use the Table Effects dialog (on the Text menu) or space the columns manually to put two spaces or a vertical bar between column values; otherwise column values will be combined in a single cell. If the text in the selection contains even one vertical bar, Guiguts will only look for vertical bars, not multiple spaces, as column separators. Tables already formatted for Plain Text with vertical bars can therefore be converted without first replacing the bars with multiple spaces (see second example, below). In the rare case of a vertical bar being part of the actual text, temporarily replace it with another character while you work on the table.

The alignment switches left, center, and right set the default alignment for all table columns. Guiguts inserts class="tdl" or class="tdc" or class="tdr" in each <td> markup. Often, different columns of a table need different alignment; for example, a column of names should be left-aligned, one of numbers right-aligned. You can specify different alignments for each column by putting characters in the "Column Format" field. You should place one character for each column in the table, using < or L/l for left-aligned, | (vertical bar) or C/c for centered, and > or R/r for right-aligned. For a four-column table to be aligned left, left, center, and right, you would enter <<|>, or llcr. Extra characters are ignored; and columns for which there are no characters get the default alignment.

Note that HTML has no concept of decimal alignment. When using proportional fonts, one way to align numeric columns containing decimals and/or fractions is to pad the shorter numbers with hard spaces: two hard spaces usually have the same width as a digit, and one hard space usually has the same width as a decimal point.

Auto-List

Auto List creates an unordered or ordered list from the text you've selected. The list will begin with <ul> or <ol> and end with its closing counterpart. Each line within the list will begin with <li> and end with </li>. If every line in the selection represents one list item, the Multi-line switch should be unchecked. If some items use more than one line, check this box and ensure there is a blank line between EVERY item, even the single-line ones.

HTML Markup

• • SCREENSHOT of HTML Markup dialog

The HTML Markup dialog allows you to quickly add HTML markup to your file, or remove unwanted markup.

• The cluster of buttons at the top place an open tag and close tag around whatever text you have selected in the main editing window. If there is a column selection, then the tags are placed around each line of the column selection. If there is no selection, the open and close tags are simply inserted at the insert cursor. The exception to the above is   which is just inserted at the start of the selection(s), or the insert cursor; nothing is inserted at the end of the selection(s).
• The four rows of controls below those buttons offer similar, but more flexible capabilities. Each button inserts markup ("div", "span" or "i") like the buttons above, but also adding any attributes from the dropdown boxes to the left. For example, if the dropdown box contains lang="fr" and the "span" button is pressed, <span lang="fr"> will be inserted before the selection/insert cursor, and </span> afterward. To insert a class attribute, you can just give the class name and omit class=, e.g. if the dropdown box contains myclass and the "div" button is pressed, <div class="myclass"> will be inserted before the selection/insert cursor.
• Each dropdown box has its own history which you can use to store attributes that you use frequently. When you use one of the buttons next to a dropdown box, the attribute in the box will be stored in the history.
• The final button at the bottom removes HTML markup from the selected text. It is not able to determine whether markup is valid HTML, and just removes markup that begins with the less-than symbol, possibly a slash character, and at least one alphabetic character, and continues removing until it finds a greater-than symbol. It also replaces   with a space character.
• All of the HTML Markup dialog commands are available in the Command Palette so you can assign keyboard shortcuts to those you use most frequently.

HTML Links/Anchors

• • Screenshot of HTML Links

The Links & Anchors dialog helps you create internal and external links:

• • Use the Insert Anchor At Selection button, in the Anchor section, to insert an anchor whose id is based on the current selection. For example, select the text CHAPTER 7 and click the button. The code <a id="CHAPTER_7"></a> is inserted preceding the selection.
    • Guiguts deals properly with spaces (converting to underscores) and special characters when making this substitution. This gives you a quick way to insert an anchor for reference from elsewhere in the book.
  • You can use the Internal Link section of the dialog to link to an anchor in this file. This section contains a list of all the anchors (elements with id attributes) in the file. If you want to refresh this list, for example if you have just added a new anchor, you can do that by turning one of the toggle buttons above the list off and on again.
    • Since projects typically contain many page number anchors and possibly footnote anchors, which could make it hard to find other anchors you want to link to, the Hide Page Anchors and Hide Footnote Anchors checkboxes allow you to temporarily hide those from the list.
    • By default, the list of anchors is sorted by location in the file. Use the Sort Alphabetically checkbox if you prefer an alphabetic sort order.
    • To link to an anchor (for example one created by the Anchor button, or a page number anchor created by automatic HTML generation) first select some text to be linked to the anchor. Then click the required anchor in the list. Guiguts will encloses the selection in a link with href="#Anchorname".
  • Use the External Link section to create a link to an external file. This could be an image file, or any other permitted file type. Click Browse to select the target file, or type the path to the file in the entry field. Click Insert Link to insert the HTML code.
    • If the linked file is in or below the same folder as your HTML file, Guiguts builds a link using a relative pathname, e.g. href="images/cover.jpg"

HTML Images

The HTML Images button pops a variant of the Auto-illustrations dialog, where you can select an image file, adjust settings like size, caption, etc., and add the markup to make it an illustration in your book. The dialog does not have a Find [Illustration] button like the Auto-Illustrations dialog, but after adding one illustration, you can use the Browse, Prev File or Next File buttons to choose another image file, click in your HTML file where you want to insert the markup, and click the Insert Illustration Markup button again.

Unmatched HTML Tags

This searches for unmatched HTML tags, e.g. <p> without a matching </p>, and displays them in the same way as the other Unmatched items commands

HTML Validator

This sends your file to the online nu HTML validator to check that it is valid HTML. The results are displayed in a checker dialog. Note that unlike Guiguts 1, which installed a version of the validator on your computer with the release, in Guiguts 2 you can be sure you are using the most up-to-date version of the validator, so there is no need to upload and check your file manually.

CSS Validator

This sends the <style> CSS block from the top of your file to the online W3C CSS Validation Service to check that it contains valid CSS. The results are displayed in a checker dialog. Note that unlike Guiguts 1, which installed a version of the validator on your computer with the release, in Guiguts 2 you can be sure you are using the most up-to-date version of the validator, so there is no need to upload and check your file manually.

HTML Link Checker

Use this to find broken and duplicate links in your file, as well as unused files in the images folder, and view the results in a checker dialog.

• • SCREENSHOT HTML Link Check dialog

PPhtml

PPhtml runs various tests on an HTML file, as well as checking the files in the images folder and music folder, and displays the results in a checker dialog.

One kind of CSS-related error occurs when an undefined class is used in the body of the document. PPhtml will find those, but also may flag some defined classes as being undefined. It also finds defined but unused CSS classes, but again, some of them actually may be used. Because PPhtml is over-cautious, you should check each possible error before making any changes.

• • SCREENSHOT PPhtml output

HTML/CSS header file

When HTML Auto-generation happens, a header is inserted at the top of the HTML file. This contains some necessary commands to identify the file as an HTML file, the title for the page, etc. It also contains default CSS to style the look of the book. You may customize the HTML header in one of two ways.

Recommended Method of Customization for CSS

The recommended method is to leave the default header as it is in `data/html/html_header.txt`, and create a new `html_header.txt` in your GGprefs folder which only contains CSS that overrides or adds to the defaults. For example, the transcriber's note has a default background of color of #E6E6FA (a pale blue-gray color) which is set by a command in the default header:

.transnote {background-color: #E6E6FA; ... }

If you prefer your TNs to have a pale pink background, e.g. #FF808C, you can put the following command in your new `html_header.txt` in your GGprefs folder:

.transnote {background-color: #FF808C;}

When the HTML file is generated, the default header will be inserted at the top of the file, and your header will be inserted at the bottom of the default CSS, just before the closing `</style>`, so that your CSS will override the earlier default settings. This method has the advantage that when future releases are made with adjustments to the default header, you will not usually need to edit your customized header text to get the benefit of the changes in the release.

Alternative Method for CSS Customization

The alternative method, which does not have the above advantage, is to copy the complete file `html_header.txt` from the `data/html` folder in the release into your GGprefs folder and edit it however you want, to make the customizations you desire. You would edit the block

.transnote {background-color: #E6E6FA; ... }

to say

.transnote {background-color: #FF808C; ... }

Your file will be used as the complete header for generated HTML files (instead of just an addition as in the recommended method above), and the default file in the `data/html` folder will be ignored. However, if the default file is altered in a future release, perhaps to improve the display of images, you would not automatically get the benefits of that change. You would need to either copy across the new changes from the release's default file into your customized one, or copy the whole file across from the `data/html` folder in the release into your GGprefs, and make your customizing edits to it once again.

Ebookmaker

Ebookmaker uses the currently-saved HTML file (so make sure you Save before running ebookmaker) and the images folder to generate .mobi (Kindle) and .epub (everything except Kindle) files, which are widely used on handheld devices. Use this after you've finished making your HTML look as good as possible in browsers, then examine the .mobi and .epub files in computer previewers (such as Kindle Previewer, Adobe Digital Editions, and Calibre) and/or actual handheld devices. Try to adjust your CSS and associated HTML to make those handheld versions look as readable as you can, without adversely affecting the appearance of the HTML in Browsers. There are two alternatives for running ebookmaker described in the sections below.

• Select which formats of ebook you want ebookmaker to create: EPUB2, EPUB3, Kindle (older Kindle format), and KF8 (newer Kindle format).
• The epub files will be created in the current project folder, and will have the same root name as the current file. For example if your HTML file is myfile.html, the epub files created will be myfile-images-epub.epub, myfile-images-epub3.epub, myfile-images-kindle.mobi, and myfile-kf8-kindle.mobi. Note that the ebookmaker log file that is displayed in the dialog lists the internal filenames at PG, which will be of the form 99999-images-epub.epub, but Guiguts renames them to match your HTML file when it downloads them for you.
• Guiguts passes the book's Title (if it can find it in the <title> of the document header) to ebookmaker, and ebookmaker can provide that information to some eReaders for use in page headings.
• While ebookmaker is running, Guiguts will wait for it to finish, just as it does with most of its other tools. When eBookmaker finishes, the Wait cursor will return to a normal text cursor, and the ebookmaker log file, including any errors, will be displayed in the dialog.
• For further information about ebookmaker, please see the eBookMaker Wiki page.

Local installation

• Using this menu option will run the version of ebookmaker installed on your computer. This may not be the latest version unless you have updated it recently, but it is unlikely to matter much for testing purposes if your version is slightly out of date. The online version at Project Gutenberg is always the latest version.
• You will need to tell Guiguts the location of ebookmaker on your system. This is the directory/folder where you typed the `pipenv install ebookmaker` command when following the ebookmaker installation instructions. You can use the Browse button to find that folder on your computer.
• If you select Kindle and/or KF8 versions to be created, ebookmaker will attempt to use Calibre to create the required format. If you do not have Calibre installed and on your PATH, an error message will be displayed. To avoid the error message, either install Calibre, ensuring it is on your PATH, and restart Guiguts, or you will need to uncheck the Kindle and KF8 check buttons.

Online using API

• Using this menu option will upload your files for processing by ebookmaker online. If you use this option, you do not need to install ebookmaker or Calibre on your computer.
• If there is a serious problem processing the file, an error box may appear reporting that it was unable to download the epub files. After dismissing that error, look in the ebookmaker dialog and inspect the contents of the ebookmaker log file to find out what was wrong.