Contents | Start | End | Previous: Preface | Next: Chapter 2: Script Syntax
Scripting and HTML templates are the two main features of Jutoh Plus. Jutoh Plus also supports the creation of CHM and HTB help files, custom checking, and creating personalised books. In this chapter we explore the concepts behind these features, and how you might make use of them.
Scripting is the main feature of Jutoh Plus. A script is a file with the jutohscript extension, and you can run a script from the command line or by opening a script using File | Open. If you open a script from Jutoh, you will see the Script Runner window:
The script runner window
Click on Start to run the script. A progress gauge will be shown below the log window, and information, warnings and errors will be written to the log window. Errors will be shown in red. Click on Edit to edit the script. You can choose a new script file with the “...” button, and you can save, clear or copy the current log text. If you check Abort on error, the script will terminate immediately an error is encountered; otherwise it will carry on with processing as far as it can.
When running Jutoh from the command line using the --batch and --quiet switches and supplying a Jutoh script file, Jutoh will complete the script processing without any prompting or visible user interface, so you can use it as a step in other shell or DOS command scripts, or indeed from any other application. You can view or parse the log file to determine if the script was successful.
Here is an example of command line operation:
jutoh --append=log.txt --batch --quiet MyScript.jutohscript
Please note that if running a script by clicking it within Finder on a Mac, Jutoh may hang during script execution, so it’s best to run it by opening the script from File | Open in Jutoh.
Jutoh doesn’t provide an editor for scripts, since they are simple text files (preferably encoded in UTF-8, without a BOM marker) that you can use with almost any text editor. For example, on Windows, you can use Windows Notepad, or a third-party application such as Programmer’s Notepad 2. If you are using the script runner window, you can click on Edit to edit the current script using whatever application is associated with the txt extension. On Windows, that’s usually Windows Notepad unless you install a different editor.
The Tools menu, on the menubar at the top of the application window, lists built-in tools (such as a ‘Dictionary’ web link) and also any custom ones that you add via the Preferences/Tools pane. The tools can also be shown on the Jutoh Desktop. Normally custom tools are documents, web links or executable files, but you can also specify Jutoh script files. When a script is executed from a tool, there is no script window, and messages, warnings and errors appear on the Jutoh log window.
You may find custom script tools useful for accomplishing certain tasks that would be laborious to do via the regular user interface, even though you use Jutoh interactively most of the time. For example, you can use it to perform reimport and subsequent property setting and compilation for the current project.
A Jutoh script can create a Jutoh project file from input such as a DOCX or ODT file; it can specify most of the options that you can change by hand, such as how to split the file into sections, and it can check and create ebook files. You can import styles common to your projects, replace strings, and insert content fragments (such as a copyright notice that is the same in all your projects). You can change the way different configurations behave, for example specifying different cover designs for different formats.
These capabilities are especially useful when you are dealing with many ebooks. One scenario is coordinating incoming content that is formatted in DOCX or ODT to your specifications. You can outsource the editing to people who just use a regular word processor and who don’t have to know how Jutoh works. You can then use scripts to convert the files you receive into Jutoh projects and various ebook formats, adding standard copyright notices, extra content, and covers; all without a lot of manual operations.
Another use would be to stamp a book with the customer’s name to discourage redistribution or to make it more personal. This could be done on a web server, if necessary using a virtual X server such as Xvfb since Jutoh still needs a notional display to be present: see Chapter 3 for more on this.
In summary, these are the main operations you can perform in a Jutoh script:
import from DOCX, ODT, HTML, Epub or text;
run a reimport and compile, for the current project, without going through all the New Project Wizard steps;
open an existing Jutoh project for modification;
specify how the input will be split into sections;
generate ebooks;
check the Epub after generation;
create multiple configurations, including more than one for the same basic format;
change section titles;
specify a cover or a different cover per configuration;
insert DOCX and ODT fragments into sections, putting the fragment at the start or end of a section or using a keyword to position it;
insert images in specific sections or using keywords;
replace text or paragraph styles based on a search for text or paragraph style;
merge an external style sheet with the default style sheet;
set string table values, for one configuration per command or all configurations at once.
Note that you can’t influence the ordering of different types of commands; they are done in this order:
file import;
file insertions;
document, configuration, string table and image property settings;
text and style replacements;
book compilation and checking.
Normally, Jutoh generates the HTML code for each book section. You can already customize HTML a little by marking content with the “HTML” paragraph style, and adding custom CSS though Jutoh style sheets and per document. HTML templates allow you to go a step further and replace parts or all of each HTML file with custom code edited within Jutoh.
Jutoh introduces the concept of ‘assets’, which are simply fragments of text to be inserted into each document file according to block markers in a special asset, the template. An asset could be JavaScript code, or custom CSS, or HTML content to insert into the body of the file. Each document can have an arbitrary number of named assets, including the template itself, and by inserting block markers in the template, you can instruct Jutoh to insert other assets into the template. The project itself also has a set of assets that can be used to create each HTML file, which means you can make document-specific assets override the project assets. Or you can use only project assets.
Jutoh’s ‘asset editor’ is used to add, delete and edit templates and other fragments for documents and for projects. To edit a document’s assets, you can use View | Asset Editor to switch from the normal editor view to the asset view, and back. The configurable syntax highlighting editor is a convenient way to edit code without recourse to an external editor.
In addition to assets, further code can be supplied using source code documents that you can add to your project and edit using the built-in code editor. They will be placed under the Resources folder in the project outline, and will be included in the ebook for you to refer to from document or project assets. For example, you could include JavaScript files that will be referenced from script tags in HTML documents. For a given source code document, you can specify which configurations the code will apply to, since you may wish to have the ability to generate different variants of your ebook with varying levels of complexity.
Currently, assets cannot be specified in scripts, but you can specify a Jutoh project template which may have customised project assets.
See Chapter 4: Using HTML Templates for more details.
Jutoh Plus can create HTML Help files used by Windows and wxWidgets applications. Windows HTML Help files have the extension CHM, and wxWidgets HTML Help files have the extension HTB. HTB files contain simplified HTML with no CSS, but the two formats otherwise have similar project, contents and keywords files. For more on this, please see Chapter 5: Creating HTML Help.
Jutoh Plus can be configured to emit additional messages during compilation or in the Inspector, tailored to the user’s needs. Normally find and replace presets are used within the Find and Replace dialog, for quick access to frequently-used find commands. But they can also be used to find issues in a project whenever you compile it; examples include:
highlighting any paragraphs formatted with the ‘Normal’ paragraph style rather than a more specific style;
highlighting any blank paragraphs;
checking for words that are frequently accidentally repeated, such as “his his”, “to to”, “at at”, and so on;
checking for known typos of character names;
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.
This facility can use preset libraries stored in the project itself, or in the global store, or a combination of both. For more information, please see the chapter Using Custom Checking. You can also search for “custom checking” in the Jutoh application help.
This feature allows bulk creation of customised books using a data file of information, via the Book | Batch Compile command. A typical use for this is when you are sending out advance copies and wish to discourage readers from distributing the book: you can add the customer’s name and other details to the title page, for example.
This works by assigning values from the data file to strings (variables) in a string table, and then replacing any variable names in the Jutoh project with the values from the string table, for example %CUSTOMER%. One book per record (line) in the data file is created. This is accomplished without scripting, and is very easy to use.
For more information on how to use this feature, please see the chapter Creating Personalised Books. You can also search for “creating personalised books” in the Jutoh application help.
We’ve seen how to edit and run a script, and what scripts can be used for. We’ve also introduced the concepts of HTML templates, assets and source code documents, and touched briefly on the other features of Jutoh Plus. Next we’ll delve into the details of script syntax.
Contents | Start | End | Previous: Preface | Next: Chapter 2: Script Syntax