It’s common to want to create different versions of your book for different distributors, formats or purposes. You may need different book identifiers, or different text describing where to buy the book, or perhaps you’d like to create a small sample for your web site that can be easily recreated when you update the book. Or you may need to add extra pages, blank or otherwise, for a print book. Or perhaps you need to include different audio or video media for different formats.
With Jutoh, you can do all this without needing to split your project into different copies, which can become a time-consuming, confusing mess. There are several ways of creating conditional content, suitable for different tasks or kinds of content, but they all depend on the fact that you can have multiple configurations, even for the same format. You might have a ‘Sample Epub’ configuration that creates an ebook containing the first couple of chapters of your book. So to create your sample, you just select ‘Sample Epub’ and press Compile. The different values of options in your configurations will determine how the book is created.
These are the different methods available to you for changing the book without editing content each time:
- Tagging section and media documents;
- Tagging chunks of content;
- Specifying string variables in your content;
- Specifying paragraph styles to include or omit.
Let’s look at each of these.
Tagging whole section and media documents
To include or exclude whole section documents, go the document properties and assign a tag name (or several tag names) to the Tags field. Open the document properties dialog using right click or control click over the project outline, or using the menu command Document | Document Properties (Shift+Alt+Enter).
Let’s say you wanted to be able to create a sample Epub. Create a new configuration called ‘Sample Epub’ using the ‘+’ button on the Configurations panel in Project Properties. To get there, press Edit next to the configuration drop-down in the Jutoh Control Panel (bottom left of the Jutoh window). Type ‘Epub Sample’ for the new configuration name, and select a configuration to base this one on, or just press OK to select a format. Once the configuration has been created, search for ‘Exclude sections matching tags’ in the search field at the bottom of the dialog. Type ‘notsample’ as the value for this option. Now press OK to close the Project Properties dialog, and for each section document you want to omit from the sample, type ‘notsample’ into the Tags field.
Now when you compile the ‘Sample Epub’ configuration, only the desired sections (not matching ‘notsample’) will be included. The other configurations will still compile the whole book because if the ‘Include/Exclude sections matching tags’ are left blank, the section is included.
You can add multiple media documents with the same or different file names and specify different tags for them, which are mentioned in ‘Include media documents matching tags’ and/or ‘Exclude media documents matching tags’. The appropriate media files will be written to the book. If the files have different names, you will also need to create multiple versions of the media object that references the media, using the ‘condition’ object (see below).
Tagging chunks of content
To include or exclude parts of a document, you can use the ‘condition’ object. Select the relevant text, then in the Objects tab in the Formatting Palette, double-click on ‘condition’. Your text will now be bracketed by the opening and closing markers of the ‘condition’ object. Click on the opening marker, and type a tag name into the Tags field. If you want, you can add notes so you can remember why you’re making this text conditional.
Now you can mention the tag in ‘Include content matching tags’ and/or ‘Exclude content matching tags’ in your configurations. For example, if you only want some text to appear in your Smashwords book, use the tag ‘smashwords’ and add it to ‘Include content matching tags’ in your Smashwords configuration.
You can mark up as much content as you like within a section document: from a single letter to multiple paragraphs. You can also move the markers around with cut and paste, or delete them both to remove the condition. You can also nest conditions within each other, but don’t overlap different spans of conditional text.
Specifying string variables in your content
You can specify variables in your content to be filled in when the configuration is compiled. For example, you could have two versions of your book where a character has a different name in each. Just use, say, %HERO% within the content, and have different configurations that reference different string tables where the value of HERO is either Joe Bloggs or Bob Smith.
What are string tables? Each project can have zero or many string tables, consisting of name/value pairs. So you could create two string tables in the ‘String tables’ panel of your Project Properties dialog, one called HeroJoe and one called HeroBob. HeroJoe has a string called HERO with a value of Joe Bloggs, and HeroBob has a string called HERO with a value of Bob Smith.
There are two more things you need to do to make this work. In each of your configurations, you need to reference the correct string table. So in your configuration ‘Hero Joe Epub’ you can set the option ‘Project string table’ to HeroJoe, and in your configuration ‘Hero Bob Epub’ you can set the option ‘Project string table’ to HeroBob. Also, check ‘Replace strings in content’ in both configurations or Jutoh will not bother looking for variables to replace.
You can use this mechanism to have different ISBN numbers in different configurations. If you have a variable %ISBN% in your project metadata, it will take its value from the relevant string table when you compile the project. You can also use the ‘Identifier’ configuration option to do the same thing, and leave the ‘Identifier’ metadata field blank, but the disadvantage of that approach is that you can’t mention the ISBN in your document content (for example, your title page) since there is no variable to use.
Specifying paragraph styles to include or omit
The idea here is to specify in each configuration which paragraph styles should be used to omit or keep text styled with them. This method predates the ‘condition’ method and is not recommended for new projects as it makes it difficult to specify arbitrary styles for your conditional text. Plus it’s not obvious at a glance which text is conditional, and can’t be used for arbitrary conditional text within a paragraph. You can read more about it in the topic “Working with conditional content” under “Jutoh User Guide” in the application help.
Managing multiple configurations
You can have as many configurations as you like, even with the same format specified. However, you will probably want to change the “Book file name” property to ensure that your ebook file names are unique and don’t overwrite each other. So you might set the values %FILENAME%_GooglePlay, %FILENAME%_Lulu, and so on. %FILENAME% will be replaced with the project filename and the correct extension will be appended.