Contents | Start | End | Previous: Chapter 5: Creating HTML Help | Next: Chapter 7: Creating Personalised Books
This chapter describes how to use Jutoh Plus to create custom checking messages: a very productive proofing tool.
When you compile a Jutoh project into an ebook file for a given configuration, Jutoh may show errors, warnings and tips based on formatting and other issues in your book. These messages are based on knowledge about formatting and ebooks encoded within Jutoh. But there may be potential issues specific to an author, publishing company or a book series that would be convenient to warn about during a compile. Here are some examples:
highlighting any paragraphs formatted with the ‘Normal’ paragraph style rather than a more specific style;
highlighting any blank paragraphs;
checking for words that are accidentally repeated, such as “his his”, “to to”, “at at”;
checking for frequent typos or non-standard usage, such as “discrete” instead of “discreet”;
checking for issues around quotations, such as a comma or period missing before an end quote;
checking that the correct kind of dash is used;
checking for clichés or over-used words that would not show up in a spell-check;
checking for references to book distributors that are not supposed to be mentioned in the final ebook.
Jutoh Plus has a mechanism that allows custom checks like this to be performed, with messages included with other Jutoh messages during compilation, or listed in the Inspector when using the Custom checking mode. You can set up find and replace preset libraries in either your project or globally (for all projects). As you edit a project, you can add presets to your library that can be used to identify common errors in the remainder of the project, and in other projects.
You may be surprised at how many issues you find in a project that were missed by human eyes!
The following screenshot shows custom messages for blank paragraphs, paragraphs with the ‘Normal’ style, and duplicate words.
First decide whether your presets are relevant only to a specific project, or of more general use. You might even have global presets that are applicable to all projects, and specific presets for each project. You can also save and load presets, for example to transfer them between project and global storage areas. Also, you can use the command File | Import | Import from Project command to import presets from one project to another. Or, ensure there are presets in a template project that you are going to use when creating new projects.
An advantage of keeping presets in a specific project is that if you send it to someone else, they too will be able to see relevant custom messages.
You can edit project presets in the Project Properties dialog, under Find & Replace, and global presets in the Preferences dialog, also under Find & Replace. You can also edit them from within the Find and Replace dialog, by clicking on “...” and choosing Manage Presets.
To tell Jutoh whether and what preset library (or libraries) to use, you can edit your configuration(s), or use a global advanced setting to override any configuration settings.
In your configuration, set the option Custom checking to use one or more of these libraries during compilation. You can use wildcard characters * and ? to specify multiple libraries, and you can separate specifications with the pipe (‘|’) character. Examples of suitable values include:
* (use all libraries from this project and the global preset store)
Project/* (use all libraries from this project)
Global/* (use all libraries from the global preset store)
Project/My Presets|Global/Default Presets (use My Presets from the current project, and Default Presets from the global preset store)
You can override this configuration option globally via the setting Custom checking in Preferences/Find & Replace. You can use this to switch off all custom messages, or always emit custom messages regardless of configuration.
Jutoh will check all specified libraries and if the ‘find’ part of the preset matches within a paragraph, the provided message will be emitted along with optional details that are provided in the preset. Any ‘replace’ component of the preset will be ignored; if the preset is used within the Find and Replace dialog, then the ‘replace’ component can be used.
When you define a preset, you specify all the search criteria that you would normally specify in the Find and Replace dialog.
In addition, there are some optional fields to fill in.
Name lets you name a preset for the purposes of organisation, and the name will be mentioned the compile message.
Details lets you define more explanation to be shown in the hint associated with the compile message (shown when the user double-clicks on the message).
Level lets you set the severity of the message. Choose from Error, Warning, Tip and Notice. By default, the preset will use Notice. Only preset messages will ever show as Notice, not regular Jutoh messages.
Enabled lets you exclude this preset from compile messages by clearing the option.
Presets can’t perform all possible checking that you can think up, and each search specification works within a single paragraph, but it can encompass a very useful range that can help you improve book quality. If you use regular expressions, the custom messages can be quite sophisticated. For example, the regular expression ^$ will match empty paragraphs, and this will find duplicate words except for “had had”: (?!had)\y([\w]+)\y\s+\y\1\y. For more on regular expressions, see the topic Using regular expressions in the Jutoh application help.
You can use simple searches, or regular expression searches, in conjunction with formatting searches. For example, you might want to highlight any paragraphs that didn’t end with punctuation - except for headings, which don’t usually end with punctuation. So, you could enter the regular expression \w$ (find a word character just before the end of the paragraph) and also specify in the advanced search options that the paragraph style Body Text* must be found. This only applies the punctuation check for body text styles such as Body Text and Body Text First Indent, and not for headings.
When you compile your book, and if your configuration option Custom checking or global setting Custom checking is set to use one or more preset libraries, then Jutoh will show any matching presets as messages in the error window, reporting the error level defined in the preset (Error, Warning, Tip or Notice).
As with other messages, you can double-click on a message and see more details. The location of the matching text will be highlighted. You can quickly navigate through the messages using the keyboard shortcuts Ctrl+[ for the previous message, and Ctrl+] for the next message. These shortcuts are on the menu View | More and can be modified if you want to use different keys.
Note: if you have edited text prior to this message, the highlighting may not be at the correct spot. This is particularly problematic if you have added or deleted paragraphs, so if you find the highlighting to be out of sync with the text, make a mental note of how far you have got through the errors, compile the project again, and start looking from the appropriate point in the message list.
You can also view your custom messages in the Inspector tab of the Formatting Palette: choose the Custom checking mode from the drop-down control.
As above, Jutoh will use your configuration option Custom checking or global setting Custom checking (set in Preferences/Find & Replace) to find presets to match against each paragraph in your book.
You can click Exception to add an exception so that the message won’t be shown again – the item will immediately disappear from the list. Click Preset to edit the preset that generated the message. Or you can correct the text, as shown in situ when you click on the message.
Whenever you edit text, the Inspector is updated after a few seconds. This means that unlike the compile method, messages won’t be out of sync with the book for long.
If you click on the “...” menu button in the Inspector, you can use commands for editing presets and configuring which preset libraries Jutoh will use.
You can apply one or more preset libraries to your project to replace content and formatting en masse. Use Format | Book | Apply Find and Replace Presets or the Apply Find and Replace Presets command in the Inspector (with Custom checking selected).
This will show the Apply Presets dialog, giving you the choice of using current custom message settings or selecting other preset libraries.
You can also tell Jutoh to apply presets directly after importing a file into a new project. To do this, set the value of Apply presets to the required preset libraries in Preferences/Import.
When Jutoh is installed, a presets file called Standard Find and Replace Presets.jfpresets is copied to the Jutoh Samples folder under your Documents folder. This file is loaded automatically into global preset storage as the library “Standard Presets” if no other global presets currently exist. You can also load this file manually via the preset manager, either into a project or into global storage.
This library includes some convenient presets for finding duplicate words, double spaces, and common punctuation problems such as a comma at the end of a paragraph. It may also help you understand how regular expressions work.
Depending on your presets, it may be that there are many ‘false positives’ - that is, the suggested change isn’t relevant in all situations. This can create a lot of distracting noise in your compile messages, making it harder to find the actual errors. So you can use exceptions to ignore particular matches. Adding them in bulk can save a lot of time if you have a lot of spurious matches.
Each exception contains a preset name and the text fragment or whole paragraph to ignore when this combination of preset and text is found. For example, you might want to ignore the text “that that” when searching for double words; or only ignore it for one particular paragraph, since “that that” might still be erroneous in other contexts.
You can only add exceptions when the preset finds some text, or by specifying the full paragraph as the exception text and the text isn’t empty. So you can’t add exceptions for presets that match blank paragraphs.
An exception is stored in a preset library, but it doesn’t have to be the same library that contains the relevant preset. For project-specific exceptions, it’s best to store them with the project, so you can create a new preset library for that purpose, via Project Properties/Find & Replace. When you add a new exception by clicking on the details for a custom message, and your project has no preset libraries, Jutoh will ask if you want to create one called “Exceptions”. This library will then be the default for further exceptions you add for this project, in this Jutoh session.
You need to ensure that the configuration option Custom checking or global setting Custom checking mentions the exception library you’re using. For example, to use all libraries in the project and global storage, set it to * (an asterisk, meaning ‘match all libraries’). To use a global preset library and a project exceptions library, use something like Global/My Presets|Project/My Exceptions.
There are three ways to add exceptions:
Edit a preset library in Project Properties/Find & Replace or Preferences/Find & Replace, and edit exceptions under the Exceptions tab.
In the details for a custom message, scroll down to the line Add exception and click on the link to add a single exception to a library of your choice.
In the details for a custom message, scroll down to the line Add bulk exceptions and click on it. This will show the Bulk Exception dialog and lets you choose which matches will be used for exceptions and which library to add the exceptions to.
If you have just added exceptions, and you chose to add the exceptions to a library in your project rather than in global storage, you can reverse it using File | Undo Project Properties.
If you have added exceptions via the error message details window (2 or 3 above), and Jutoh detects that your current Custom checking setting doesn’t include the library containing exceptions, and therefore the exceptions won’t be used, it will ask if you want to add the library name to the setting.
To help bring all this together, let’s look at the typical steps you will take to make custom checking work for you.
Define some find and replace presets. Add a global preset library via Preferences/Find & Replace, or project-specific presets via Project Properties/Find & Replace. Or you can do both! You can load existing preset libraries from disk or create them from scratch.
Tell Jutoh which preset libraries you want to use. You can do this per configuration, via the option Custom checking. When this configuration is selected, for this project, and you click Compile, Jutoh will use the specified preset libraries. You could even add a special configuration that is used only for this purpose. Or, you can tell Jutoh to always use certain preset libaries, for all projects and configurations, via the global setting Custom checking. Example values: “*” (use all libraries), “Global/Standard Presets” (use only the global library Standard Presets), “Global/*|Project/Exceptions” (use all global libraries, and the project library Exceptions). Tip: a quick way of editing these options is to use the context menu in the error list, by right-clicking (or control-clicking on Mac) and choosing commands under Custom Messages.
Compile your project and view the messages. Click Compile, and double-click on a message. You can use Ctrl+[ and Ctrl+] to quickly cycle through the messages, showing the matching content in situ; correct your text if necessary. Or, view messages in the Inspector using ‘Custom checking’ mode.
Add exceptions to eliminate ‘false positives’. Each custom message has links to add exceptions singly or in bulk, so that Jutoh won’t warn about this particular occurrence again. If you create an Exceptions preset library in each project, you can store the exceptions with your projects, reducing distracting messages when you come to compile the project again.
Go to step 3 until you are satisfied that there are no more problems. As you edit your book, you may add further presets as you discover common errors.
In this chapter we learned how Jutoh can be used to create special messages to track down problems in your book, such as common typos or punctuation errors.
Next up: the bulk creation of books personalised for individual customers.
Contents | Start | End | Previous: Chapter 5: Creating HTML Help | Next: Chapter 7: Creating Personalised Books