Contents | Start | End | Previous: Chapter 1: Introduction to Jutoh Plus | Next: Chapter 3: Using the Command Line
In this chapter we’ll describe the anatomy of a Jutoh script in detail.
A Jutoh script has extension jutohscript and is composed of groups of variable/value pairs, in this form:
[Group Name]
Variable1=Value2
Variable2=Value2
The group names are arbitrary and not used by Jutoh except to report errors, but they must be unique. You can use multiple groups to process multiple files.
Jutoh scripting is not a procedural programming language and everything is specified using variable/value pairs. The value part may have a special syntax depending on the type of variable, for example comprising semicolon-separated named parameters – see the insertfile and search examples below. Variables can refer to project-wide or configuration-wide settings. Here’s a configuration-specific setting:
configs.Epub.HTML left margin=10
And a project-wide setting:
title=Lena
You can add a comment on its own line using a semicolon.
By default, Jutoh assumes that the script is encoded in UTF-8. If you want to change this, you can set the encoding in a comment at the top of the file, for example:
;;; encoding=windows-1252
Note that all backslashes, for example in file paths, must be escaped with an extra backslash. Alternatively, you can use forward slashes in paths on all operating systems.
If you wish to include a double quotation mark within a string, you can escape it with a single preceding backslash within a simple right-hand value (a string with or without quotation marks). However if the value is within a parameter, you must use two backslashes to escape the quotation mark. For example:
documents.Chapter 1.name="Chapter \"One\""
and:
insertfile=file:"none";new-section:"Chapter \\"One\\""
If you need to include an “=” character in the variable part of a command, you can escape it with a backslash to stop it being interpreted as the separator between variable and value.
You must specify the ‘actions’, a comma-separated list of keywords. For example:
actions=import,setproperties,compile,check
open
Opens the specified project.
import
Creates the specified project from the named source file, deleting the project first if it already exists.
reimport
Creates the specified project from the named source file, or if it exists, reimports into the existing project. Use project=this to specify the current project, and leave source blank to use the import file already existing in the project.
openorimport
Opens the project if it already exists, and creates it if it doesn't exist.
compile
Compiles the project after opening or creation.
check
Checks the ebook (Epub only).
setproperties
Sets the configuration and other properties if the main action is open, import or openorimport.
close
Closes the project after other actions have been completed.
compact
Compacts the project after other actions have been completed and before closing.
You must include the names of the configurations you're interested in, using the configs variable, which should be of the form:
configs=<Configuration Name 1>:<format 1>,<Configuration Name 2>:<format 2>, ...
Formats are represented by the normal extension: mobi, epub, odt, html, txt, htb, and mp3.
For example:
configs=Epub:epub,Mobipocket:mobi
source
For example: source=Lena.odt. This indicates the file to import, and can be ODT, DOCX, text, HTML or Epub. You can leave this blank if you are reimporting and the project contains an import file name (that is, you imported a file at least once before).
project
For example: project=%TITLE%_%AUTHOR%. This indicates the name of the project and can contain metadata keywords. You can also specify the value ‘this’, to indicate the currently loaded and selected project.
template
The template file to base the new project on. For example: template=MyTemplate.jutoh. For more information on templates, see below.
deleteexistingproject
Specify yes to delete an existing project if it exists, to avoid a prompt.
abortonerror
Specify no to continue processing other configurations if an error occurs.
titlepage
Specify simple to generate a title page from the metadata, or none. Valid on import only, and sets the value of the Generate title page property for all configurations. You can also set the property with the syntax configs.*.Generate title page=yes.
You can specify these properties for metadata, for either import or open actions:
author, title, copyright, date, description, ISBN, EAN, language, contributors, subject, publisher, website, metadata_source, metadata_identifier
(the case is significant). These can either be in the form:
ISBN=12345678
or:
ISBN:Epub=12345678
to specify either a configuration-independent or configuration-dependent value. If configuration-independent, the value will be inserted directly into the metadata. Otherwise, a keyword will be set in the metadata, and a configuration-specific string table value used which is substituted for the keyword when the ebook is generated.
metadata_identifier is an alternative to using ISBN or EAN and cannot be used in a configuration-specific form. The syntax of this property is:
metadata_identifier=value:"1234567";scheme:"URL"
You can specify the cover image or .dtempl cover design template file, on import only.
cover
Specify the cover image, with or without the configuration, for example cover=Lena.jpg or cover:Epub=Lena.jpg and cover:Mobipocket=Trees.dtempl
You can specify the method, pattern and style used for splitting the file into sections.
splitmethod
Can be one of pattern, style, pagebreak.
splitpattern
For example, Chapter*. The value can include wildcards and pipe (‘|’) separators for multiple patterns.
splitstyle
For example, Heading 1. The value can contain wildcards.
These variables control aspects of import for HTML/Epub import only.
import.parsecss
yes to parse CSS when importing HTML or Epub, no to use simple styles.
import.firstparagraphstyle
The style for first paragraphs after a title if import.parsecss is no.
import.subsequentparagraphstyle
The style for subsequent paragraphs if import.parsecss is no.
These variables determine how the table of contents will be created. removefromtoc is one of the few variables that does not have a direct equivalent in the GUI. The equivalent is a sequence of manual actions to remove items from the compiled table of contents.
toc
Can be simple, fromheadings or none.
tocmaxlevel
A maximum level to search, for example 3.
removefromtoc
A pipe (‘|’) separated list of section names to ignore.
toctitle
The table of contents title, default Table of Contents.
toctitlestyle
The style for the ToC title, default TOC Heading.
tocmatchstyleN
The style match at level N (between 1 and 6).
tocstyleN
The table of contents entry style to apply at level N (between 1 and 6).
These variables determine how footnotes will be formatted.
footnotes.autobuild
If using endnotes, this automatically rebuilds the endnotes when compiling if the value is yes.
footnotes.endnotes
If yes, an endnotes section will be created.
footnotes.alwaysapplyfootnotestyle
If yes, the designated footnote style will always be applied.
footnotes.epubtypemarkup
If yes, Epub 3 types will be applied to the endnotes page.
footnotes.asidemarkup
If yes, Epub 3 asides will be used for endnotes.
footnotes.title
The title for the endnotes section.
footnotes.titlestyle
The paragraph style for the endnotes title.
footnotes.notestyle
The paragraph style for each endnote.
footnotes.citationstyle
The character style for each footnote/endnote citation.
footnotes.numberingstyle
Either global or chapter.
footnotes.citationappearance
One of superscript, squarebrackets, none, or a custom string containing the keyword %REF%.
footnotes.referenceappearance
One of superscript, squarebrackets, none, or a custom string containing the keyword %REF%.
These variables control settings for the alphabetical index, bibliography, and fields (including automatic heading numbering).
index.autobuild
If yes, builds an alphabetical index section when compiling.
bibliography.autobuild
If yes, builds a bibliography section when compiling.
fields.autobuild
If yes, updates fields and numbered headings when compiling.
fields.autonumbering
If yes, enables automatic heading numbering based on outline settings.
These variables control settings for page layout. For more information, please search for page layout in the Jutoh help.
pagelayout.mode
Determines whether Jutoh makes simple page style decisions, or leaves it up to page styles. Can be one of basic (use configuration settings for page layout), manual (use page styles assigned to each section), and auto (use specified simple header and footer settings).
pagelayout.startnumbering
If auto, Jutoh will choose where to start numbering. Otherwise, the value is a section title used to determine when to start numbering.
pagelayout.header, pagelayout.footer
Each of these can be one of none, page-number, book-title, and book-chapter.
You can set arbitrary image, configuration and string table values using this syntax:
<context>.<object name>.<property name>=<property value>
or
<configuration or table name>.<property name>=<property value>
where <context> is one of configs, strings, globalstrings and objects. Currently objects is used to specify image properties, but may be extended to other content objects in the future.
For example:
configs.*.Maximum image width=999
configs.Epub.HTML left margin=10
objects.butterfly.maxwidth=100%
strings.*.TESTSTRING=Hello, this is a test string!
or just:
Epub.HTML left margin=10
You can use an asterisk for the configuration or table name, to denote all configurations or tables.
Use strings to specify project string tables, and globalstrings to specify global string tables. If a table is referenced but not found, it will be created.
You can set document properties with the syntax:
documents.<document title>.<property name>=<property value>
For example:
documents.Chapter 1.guide=start
Valid document properties are name (the title of the document), tags, guide, filename, showintoc, showinnavmap, showinspine, scripted, uses-svg, uses-mathml, uses-remote-resources, javascript, javascript-filename, javascript-at-bottom, css, css-filename, notes, epub-type, page-style-enabled, page-style-name, page-style-start-number, page-style-repeat.
Valid image (object) properties are leftpadding, rightpadding, toppadding, bottompadding, alt, width, height, maxwidth, maxheight, preserveoriginalformat, svg, alignment, name, id, url, pagelink. Values of these properties are as specified in the image properties dialog, apart from the pagelink property who syntax is:
objects.butterfly.pagelink=Section Title#bookmarkname
In image assignments such as the above, the image id can be used instead of the image name to identify individual instances of an image that might share the same name.
Unlike other types of property, object properties can also use parameter syntax. Using this, we can speed up object property setting by specifying a section document as follows:
objects.butterfly.width=document:Section Title;value:600
Note that all property setting specified in a script will be done in one lump, after other operations have taken place; you cannot interleave file import and property setting.
Specify a search operation with search. Search operations take parameters in the value part, of the form:
name1:"Value1";name2:"Value2";...
Valid search operations are: find-text, match-text (as find-text but with wildcards), and find-paragraph-style. Specify the title of a document (with optional wildcards) as the value of in-section to limit the replacement to one or more sections.
Valid replacement operations are replace-text and replace-paragraph-style.
replace-text cannot be used with match-text since pattern matching doesn’t specify a unique match string. If you specify a value of $EMPTY$ for replace-text, the empty string will be used.
Examples:
search=match-text:"*\\* \\* \\**";replace-paragraph-style:"Centre"
search=find-text:"In my job";replace-text:"In my incredibly interesting job";in-section:"Chapter One"
search=find-paragraph-style:"Normal";replace-paragraph-style:"Body Text"
The first example searches for two space-separated asterisks; they are escaped because normally an asterisk is a wildcard character matching zero or more characters. The escape character is a double-backslash because the backslash character is also a special character in script syntax, and has to be escaped itself.
You can use the insertfile operation to insert files into existing sections or as new sections. DOCX, ODT, HTML, text, bitmap image and media files may currently be specified. If inserting text, the file should be in the encoding specified for the project, which defaults to UTF-8, or you can use the encoding parameter.
Creating a new document section with new-section
The value of the new-section parameter is the new section title. Also specify the document position with after-section or before-section, and/or parent-section, or omit these to append to the end of the book. Specify the file name with file. You cannot use new-section for image insertion.
after-section and before-section can take the values “first-section” and “last-section” as well as section titles.
You can specify the new document’s guide type (such as “toc”) with the guide-type parameter.
Inserting content into an existing section with in-section
For the in-section parameter, specify the name of the section to insert into (or ‘*’ for all documents). Specify the new content file name with file. Also specify one of at-start (“yes”), at-end (“yes”), or a keyword to replace. The paragraph containing the keyword will be deleted. To insert before or after the paragraph containing certain text without deleting the existing text, specify before-text or after-text. This text is case-sensitive, matches anywhere in the paragraph and doesn’t take wildcards.
You can specify a paragraph style to apply to all paragraphs in the newly-inserted content using the style parameter. For text files, you can specify the encoding to use with the encoding parameter; otherwise the project encoding will be used, defaulting to UTF-8.
If you specify clear:yes, the section will be cleared before content insertion. This also applies to inserting images and media objects.
Inserting images into an existing section with in-section
The parameters are as above, but also specify name to identify a new image, id to set the image identifier, and class to set the CSS class. You can also use width, height, max-width, max-height, padding, left-padding, top-padding, right-padding, bottom-padding (include units with dimensions), and alt (for alternate text). Specify an optional alignment with the value “none”, “left” or “right”.
Inserting media objects into an existing section with in-section
The parameters are as above, but you must specify media-kind as “video”, “audio”, or “image.” The file parameter is the media file, which will be added to the project’s Resources section if it has not already been added, and you can specify an image poster file with the poster parameter. Pass the value “yes” to show-controls if you wish media controls to be shown.
Examples:
insertfile=file:"TextChunk.odt";new-section:"My New Section";after-section:"Lena"
insertfile=file:"TextChunk.odt";in-section:"Lena";at-end:"yes"
insertfile=file:"TextChunk.docx";new-section:"My New Section";parent-section:"Lena"
insertfile=file:"TextChunk.odt";in-section:"Lena";at-start:"yes"
insertfile=file:"TextChunk.odt";in-section:"*";keyword:"%MYTEXT%"
insertfile=file:"butterfly.png";in-section:"*";keyword:"%MYIMAGE%";name:"butterfly";id:"imageid1";class:"animals"
insertfile=media-kind:video;poster:poster.png;alignment:none;width:"90%";max-width:"100%";padding:"1cm";right-padding:"1cm";alt:"Fox video";title:"A fox";show-controls:yes;file:"fox.m4v";in-section:"Chapter 3";at-end:"yes"
insertfile=file:"TextChunk.odt";in-section:"*";before-text:"In my"
The insertresource command lets you insert arbitrary resources into the project. Use the parameters file, mimetype and resource-location. For example:
insertresource=file:"MyAudio.mp4";mimetype:"audio/mp4";location:"resources/MyAudio.mp4"
You can use the deletesection operation to delete one or more sections. Use title:"PATTERN" to specify the title of the sections to delete. If the pattern contains an asterisk, the pattern is assumed to contain wildcards, otherwise an exact title match is performed.
You can specify a Jutoh style sheet file to import or merge on project creation. If you specify importstylesheet, the style sheets will be added to the existing style sheets and any name clash will result in the new sheets overriding the old sheets.
If you specify mergestylesheet, only the first sheet in the file will be used and it will be merged with the default style sheet, with any new styles overriding existing ones. You can use this to incorporate custom styles, which you might then use by doing a style search and replace operation.
Examples:
importstylesheet=MyStyles.stylesheet
mergestylesheet=MyStyles.stylesheet
Style sheets can be used when importing, or applied when opening an existing project file.
You can specify a Jutoh project to use as a template using the template variable, which will be applied before import, or after opening an existing project. You can control whether parts of the template will be merged with imported data, discarded, or kept. These specifiers follow the pattern of template:<element>=<value> where <value> is one of keep (retain this template information and ignore imported/specified information), discard (ignore this template information) and merge (merge this template information with specified or imported information, with priority given to the latter). Currently, merge only works for metadata, and otherwise is simply a synonym for keep.
Specify a template file like this:
template=MyTemplate.jutoh
These specifiers are supported (the defaults are asterisked):
template:accessibility – accessibility options, as set via Project Properties/Accessibility. One of keep*, discard
template:bibinfo – the bibliography options, as set via Project Properties/Indexes/Bibliography. One of keep*, discard
template:bullets – the ODT bullet information, as set via Project Properties/Options/ODT Options. One of keep*, discard
template:configurations – the configurations. One of keep*, discard
template:content – contents of the "Content" folder. One of keep*, discard
template:covers – the cover design(s). One of keep*, discard
template:fixedlayout – the fixed layout project options, as set via Project Properties/Fixed Layout. One of keep*, discard
template:footnotes – the footnote options. One of keep*, discard
template:htmlhelp – the HTML Help options, as set via Project Properties/HTML Help. One of keep*, discard
template:index – the index options. One of keep*, discard
template:metadata – the metadata such as title, author. One of keep, discard, merge*
template:linkstyles – link styles as edited via Project Properties/Styles/Link Styles One of keep*, discard
template:options – miscellaneous options such as titlepage; for internal Jutoh use only. One of keep*, discard
template:outlinestyles – outline styles as edited via Project Properties/Fields & Numbering. One of keep*, discard
template:pagelayout – page layout options as edited via Project Properties/Page Layout. One of keep*, discard
template:pagestyles – page styles as edited via Project Properties/Page Layout/Manage Page Styles. One of keep*, discard
template:projectoptions – various project options as edited via Project Properties/Options. One of keep*, discard
template:regions – fixed layout magnification region settings, as edited via Project Properties/Fixed Layout. One of keep*, discard
template:resources – contents of the "Resources" folder. One of keep*, discard
template:sequencedefinitions – sequence definitions as edited via Project Properties/Fields & Numbering/Edit Sequence Definitions. One of keep*, discard
template:shortcuts – the custom project shortcuts (associated with styles). One of keep*, discard
template:stringtables – the string tables. One of keep*, discard
template:styles – the style sheets. One of keep, discard
template:toc – the table of contents options. One of keep*, discard
You have learned how to create a script for creating and altering ebooks. For an example, please see Appendix A: A sample script. Next we will look at how to control scripting from the command line.
Contents | Start | End | Previous: Chapter 1: Introduction to Jutoh Plus | Next: Chapter 3: Using the Command Line