Sigil User Guide

Version 0.6.0

Dave Heiland

Copyright ©2012 Dave Heiland

All rights reserved.

This work is licensed under a Creative Commons 3.0 Attribution-Share License

Use of these materials is permitted only in accordance with license rights granted. Materials provided “AS IS”; no representations or warranties provided. User assumes all responsibility for use, and all liability related thereto, and must independently review all materials for accuracy and efficacy.

INTRODUCTION

— WELCOME TO SIGIL —

Sigil is an easy to use and powerful editor that is designed to provide professional and amateur publishers, editors and authors the ability to precisely control the design and appearance of EPUB ebooks.

Sigil software and documentation is available online:

Sigil Official Website [http://code.google.com/p/sigil/]

EPUB version of the Sigil User Guide [http://code.google.com/p/sigil/downloads/list]

Help with Sigil is available from Sigil users at MobileRead:

Sigil Forum @ MobileRead [http://www.mobileread.com/forums/forumdisplay.php?f=203]

ABOUT SIGIL

Sigil is used to create EPUB ebooks from HTML files and to modify the formatting of existing EPUBs. It is used by both individuals cleaning up a few ebooks for personal use and by professional editing companies publishing books on multiple platforms. Although you can use Sigil with its WYSIWYG editor to write your book, most authors using Sigil typically use their favorite editor for writing and then use Sigil to edit it to achieve the appearance they want and to package it into an EPUB.

Sigil was created by Strahinja Markovic in 2009 as completely free and open-source software. John Schember is currently the lead developer and has been since 2011 when he volunteered to become the new maintainer of Sigil. Other volunteers contribute code, translations and documentation to Sigil. See the Help→About menu in Sigil for a complete list of contributors.

This User Guide was created entirely in Sigil – you can load the EPUB version of this guide into Sigil to see an example EPUB ebook.

ABOUT EPUB

The EPUB (electronic publication) format is one of the most popular formats for ebooks. It is an open and freely available format that can be used by anyone.

An EPUB ebook is just a file containing several other files stored together using the common zip format. These files include your words, images, Table of Contents, stylesheets, fonts and details about your book like author or title. EPUB's standard format means your book can be read on many ereaders.

Words and text are actually stored in the EPUB book using the HTML format (Hyper Text Markup Language – the same code used by web pages to display text and images). HTML files contain your text along with markup codes and tags (like <h1> or <p>) which tell ereaders how to format and display the text – some words could be bold or italic, others could be a paragraph or a heading, etc.

Although you can use only HTML tags to control or style the layout, EPUB books typically make use of stylesheets to help organize the use of styles used by the HTML file. A stylesheet is another file in the EPUB that contains a list of HTML tags along with instructions on how to display any text using that tag, e.g. <h1> (heading level 1) should be larger and centered. This allows you to separate the content of your book from its layout and allows you to easily adjust the look of the EPUB.

Of course, when anyone actually reads an EPUB they don’t see all these HTML files or stylesheets. The ereader just displays the text and images like a normal book as close as it can to the formatting you defined, even if there are thousands of pages or files.

You don't have to understand all the details of the EPUB format or understand HTML formatting codes to start using Sigil. However, if you spend any time with Sigil you will soon need to become familiar with these areas in order to get the most out of the advanced features of Sigil, and ultimately to achieve the design you want.

Note

Technically the text files are in XHTML format (an XML compliant version of HTML), but to keep things simpler we'll use HTML to refer to either HTML or XHTML in this guide.

To learn more about HTML you can read various online guides, including:

W3Schools HTML Guide [http://www.w3schools.com/html/]

Help with EPUB is available from EPUB users at MobileRead:

EPUB Forum @ MobileRead [http://www.mobileread.com/forums/forumdisplay.php?f=179]

If you really want to dig into the details of the official EPUB standard on which Sigil is built you can read the original technical specifications:

Official EPUB 2.0.1 IDPF Standard [http://idpf.org/epub/201]

- OPS (Open Publication Structure): the key specification which describes everything in an EPUB file

- OPF (Open Packaging Format): how the EPUB files relate to each other, metadata details (content.opf)

- OCF (OEBPS Container Format): how files are packaged into a .epub

A great way to learn about EPUB is to find an EPUB ebook that is formatted how you like, load it into Sigil and look at it.

CONTENTS

The Sigil User Guide includes documentation that will help you get the best out of editing your EPUB, including:

- Introduction: this section

- Installation: installing Sigil on Windows, MAC and Linux

- Features: the complete description of all of Sigil's features

- Tutorials: step by step guides for common activities in Sigil

- FAQ: frequently asked questions about Sigil

- Contributing to Sigil: how to support Sigil

INSTALLATION

— DOWNLOADING SIGIL —

You can download the latest version of Sigil from the official Sigil web site and install it for your OS.

WINDOWS

Sigil can run on Windows XP, Vista, or Windows 7.

Download Sigil [http://code.google.com/p/sigil/downloads/list]

Download the version that matches your version of Windows. If you are not certain which version of Windows you are running, use the 32 bit version:

- 32 bit: Sigil-0.6.0-Windows-Setup.exe

- 64 bit: Sigil-0.6.0-Windows-x64-Setup.exe

Then just double click the file to run the installer.

If you get a message about Sigil not being “a valid Win32 application”, you downloaded the 64 bit version by mistake and should download the 32 bit version.

MAC

Sigil can run on MAC OS 10.6 (Snow Leopard) x64 bit only or higher.

Download Sigil [http://code.google.com/p/sigil/downloads/list]

Unpack the DMG file and drag the “Sigil.app” file to your Applications folder, e.g.

Sigil-0.6.0-Mac-Package.dmg

LINUX

A binary version of Sigil is no longer provided since there are so many versions of Linux.

However, due to the effort of many volunteers, there is most likely a pre-packaged version of Sigil built for your Linux distribution available online:

Sigil Linux Distribution Packages [http://code.google.com/p/sigil/wiki/LinuxDistroPackages]

FEATURES

— AN IN-DEPTH GUIDE —

This section describes all of Sigil's functions in detail.

You can also read the Tutorials chapter for step-by-step instructions on common tasks in Sigil, and then refer back to this section for additional details.

OVERVIEW

— SIGIL HIGHLIGHTS —

This is a quick summary of features in Sigil.

EDITING

Sigil provides two ways to edit your book – Book View and Code View. The Book View editor is a WYSIWYG editor (based on CKEditor [http://ckeditor.com]) which is useful when you need to make basic changes. The Code View editor on the other hand allows you to directly edit the HTML formatting of your files when you want complete control over your book or you want to use Sigil's advanced features. There is also a read-only Preview View which allows you to test modifying styles and to inspect your code in detail. Tabs are opened for each of the files in the EPUB that you edit, and you can even magnify the text. Spell checking with multiple dictionaries is also available.

FIND & REPLACE

The ability to search for or replace text is one of the most powerful functions in Sigil. Book View provides a basic find function, but Find & Replace is usually used in Code View where all its features are available and it can be used to change or correct formatting and styles. You can search or replace in one file or in all the files at once, and you can search for simple text or use Regular Expressions.

MANAGING FILES

The Book Browser organizes all your files by type and gives you quick access to open files or to modify them. Double-click a file to open it in the editing window, or right-click on selected files to see options for renaming, deleting, merging, adding, linking stylesheets, etc. The HTML files are listed in the order they appear in your book – and you can drag and drop them to reorder them.

TABLE OF CONTENTS

The Table of Contents (TOC) window shows you exactly what your TOC will look like, and allows you to jump to specific chapters by clicking on chapter names. You can also generate a new TOC based on headings in your book at any time, and create an HTML version of your TOC.

MODIFYING BOOK DETAILS

The Metadata Editor provides a quick way to update book details like Title, Author, and Language. You can add any of the hundreds of standard EPUB metadata entries like publication date, co-authors, copyright information, etc.

PREFERENCES

Many settings in Sigil can be customised by opening the Preferences window. In particular you can set Sigil's user interface language, keyboard shortcuts and dictionaries.

VALIDATION

Sigil performs automatic checking of your code to highlight errors when saving, and it includes the FlightCrew EPUB validator [http://code.google.com/p/flightcrew/] to help ensure your book conforms to EPUB standards. Sigil can also automatically clean and format your code using HTML Tidy [http://tidy.sourceforge.net/].

LANGUAGE SUPPORT

Sigil has been translated into over 15 languages and makes it easy to change the user interface language as needed. It is written in C++ for high performance and includes full Unicode UTF-16 support.

USER INTERFACE

— WINDOWS, MENUS AND TOOLBARS —

Sigil provides several ways to use its features and run commands: main menu entries (like File→Open), icons on toolbars, keyboard shortcuts (like Ctrl+S to save your file), and Context Menus (shown when you right click on something like a filename).

The main actions are shown below, but you should refer to individual chapters in the guide for more details, including Book View icons and context menu options.

Note

Since Sigil runs on many OS's the screenshots in the User Guide may not exactly match what you see on your computer.

WINDOWS

Sigil uses various windows in the main interface to present information: a window to show your files, to edit your book, to view your table of contents, etc.

Certain windows can be moved. For example, you can move the Table of Contents window to the left under the Book Browser instead of on the right, and you can even undock some windows (separate them from the main Sigil window):

To move, dock or undock a window click on the heading of the window and drag it to its new location. (In some OS's you can also undock and re-dock the windows by clicking on the little icon in the top right corner of the Book Browser or TOC window.)

Tip

To re-dock a separate window, double click on its title bar.

To hide or show specific windows use the View menu.

MAIN MENU

This is the list of menu items that is always at the top of Sigil's window or your screen:

File

- New:

- New Book: create a new, empty EPUB

- Blank Section: create a new HTML file in the book

- Blank Stylesheet: create a new CSS Stylesheet in the book

- Add Existing File(s): add HTML files, images, etc. from your computer

- Open: open an EPUB or HTML file from your computer – see the Open and Save Files chapter

- Save: save your file (use often!)

- Save As: save your file under a different name

- Print Preview: preview the printing of the current tab

- Print: print the current tab

- Validate EPUB: check if your book meets EPUB standards (see Validate and Clean)

- List of recently opened files

- Quit: exit Sigil, asking if you want to save your file first if it hasn't been saved

Edit

- Undo: restore text just deleted, inserted or replaced

- Redo: reverse the last Undo

- Cut: remove the selected text and store it for paste

- Copy: copy the selected text and store it for paste

- Paste: insert previously cut or copied text into your document

- Metadata Editor: open the Metadata Editor – see the Metadata Editor chapter

- Insert Image: insert an image in the EPUB into the text – see the Images chapter

- Split Chapter: split the current file into 2 files at the end of the paragraph – see the Splitting and Merging chapter

- Insert Chapter Marker: insert a chapter marker to use for splitting

- Split at Chapter Markers: split the current file at inserted chapter markers

- Clean Source: see the Validate and Clean chapter (you must restart Sigil for new settings to take effect)

- Off: no automatic cleaning of code will be done

- Pretty Print: clean up spacing and layout of code but do not change any code

- Tidy: clean up code, convert some formats to inline styles, etc.

- Check For Well-Formed Errors: check for invalid HTML – see the Validate and Clean chapter

- Preferences: open the Preferences window – see the Preferences chapter

Search

- Find / Replace: open the Find & Replace window – see the Find & Replace chapter

- Find Next: search forwards for the next matching text

- Find Previous: search backwards for the next matching text

- Replace Next: replace any matched text and search forwards for the next matching text

- Replace Previous: replace any matched text and search backwards for the next matching text

- Replace All: replace every matching text according to the Find & Replace settings

- Count All: count every matching text according to the Find & Replace settings

- Go to Line: jump to a specific line number in Code View

View

- Toolbars

- File: show or hide the open and save icons

- Edit: show or hide the undo and cut icons

- View: show or hide the Book and Code view icons

- Insert: show or hide the insert chapter and image icons

- Donate: show or hide the Donate icon

- Quick Settings: show or hide the quick settings icons

- Book View: switch to Book View for editing

- Preview View: switch to Preview View for reviewing

- Code View: switch to Code View for editing

- Zoom In: increase the size of text and images in the view

- Zoom Out: decrease the size of text and images in the view

- Zoom Reset: reset the window zoom to 100%

- Book Browser: open or close the book browser window

- Validation Results: open or close the validation window

- Table of Contents: open or close the TOC window

Window

- Next Tab: change view to the following tab

- Previous Tab: change view to the preceding tab

- Close Tab: close the current tab

- Close Other Tabs: close all tabs other than the current tab

- Open Previous File: open the file above the selected file in the Book Browser

- Open Next File: open the file below the selected file in the Book Browser

Help

- User Guide: the official Sigil User Guide

- Frequently Asked Questions: common questions about Sigil

- Tutorials: step by step guides to using Sigil

- Donate: how to donate to ongoing development

- Report an Issue: how to submit a bug report

- Sigil DevBlog: occasional updates about development

- About: Sigil version and author information

MAIN TOOLBAR

This is the list of icons that are always at the top of Sigil's window:

Tip

You can move sets of icons around to change their order or to place them to the left or right of the main window. Click and hold on the small bar to the left of each group of icons, then drag it to where you want it.

Right click on the toolbar to easily select which icons or windows to show.

The icons are listed below with their equivalent menu entry.

- New: File→New→New Book

- Open: File→Open

- Save: File→Save

- Save As: File→Save As

- Undo: Edit→Undo

- Redo: Edit→Redo

- Cut: Edit→Cut

- Copy: Edit→Copy

- Paste: Edit→Paste

- Find & Replace: Search→Find / Replace

- Book View: View→Book View

- Preview View: View→Preview View

- Code View: View→Code View

- Split Chapter: Edit→Split Chapter

- Insert Image: Edit→Insert Image

- Donate: Help→Donate

- Check For Well-Formed Errors: Edit→Check For Well-formed errors

- Validate: File→Validate Epub

KEYBOARD SHORTCUTS

Keyboard shortcuts (e.g. Ctrl+S for Save) are shown next to menu entries and in Keyboard Shortcuts in Edit→Preferences.

You can change the default keyboard shortcuts in Preferences.

CONTEXT MENUS

Context Menus are menus that appear when you right-click on something – like a file in the Book Browser or a misspelled word in Code View. Context menu items are discussed in related chapters.

Tip

When in doubt, right-click on something to see if there are additional actions available!

ZOOM

On the lower right of the main window is a zoom control that lets you shrink or enlarge the text and images in the main view:

The 100% indicates the zoom level of the view and this percentage will increase or decrease when you click on the + or – icons.

STATUS BAR

The bottom area on the main window (to the left of the zoom control) will occasionally list status information when an action is completed, like File Saved.

The status bar can also show information about the currently opened file, such as Line and Column in Code View.

TOOLTIPS

Many of the buttons, dropdown boxes, labels and fields have tooltips that provide information on how they are used.

To see a tooltip just hover your mouse over the button or other item and the help text should be displayed.

OPEN AND SAVE FILES

— LOAD AND SAVE YOUR BOOKS —

Sigil supports opening EPUB files and importing HTML files. However, Sigil always saves books as EPUB files. The EPUB file will contain all your HTML files, images, stylesheets, fonts, etc. zipped up into one file.

Tip

You should save your file immediately after opening in Sigil for the first time so that Sigil can check for errors and convert your book to EPUB.

IMPORTING AND ADDING DOCUMENTS

OPEN FILES

To open a file, use File→Open and select the file you want to open:

EPUB Files

- Everything in the EPUB file is loaded automatically – HTML files, images, stylesheets, metadata, etc.

- Sigil will attempt to organise your files into standard folders as shown in the Book Browser.

- Sigil will also attempt to clean up the EPUB for spacing and minor issues depending on your preferences.

HTML Files

- The file and and linked files, images or stylesheets are imported if possible and placed into the appropriate folders.

- The metadata in the HTML file will be loaded into the metadata for the book.

- Sigil will attempt to cleanup the HTML file for spacing and minor issues depending on your preferences.

ADD FILES

To add files to your EPUB, use File→New→Add Existing Files:

HTML Files

- Metadata is not loaded from the file (unlike when you use Open).

- Sigil will attempt to load any files such as images, fonts that are referenced.

- Files will be placed into the Text folder.

Image Files

- Files will be placed into the Images folder.

Stylesheet Files

- Files will be placed into the Styles folder.

Font Files

- Files will be placed into the Fonts folder.

Other Files

- All other files will be placed in the Misc folder. These miscellaneous files cannot be edited in Sigil.

Note

If there are any errors while opening your file, Sigil may fail and may give you a warning. Sigil cannot read EPUB files or documents that are very badly formatted or non-standard. You may need to open the file (using standard zip programs like WinZip or 7Zip) and correct the errors before reloading it into Sigil.

SAVING YOUR BOOK

Use File→Save or Ctrl+S to save your book. You should always save your document before doing major edits in case you want to undo them.

Tip

If you edit any text in your document, an asterisk ('*') is added to the file's name in the titlebar.

When you save your book Sigil will check it for errors and warn you if you need to fix anything.

Sigil will not save a corrupt EPUB, so frequent saves will make it easier to recover from any unexpected errors. Sigil will also clean your source code according to your preferences when saving the file. See the Validate and Clean chapter for more details.

BOOK VIEW

— WYSIWYG EDITING —

Book View (or WYSIWYG mode – what you see is what you get) is one of two ways you can edit your book in Sigil. Book View is what most people use when they start to use Sigil since its the closest to a standard word processor. Its a good way to make basic changes to your book when you aren't too concerned about the underlying HTML code. However, when you want more control over the format of your EPUB or to use Sigil's advanced features then you can use Code View. You can switch between Book View and Code View at any time.

To switch to Book View use View→Book View or its toolbar icon or keyboard shortcut:

Note

Certain features, like advanced Find & Replace and Spell Check are only available in Code View.

Book View will do its best to apply the style you intended, but occasionally it will guess wrong and you will need to reformat it. It may even be necessary to use Code View to adjust the formatting.

If you delete a blank line in Book View, you should click at the end of the previous paragraph then press the Delete key, or use the Backspace key – this is because you will lose the formatting of the following paragraph or header if you press Delete on the blank line.

Sometimes parts of the text are highlighted even though they are not selected. This is a bug in the Qt libraries used by Sigil and cannot be avoided.

If you edit some text and the style looks completely wrong, try switching to Code View and back to Book View as this may help refresh the screen.

If you change styles using stylesheets then you may need to save and re-open your book to see the new styles.

Tip

At the bottom of the Book View window you can see the HTML formatting tags that are applied to the text you have selected.

TOOLBAR ICONS

In addition to the standard main toolbar icons like Undo, Copy and Paste, the Book View Editor has its own toolbar:

Details of each what each icon is used for is below:

- Paste as plain text: standard paste of text

- Paste from Word: removes certain styling from text copied from Word to avoid issues

- B: make text bold

- I: make text italic

- U: make text underlined

- abc: make text striked through

- X_2: make text subscript

- X^2: make text superscript, useful for footnotes (but harder to use on touch screens)

- Erase: remove basic formatting (styles, classes but not ids) from selected text

- Numbered List: change text into a list of items preceded by numbers

- Bullet List: change text into a list of items preceded by dots

- Outdent: remove an indent from the text

- Indent: move text to the right

- Block Quote: change text into a separate paragraph that may be treated as a quotation

- Left Justify: align text to the left margin

- Center: align text centered on the screen

- Right Justify: align text to the right margin

- Normal: reset to unjustified text

- Left to Right: set the direction of text from left to right

- Right to Left: set the direction of text from right to left

- Link: create or edit a link for the selected text – see the Links and Footnotes chapter

- Unlink: remove a link from the selected text

- Anchor: create an anchor tag with an ID using the selected text – to use the text as the destination for a link

- Table: insert simple tables, best used for data not for formatting text

- Insert horizontal line: insert a line in the text

- Insert special character: choose from special characters like Æ, ©, →, £, ½, É to insert

- Format: contains formats to use for Chapter Headings (use Normal to change back to a standard paragraph and the erase icon to remove old formatting or style classes)

- Text Color: set the color of the text

- Background Color: set the color of the text background

Tip

Double click on an image to show the image's filename.

CUSTOMIZING THE TOOLBAR

The Book View editor uses the open-source CKEditor software. This is an extremely flexible editor that can be customized by advanced users.

Warning

Customizing the CKEditor settings is not supported, and it could result in some things breaking. If you are willing to customize the look of the Book View editor, then it may be better if you considering using Code View instead where you can control even more of what formats are used.

To modify the look and functionality of the Book View editor in Sigil you need to create a custom configuration file that Sigil will read when it starts. You can use this file to change what buttons are displayed, what menu items are shown for the editor, and what formats are applied when you select the icons or menu entries.

The official CKEditor documentation listing all the available configuration options is available at:

CKEditor Documentation [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html]

In Sigil, you need to create this file

ckeditor_config.js

and store it in Sigil's user directory (on linux this is '$HOME/.local/share/data/sigil-ebook/sigil/. You can find it by going to Spell Check in Preferences and selecting Open Dictionary Directory, then going up one level once the directory is open.

Here is a configuration file as an example:

CKEDITOR.editorConfig = function(config)

{

// Toolbar example - commenting some icons out from default settings

config.toolbarCanCollapse = false;

config.toolbar = 'Full';

config.toolbar_Full =

[

{ name: 'clipboard', items : [ 'PasteText','PasteFromWord' ] },

{ name: 'basicstyles', items : [ 'Bold','Italic','Underline','Strike','Subscript','Superscript','-','RemoveFormat' ] },

{ name: 'format', items : [ 'NumberedList','BulletedList','-','Outdent','Indent','-','Blockquote','CreateDiv', ] },

{ name: 'align', items : ['JustifyLeft','JustifyCenter','JustifyRight','JustifyBlock' ] },

//{ name: 'direction', items : [ 'BidiLtr','BidiRtl' ] },

{ name: 'links', items : [ 'Link','Unlink','Anchor' ] },

{ name: 'insert', items : [ 'Table','HorizontalRule','SpecialChar','PageBreak' ] },

{ name: 'styles', items : [ 'Styles','Format','Font','FontSize' ] },

//{ name: 'colors', items : [ 'TextColor','BGColor' ] },

]

// Size Menu

config.fontSize_sizes = '80%/80%;90%/90%;100%/;110%/110%;120%/120%;1 em/1em; 2em/2em';

config.font_names =

'Arial/Arial, Helvetica, sans-serif;';

// Styles Menu - class names must be defined in your CSS in order to be useful

config.stylesSet = [

{ name : 'Strong', element : 'strong' },

{ name : 'Emphasis', element : 'em' },

{ name : 'Span Class Example',

element : 'span',

attributes : { 'class' : 'example' } },

];

};

CODE VIEW

— DIRECT HTML EDITING —

Code View allows you to directly edit the HTML code that makes up your EPUB.

To switch to Code View use View→Code View or its toolbar icon or keyboard shortcut:

In addition to displaying your HTML code exactly as it is stored, Code View highlights tags and elements in colors to make it easier to read and identify issues.

Code View gives you access to several features described elsewhere in the User Guide such as Replace in Find & Replace and Spell Check (words that are misspelled are underlined in red if this feature is active.

Tip

When switching from Code View to another window or saving your file, Sigil will check if your code has any major errors if the Well-Formed Check is enabled. If there are any errors you will be prompted to correct them Manually or Automatically. You should usually choose Manually to fix the issue to avoid any chance of the Automatic correction deleting text.

Note

If you have any entities in your code, e.g. &#257; and you make any changes while in Book View, then when you switch back to Code View you will see that Book View converted most of those entities into their actual character, e.g. ā. So after editing in Book View your entities will be shown as characters even when viewed in Code View.

PREVIEW VIEW

— TEST LINKS AND STYLES —

The Preview View is a read-only view of your HTML files. You can use it to test links and review your document's appearance. You can also use the advanced code inspector to make temporary changes to styles to see what affect this has.

Any edits you make in this view will not be saved:

Tip

The dividing bar between the preview and inspector areas can be dragged to resize the areas.

PREVIEW AREA

This window shows your book as it will appear to readers, exactly the same as the Book View except that you cannot edit the text.

You can test links in this view by clicking on a link.

Tip

If your link opens a new file, just close the new tab when you are done checking it and you'll be switched back to the original tab with the link.

INSPECTOR AREA

This is an HTML developer's tool that allows detailed examination of the code behind the book's appearance. It is intended to allow you to see why specific sections of your book are displayed the way they are and to make temporary changes to styles and text.

Warning

Any changes you make in the Inspector area are only temporary and are not saved!

The Inspector is basically the Chrome web developer toolset and you can find more information about it from their documentation. Not all the information applies to Sigil since the software is meant for general web page inspection. Scroll down to the Developer Window section to see what functions are available:

- Inspector for Chrome Developer Tools [https://code.google.com/p/sigil-developer-tools/docs/overview]

The typical use of the Inspector is to click on the magnifying glass at the bottom of the Inspector then scroll the preview area to the text of your book that you want to inspect and click on it. The inspector pane will scroll to the related section of code, allowing you to view various details about the text.

You can then make modifications to the styles used by the text to test out changes. Changes to styles are reflected immediately in the Preview area, but if you edit any text you may need to click in the Preview area to refresh it. You can then edit your CSS stylesheets to include any changes you decide to keep.

Note

If you click on an area in the inspector area, the preview area will not sync as you might expect.

BOOK BROWSER

— MANAGING YOUR FILES —

All of the files that make up an EPUB can be accessed by the Book Browser. Your HTML text files, images, as well as any fonts or stylesheets, are organized into folders allowing easy access to open them or right-click on them to perform actions on them.

You can open the Book Browser using the menu View→Book Browser or its keyboard shortcut:

FOLDERS & FILES

The Book Browser organizes your files into several folders which can be expanded or collapsed by clicking on the little arrow icon to the left of the folder’s name. The folders and files include:

- Text: the XHTML, HTML, XML, HTM files that make up the text of the book

- Styles: the CSS and XPGT stylesheets that control the formatting of the book

- Images: the PNG, JPG, GIF image types in the book

- Fonts: the TTF and OTF embedded fonts that might be in the book

- Misc: other files, which are not typically used by EPUB readers even though they can be stored with the book

- toc.ncx: the file containing the table of contents of the book (usually not edited manually)

- content.opf: the file containing the list of files in the book (usually not edited manually)

To open a file just double-click on it. If the file was not already open in a tab, a new tab will be created for it. If it was already open in a tab the view will switch to the tab containing the file.

SELECTING MULTIPLE FILES

You can select multiple files in the Book Browser by clicking on one entry, and then holding the Shift key while clicking another entry to select all entries between and including the two entries. You can also hold down the Ctrl key while clicking to add individual files to your selection. You can also use the right-click context menu to select all entries easily. Once you've selected your files you can then use menu options or the right-click context menu to perform actions on all the selected files.

You can only select multiple items within the same folder.

RE-ORDERING FILES

The order of the files in the Text folder is important since it is the order in which the files will be displayed to readers.

You can drag a file in the Text folder and move it up or down if you need to re-arrange the order in which the chapters or files appear in your book.

Tip

You can also use the context menu to rename or re-sort the files.

All other folders are automatically sorted alphabetically and cannot be re-arranged (the order of their files does not affect how your book is displayed).

CONTEXT MENU

Right-clicking on one or more items in the Book Browser brings up a context menu with relevant actions:

The following sections describe the available context menu actions.

ADD EXISTING FILES

Opens a dialog window to allow you to choose one or more files from your computer to add to your EPUB.

Files will be added to the appropriate folder based on their file extension regardless of what file you right-clicked on.

This is the same as the main menu option File→New→Add Existing File(s)

ADD BLANK SECTION/STYLESHEET

For HTML or Style files.

Adds a blank HTML document or CSS Stylesheet to the folder just below the file you right-clicked on, or at the bottom of the appropriate folder if you right-clicked on the folder name.

This is the same as the main menu option File→New→Add Blank Section if you right-clicked on an HTML file, or File→New→Add Blank Stylesheet if you right-clicked a stylesheet.

REMOVE

Delete the selected files. You will be prompted to confirm you want to delete since the action cannot be undone. You cannot delete the last remaining HTML file.

Remember to update the TOC if your file was included in the Table of Contents.

RENAME

If you select a single file to rename, then the name of the file is highlighted so that you can type in its new name. By default the extension is not highlighted to make renaming easier, but you can also change the extension if necessary.

If you select multiple files, then a new dialog is displayed asking you how you want to rename the files. Enter the name the first file should have, including numbers at the end of the name. Sigil will then name each of your files sequentially using the name you provided and starting at the number you provided. A file will not be renamed if a file already exists with the new name.

For example:

Chapter 1

will rename the files to: Chapter 1, Chapter 2, Chapter 3 ...

Section_0099

will rename the files to: Section_0099, Section 0100, Section_0101 ...

Part 2 - Section 08

will rename the files to: Part 2 - Section 08, Part 2 - Section 09, Part 2 - Section 10 ...

Note

When you rename a file any links pointing to the file in your EPUB will be updated.

SORT

For HTML files.

Sort the selected files alpha-numerically. This means filenames containing numbers will be sorted in their expected numerical order, e.g. “1 3 2 10” will be resorted as “1 2 3 10” instead of the default “1 10 2 3”.

MERGE

For HTML files.

If you select a single file, then the file will be merged into the previous HTML file in the list.

If you select multiple files, then all files will be merged into the first HTML file you selected.

You can also use the Merge keyboard shortcut.

LINK STYLESHEETS

For HTML files.

Link Stylesheets to the selected files. Choose the stylesheets to link from the dialog window – only stylesheets marked with a checkmark will be linked, others will be unlinked from the HTML file.

Note

When the dialog is first opened a checkmark is shown against stylesheets only if all selected files are linked to that stylesheet.

Stylesheets are applied in order.

ADD SEMANTIC INFORMATION

For HTML and Image files.

This sub-menu allows you to designate the semantic 'type' for selected files. EPUB ereaders may use this information (stored in the content.opf file) to guide them in how to present these files to readers.

For Image files, the only option is “Cover” – to indicate that this image is the cover image of the book.

For HTML files you can select from any of the following options – but each file can have only one type:

- Cover

- TitlePage

- Table Of Contents

- Index

- Glossary

- Acknowledgements

- Bibliography

- Colophon

- Copyright Page

- Dedication

- Epigraph

- Foreword

- List Of Illustrations

- List Of Tables

- Notes

- Preface

- Text

Note

Text should indicate the page of the book that should be shown when the book is first opened, but not all ereaders follow this convention.

SELECT ALL

A quick way to select all of the files in the current folder so you can rename, link, etc. all of them at once.

FONT OBFUSCATION

For Font files.

If you are using custom fonts in your ebook, then this sub-menu allows you to define how the embedded fonts are stored in the EPUB. Normally when fonts are added to the EPUB the fonts are stored in a readable form. In some cases you may not want to make the fonts available for the readers to access directly. In these cases you can obfuscate or scramble the fonts in the ebook so that readers cannot access the fonts, but the fonts will still be useable by EPUB ereaders. The details of obfuscation and its implications are beyond the scope of Sigil, but there are many references to it on the web.

The options are:

- Use Adobe’s method

- Use IDPF’s method

RENUMBER TOC ENTRIES

For the toc.ncx file.

An advanced feature that sequentially renumbers the playOrder and navPoint id numbers of the Table of Content entries in the toc.ncx file starting from 1. This feature is intended to clean up the TOC numbering if you have to manually add or delete an entry in the TOC.

Any navList or pageList items in the file are not saved – only the Table of Contents entries are saved after renumbering.

TABLE OF CONTENTS (TOC)

— A MAP OF YOUR BOOK —

EPUB supports a Table of Contents (abbreviated as TOC) to help readers navigate their way around your book. The Table of Contents window in Sigil gives you a dynamic view of your TOC – you can view exactly what your TOC looks like, select entries to jump to, and generate new versions of your TOC automatically.

VIEW THE TOC

To open the TOC window use View→Table of Contents:

Tip

Click on an entry to jump to its location in the book.

Click on the arrow icons to expand or collapse entries with subsections.

Use the right-click context menu to select Collapse All or Expand All to quickly show or hide sub-chapters.

An EPUB Table of Contents is stored in the toc.ncx file, which is listed in the Book Browser. You can edit this information manually, but Sigil provides a way to generate its contents automatically.

CREATE HEADINGS

In order to create a Table of Contents automatically you first need to define the headings or chapters in your book.

In Book View you can create the your headings by selecting the text you want to make into a heading, and then selecting the level of the heading you want from the Paragraph Format drop-down menu.

In Code View, use the standard h1, h2, etc. tags.

GENERATE TOC FROM HEADINGS

You can use the Generate TOC from headings button to select the headings you want included in the book's Table of Contents (which is stored in the toc.ncx file).

Check any name that you want to be included in the Table of Contents, and uncheck any entry that you don't want included. You can use the TOC Items Only field to show or hide entries that will not be included in the TOC.

Tip

You can also use the Select headings to include drop-down menu to quickly select or unselect headings of a certain type, and then fine tune the selections manually.

If your chapter names do not use heading tags (h1, h2, etc.) as described above, then the chapter names will not be able to be used to generate a TOC automatically.

Note

When the TOC is auto-generated, Sigil will add ID names to every chapter if they don't already have one. If you copy a chapter heading to another part of the book, you may end up with duplicate heading ID names and you will need to edit these names.

If your heading is "near" the beginning of your HTML file, Sigil will link directly to the file and not to the heading. This is because on some ereaders linking directly to an element slows down the display of the TOC.

Warning

Generating the TOC automatically will overwrite any existing TOC in the toc.ncx file.

GENERATE INLINE HTML TOC

The TOC that is stored in toc.ncx or automatically generated from Generate TOC from headings can be used by most EPUB ereaders to display the TOC. However, there are times when an inline TOC is desired in an EPUB or when it is needed because the EPUB will be converted to another ebook format that does not use the TOC file.

Tip

If you are creating an EPUB you should leave out the inline HTML TOC file unless you have a specific reason to include it. If it is needed for a specific format you are converting to then you can include it just for that conversion.

An inline TOC is just another HTML page in the EPUB that contains the TOC in text format.

The Generate Inline HTML TOC button can be used to create an HTML file called toc.html and populate it with a linked table of contents. If toc.html already exists it will be updated.

Note

If an HTML file with a semantic type of TOC already exists, then that file will be updated with the new TOC instead of the toc.html file.

Tip

You can change the style of the inline TOC once you've generated it – but remember to do this each time you create the TOC.

METADATA EDITOR

— EDIT DETAILS ABOUT YOUR BOOK —

The Metadata Editor allows you to add or edit details about your book – like Author, Title and Language, as well as hundreds of other entries defined by the EPUB standard.

All of the details about the book (called metadata) are stored in the contents.opf file in the Book Browser. You can edit this information manually, but the Metadata Editor allows you to edit it more easily.

You can open the Metadata Editor by selecting Edit→Metadata Editor or its keyboard shortcut:

REQUIRED METADATA DETAILS

The Metadata Editor shows the 3 fields required for an EPUB at the top – you must fill these in in order to create a valid EPUB:

- Title of the book

- Author of the book

- Language the book is written in

Tip

If you write a person's name as Lastname, Firstname then Sigil will automatically add it as Lastname, Firstname for filing purposes, and also add it as Firstname Lastname which is what is usually displayed to readers.

You can list several authors of a book by separating the names with a semicolon, e.g. Smith, John; Doe, Jane (they will appear in the table at the bottom of the Metadata window once you save and re-open the Metadata Editor).

OPTIONAL METADATA DETAILS

You can add optional details using the Add Basic or Add Role buttons. These will be added to the table below the required fields. The table allows you to provide the following values for each entry:

- Name: the name of the field

- Value: the contents of the field

- File As: some fields like author can or date have alternative values

- Role Type: all roles, like author, can be either a creator or contributor

The Add Basic metadata items include about 30 items such as:

- Date: Publication

- Date: Creation

- Date (custom): you can enter your own date type in the "File As" column

- Identifier: ISBN

- Identifier (custom): you can enter your own identifier type in the "File As" column

- Rights: copyright information such as Copyright 2012 An Author

The Add Role metadata contains hundreds of possible activities that people may have performed in the creation of this book such as Authors, Editor, Proofreader, etc.:

You can add the same type of field multiple times.

Tip

You can copy an entry by selecting it and clicking the Copy button. You can then modify it as needed.

You can re-arrange the order of the entries (which may affect how ereaders display the information) by selecting the entries and clicking on the Up or Down buttons.

FIND & REPLACE

— SEARCHING IN CODE VIEW —

Finding text and updating it is one of the most common tasks in Sigil – to look for words, to remove unwanted text in one file, or to change the formatting of specific items in the entire book. In fact, if you ever need to make lots of changes to your text you will almost certainly want to use Find & Replace since it allows you to quickly make a large number of edits across all your files.

Note

Most Find & Replace functions are only available in Code View. In fact, Book View only supports finding text in the current file. This chapter assumes you will use Find & Replace in Code View.

To open the Find & Replace dialog, use the menu option Search→Find/Replace: or the keyboard shortcut Ctrl+F:

Tip

Keyboard shortcuts exist for many find and replace operations – such as Ctrl+G to find again. See the Search menu for a list of shortcuts.

You can set various modes (Normal, Case-Sensitive, search some or all HTML files, search down, etc.) to modify the behavior of the actions you select (count, find, replace, etc.).

When open, the Find & Replace dialog is always positioned at the bottom of the editing windows for easy access.

ACTIONS

The four buttons on the right are used to run your search commands.

Tip

After you run a find, replace or count, the text you entered in either the Find or Replace box is saved and is available for you to select later. Click the down-arrow to the right of the Find (or Replace) text box to show the list of items in the search histories.

Whenever you run a search, the results are shown in the Find & Replace status bar.

FIND

Finds the next occurrence of your search term and highlights it.

To search for text, enter it in in the Find text box and press the Find button. Any text in the Replace box is ignored if you are just doing a Find.

Tip

If you select text and then use Ctrl+F to open or re-open the Find box, your selected text will be placed in the Find box.

COUNT ALL

Displays a count of the number of times the search term you entered in the Find text box occurs in the selected files.

Count All always counts from the start of a file.

Tip

Its a good idea to run Count All before doing a Replace to check the number of replacements are what you expect. And you should run it after a Replace All in case the particular search and replace created new matches.

REPLACE

Replaces one occurrence of your search term in your text at a time.

To replace text, enter the old text in the Find box, and the new text in the Replace box. Then select Replace.

The first time you do a Replace the first match will be highlighted. Subsequent Replaces will replace the highlighted matched text and then highlight the next match.

Tip

You can use the Undo icon or right-click in the editing window and select Undo to change the text back. But if you are replacing across files and your next match is on a different page, you need to switch back to the file containing the replaced text before selecting undo.

You can safely use Replace instead of Find if no text is selected since it will act just like Find until a match is highlighted.

REPLACE ALL

Replaces all text matching your search term with your replace term in all the selected files. This is done all at once automatically.

Note

You cannot undo a Replace All.

Replace All always replaces from the start of a file.

Tip

Test your find and replace strings using Replace a few times before using Replace All to avoid surprises.

Save your book before a Replace All and check it after the replace in case of issues.

Check if your mode is set for Current File or All HTML Files.

MODE – WHAT TO SEARCH

You can control what type of text to search for using these options.

NORMAL

This mode will search for exactly what you type except that it will ignore case, e.g. “A” and “a” will be considered the same letter.

CASE SENSITIVE

This mode will search for exactly what you type.

REGEX

Regex is an abbreviation of “Regular Expression”. This mode allows you to search for patterns instead of exact words or characters.

For instance, you can search for “Page [0-9]+” which will find "Page" followed by one or more numbers.

Regex is very powerful and one of the main benefits of using Sigil to work with ebooks.

See the Regular Expressions chapter for more details about using regex.

SPELL CHECK

In Spell Check mode, Find can be used to find the next misspelled word.

Tip

In Code View you can set your preferences to show misspelled words with a wavy red underline, but this means you have to scroll through the document to find each misspelled word. Using Spell Check mode in Find & Replace allows you to find misspelled words one by one.

To use Spell Check mode, make sure the Find text box is empty, then click Find to find the next misspelled word.

You can then edit the word in the text or use replace. If automatic spell checking is on you can also right-click the misspelled word to select an alternative.

Tip

You can use Count All to easily count the number of misspelled words.

You can also use a regex expression in the Find box if you need to find specific misspelled words or patterns.

Note

See the Spell Check chapter for more information about spell checking.

MODE – WHERE TO SEARCH

You can control which files to search with these options making it easy to search all or just some of your files.

CURRENT FILE

This restricts your search to just the file you are viewing. You can search HTML files and Style files.

If your search reaches the end of the file it will automatically wrap around and search from the other end of the file. You will see a small picture of an arrow flash on the screen to indicate the search wrapped around.

ALL HTML FILES

This searches in every HTML file.

When a search reaches the end or beginning of the book it will automatically move to the next or previous file (in the order listed in the book browser), and it will loop around when all files have been searched.

SELECTED HTML FILES

This searches only the HTML files that you selected in the Book Browser.

When a search reaches the end of a file it will automatically move to the next or previous selected file (in the order listed in the book browser), and it will loop around when all files have been searched.

MODE – SEARCH DIRECTION

You can control the direction of searching with these options.

UP

Searches from your position in the document upwards – finds the previous occurrence of your search.

DOWN

Searches from your position in the document downwards – finds the next occurrence of your search.

IMAGES

— INSERTING PICTURES INTO YOUR BOOK —

You can insert images and pictures into your book – but first you must add them to your EPUB and then tell Sigil where they should be used in the ebook.

ADDING IMAGES TO YOUR EPUB

To add images to your book, use File→New→Add Existing Files, or right click in the Book Browser and select Add Existing Files from the context menu. This will display a dialog allowing you to select one or more files from your computer. Select as many images as you want.

The images will be added to the Images folder in the Book Browser. However, they are not yet actually used anywhere in your book – they are just available to use.

Tip

To view an image's details double click on it in the Book Browser. The Width and Height in pixels, size of the file in kilobytes, and whether or not the image has any color defined are shown:

Note

If you delete and re-add an image you will need to save and re-open Sigil to display the new image.

INSERTING IMAGES INTO YOUR BOOK

Once the images are in your EPUB, you can insert them anywhere in your files.

Click on the location in your file where you want the image to be located (in either Book View or Code View) and then use Edit→Insert Image or the Insert Image icon in the main toolbar.

Select the image you want to insert.

Tip

You can insert the same image into your text as many times as you want.

In Book View you can double click on an image or right click and select Image Properties to see information on the image link.

COVER IMAGES

Images for covers are special in that you must tell the EPUB which image should be used for the cover. Different ereaders use different methods to identify the cover, so you should use both methods:

- Create a cover.html file at the start of your book and then insert your image into it.

- Mark the cover.html file as a cover file by right clicking on it in the Book Browser Text folder, selecting Add Semantics and choosing Cover.

- Mark your actual cover image file as a Cover by right clicking on it's file in the Book Browser Images folder, selecting Add Semantics and choosing Cover.

Note

Please make sure you have permission to use any images in your book as most images are copyright and their use may require a license.

SPLITTING AND MERGING

— WORKING WITH CHAPTERS AND FILES —

An EPUB can consist of one large HTML file with all of your text, or multiple files each containing part of your book. In most EPUBs each main Chapter is stored in its own HTML file in the EPUB. This isn't required, but it makes it easier to work with the book and can make reading and editing quicker since the files are smaller. All of your files can be accessed using the Book Browser.

If you have loaded one HTML file into Sigil and want to divide it into separate files, then you can use Sigil's Split functions. And if you have several smaller files that you want to combine into a larger file, then you can use the Merge functions.

Tip

Most ereaders start each new HTML file on a new page – giving you automatic page breaks between chapters if you split your Chapters into separate files.

SPLITTING FILES

You can split a file into multiple files in a couple of ways.

SPLIT IMMEDIATELY

The easiest way to separate a file into two files is with the Edit→Split Chapter menu item, or the Split Chapter icon:

To use Split Chapter, click at the end of paragraph where you want to do the split:

Then use Edit→Split Chapter:

Everything from the beginning of the original file up to and including the paragraph where you clicked is put into one file, and everything after the paragraph you clicked on was put into a second file.  Note that the first file kept its name, and a new file with a new name was created to hold the second file. You can rename and edit the files as necessary.

Tip

The split is done at the end of the paragraph you clicked in.

MARK AND THEN SPLIT

If you want to split a very large file into many chapters, then it is probably easier to use the chapter marking approach.

Scroll through your file, and wherever you want a new chapter to start click the beginning of the chapter name or the end of the previous paragraph. Then use Edit→Insert Chapter Marker. This will insert code into your document telling Sigil you want a new chapter to begin here – you will see a horizontal line in Book View exactly where you inserted the marker:

When you have marked all your chapters, use Edit→Split at Chapter Markers. This will automatically split your file into as many chapters as you marked. If you decide not to split the file, you can delete the horizontal marker lines.

Once you have split your files you rename them. And you can even Merge some or all of them together again.

Tip

If you split a file, any header information is copied to the new file.

MERGING FILES

If you need to combine two or more files into one file, you can use Merge.

In the Book Browser select the files you want to merge, then right click and select Merge from the context menu (or use the keyboard shortcut).

Your files will be combined into the first file.

Tip

If you only have one file selected and use Merge, then the selected file will be merged with the previous file in the Book Browser.

SPELL CHECK

— CHECKING AND CORRECTING SPELLING —

Sigil provides several ways to spell check your book. You can choose the main dictionary to use, and create personal dictionaries with your own words.

Note

Spell Check is only available in Code View.

CONFIGURING SPELL CHECKING

You can set the spell checking preferences that you want – including whether or not to use automatic spell checking, which main dictionary to use, and which custom dictionary to use if any. See Spell Checking under Edit→Preferences to change the available options.

Tip

Since you can use multiple user dictionaries, you can setup user dictionaries for different types of books or individual books. Then you can change user dictionaries as necessary.

AUTOMATIC SPELL CHECKING

Code View will highlight any misspelled words with a wavy red underline when automatic spell checking is enabled in Preferences:

You can then right-click on the misspelled word to bring up a list of choices:

- Suggested Words: a list of alternative words to choose from – selecting one will replace the misspelled word

- Add to Dictionary: add this word to your current user dictionary

- Ignore: ignores the spelling of this word in the entire document until you restart Sigil

FINDING MISSPELLED WORDS

You can also search for misspelled words one at a time in order to make finding them easier.

In Code View, open the Find & Replace window and change the mode to Spell Check and clear any text in the Find box:

To search for misspelled words:

- Click on Count All to display the number of misspelled words in your selected files.

- Click on Find to highlight the next misspelled word. You can then right-click on it as above to change it or add it to the dictionary.

You can also enter a Regex search pattern in the Find box to find misspelled words that match the pattern you entered in the Find box.

VALIDATE AND CLEAN

— MAKING SURE YOUR EPUB IS VALID —

VALIDATE

In order to be considered a valid EPUB, your ebook must meet the standards defined for EPUBs. This means it must include certain files and must contain certain information. To help ensure your EPUB meets these standards, Sigil includes the EPUB validation program FlightCrew.

You can create a report showing any issues in your EPUB by using the menu option File→Validate EPUB:

Once you have run Validate to produce a report, look at each of the issues listed and then edit your document to correct them.

Tip

You can double click on most entries to be taken to the relevant part of the book.

You should validate your document each time you correct it to verify there are no more errors.

Common issues include:

- This resource is present in the OPF <manifest>, but it's not reachable (it's unused).

- This warning means you have included the listed file in your EPUB, but you have not used it anywhere in your book. If you intended to use it, you should link to it, otherwise you can delete the file.

- This OPS document is reachable but not present in the OPF <manifest or spine>. "Reachable" means that a reference of some kind that points to this resource exists in the epub.

- This error means you have a reference or a link to a file or image in your EPUB, but that file is not included in the EPUB. You need to add the file to the EPUB or correct the name of the file used in your text. You can usually find these by searching for the filename listed in all the HTML files. You may also have to re-generate or update your TOC.

- ID value 'SOMEIDNAME' is not unique

- This error means you have an ID named SOMEIDNAME in your EPUB that is defined more than once. Typically these are in headers or footnotes and can be caused by copying and pasting or merging. You can find these by searching all HTML files for the ID name that is listed and changing them so all IDs are different from all other IDs. If the issue is in a heading and you have auto-generated your headings, you can delete the ID and they will be re-generated the next time you create your TOC.

- attribute 'INVALIDATTRIBUTE' is not declared for element 'SOMEELEMENT'

- This error means you have an HTML tag named SOMEELEMENT that contains an attribute INVALIDATTRIBUTE, but INVALIDATTRIBUTE is not valid for that tag. For instance <h2 invalidattribute="test">. This can be caused by typos or by old versions of HTML. You need to search for INVALIDATTRIBUTE in all HTML files and remove, correct, or replace each occurrence.

- no declaration found for element 'INVALIDELEMENT'

- This error means you have an HTML tag named INVALIDELEMENT that has not been defined. Typically this is simply because it is invalid and is old HTML syntax that need updating. You need to search for INVALIDELEMENT in all HTML files and remove, correct, or replace these with valid HTML.

- element 'INVALIDELEMENT' is not allowed for content model '(p|d|h2|h3|h4|h5|h6|div|ul|ol|...'

- This error means you have an HTML tag named INVALIDELEMENT that is not valid HTML for an EPUB. Typically this is old HTML syntax that needs updating (such as the <center> tag which should be implemented using a style). You need to search for INVALIDELEMENT in all HTML files and remove, correct, or replace each occurrence with valid HTML.

- value 'SOMENAME' is invalid NCName

- This error means you have an ID name that is invalid. It probably contains a space or other invalid character. You need to search for SOMENAME and change it.

Tip

You can also use online EPUB validation programs, in particular:

- IDPF EPUB Validator [http://validator.idpf.org/]

AUTOMATIC CODE CLEANING

Sigil can automatically clean your HTML code when you save by using the included HTML Tidy software. This does not correct any errors but attempts to normalize your code by adjusting spacing or consolidating styles.

The Edit→Clean Source menu option allows you to set several levels of automatic cleaning:

- Off: HTML Tidy will not be used. No automatic cleaning of code will be done – your code will be left formatted exactly the way you typed it.

- Pretty Print: HTML Tidy will be used to remove any unnecessary spaces or blank lines in your code and will indent HTML tags to make it easier to read the code. No code will be changed – only spacing.

- Tidy: HTML Tidy will be used to clean your code – this will include pretty printing plus converting some of your tags into styles and some of your styles into an internal stylesheet. It is possible under rare circumstances that Tidy will clean too much and delete text, so you may want to carefully consider using this option.

When using Tidy, it will often convert tags or style attributes you have applied into a style tag and create a class name for the style (see the Stylesheets chapter for more information). If this has happened you will see the new stylesheet at the top of your file, e.g.

<style type="text/css">

/*<![CDATA[*/

p.sgc-1 {font-weight: bold}

/*]]>*/

</style>

This is a perfectly valid stylesheet (the sgc stands for Sigil class), although if you prefer to keep your tags exactly as typed, or use external stylesheets to manage your styles as most people do, you may want to set Clean Source to the Pretty Print option to prevent the conversion of styles to internal stylesheets.

Tip

Tidy is only run when you save your book, so save often to see the changes Tidy makes as you edit.

PREFERENCES

— CUSTOMIZE SETTINGS —

The Preferences dialog gives you control over a number of settings in Sigil like Languages and Dictionaries.

Select the menu item Edit→Preferences to open the Preferences dialog.

Choose the area you want to modify by clicking on the entry on the left. See below for details on what can be changed.

Select the Close button to save the current settings and close the window.

KEYBOARD SHORTCUTS

You can view all the keyboard shortcuts assigned to functions in Sigil – and change them to what you prefer. So if you want F2 to always open Find & Replace then you can change it here.

Use the Filter text box to easily find keys or descriptions that contain letters you type.

Use Reset to change the shortcut back to its default, or Clear to remove any shortcut for the function

LANGUAGE

You can set the language of Sigil's interface and the default language of your book:

USER INTERFACE LANGUAGE

Sigil's user interface has been translated into many languages. You can select from the available languages using this option. If a translation is not available for specific words then they will be shown in English.

Note

You must restart Sigil in order for the new user interface language to be used.

Try setting the interface to another language and restarting Sigil to see the translations volunteers have created. You can easily change back to your preferred language.

DEFAULT LANGUAGE FOR METADATA

This option sets the default language that will be selected in the Metadata Editor for new books or books that do not already have a language set.

SPELL CHECK

Sigil supports spell checking in Code View, and allows you to choose from standard or personal dictionaries:

ENABLE AUTOMATIC SPELL CHECKING

When Enable automatic spell checking is checked, Code View will underline misspelled words.

Tip

Even with automatic spell checking off you can still use Find & Replace in Spell Check mode to search for misspelled words.

STANDARD DICTIONARIES

Sigil includes several dictionaries as standard: US English, British English, French, German, Spanish. You can select one using the Dictionary drop-down menu.

If you want to see where the standard dictionaries are stored, or to add new standard dictionaries (which must be in the hunspell format) then you can click on the "Open Dictionary Directory" button.

Note

To add another standard dictionary, such as ones found at the OpenOffice Dictionaries [http://wiki.services.openoffice.org/wiki/Dictionaries] site, download, extract, and copy the files, e.g. en_GB.aff, en_GB.dic, hyph_en_GB.dic to the standard directory location and restart Sigil.

USER DICTIONARIES

You can also create your own personal dictionaries, and even use different ones for different books.

To create a personal dictionary, select Add under User Dictionary on the left and then enter a name for your new word list:

You can choose which User Dictionary is in use, and you will see the words for that dictionary on the right. You can also rename or remove the dictionary.

On the right side you can add/edit/remove words in the selected Dictionary.

Tip

Whenever you use Add to Dictionary in Code View, your selected word will be added to the currently selected User Dictionary.

TUTORIALS

— STEP-BY-STEP GUIDES —

These tutorials show you how to use Sigil for several common tasks, including how to create an EPUB from another document, how to edit an EPUB, how to use stylesheets and how to use custom fonts in an EPUB.

Details and tips on all of Sigil's features can be found in the Features chapter.

If you haven't read the introduction of the User Guide yet, then you should to get an overview of EPUB. One important point to be aware of is that an EPUB is just a collection of files including HTML documents, images, and styles all zipped up into a single file. Sigil allows you to work with all those files and package them as an EPUB.

CREATE AN EPUB

— CONVERT AN HTML FILE TO EPUB —

This tutorial shows you how to create an EPUB ebook from a document or file.

Creating an EPUB consists of loading your document or entering text, and then adding information about the book, a cover and a table of contents, and then checking your EPUB for errors. The steps in the tutorial will walk you through many of the features of Sigil.

If you already have an HTML or EPUB file you can skip the conversion step and open your file directly in Sigil. If you are going to write in Sigil, then you can skip the conversion and opening file steps.

CONVERT YOUR FILES TO HTML

If you are starting with a document created by one of the many available word processor programs, the first thing you need to do is convert your document to HTML so that you can import it into Sigil.

Note

Sigil only supports importing HTML files since converting from other formats is actually quite specialized and best left to other tools.

Although conversion is not part of Sigil, here are some suggestions for converting files to HTML:

- Microsoft Word file: use the MS Word menu option File→Save As Filtered HTML. Or use the MS Word Macro @ MobileRead [http://www.mobileread.com/forums/showthread.php?t=142530]. Both approaches try to reduce the amount of extra code used by MS Word so that your HTML file is cleaner and simpler to edit in Sigil.

- Text file: try renaming the file to end in .html, or load into into MS Word, OpenOffice or LibreOffice and save as HTML. Text files usually don't convert well due to difficulty in identify the start and end of paragraphs.

- RTF file: try the rtf2epub tool at http://code.google.com/p/epub-tools/downloads/list.

- PDF file: use Adobe Acrobat File→Save as HTML menu option, or use http://pdftohtml.sourceforge.net/. PDF files usually don't convert well since they were built for a fixed layout.

Tip

You can also use calibre [http://calibre-ebook.com/] to convert many different formats to HTML, and can convert EPUB files to many other formats. Although it can convert files to EPUB, its best to use an HTML source file if you have one.

START SIGIL

When you first start Sigil you will be shown a screen with several windows. The Book Browser window is on the left (which is used to access all the files in your EPUB), an editor Window is in the center and set to Book View (to edit your book as it appears), and a Table of Contents window is on the right (to show you any chapter titles you've defined).

Tip

See the User Interface chapter for more details.

OPEN YOUR FILE

A blank EPUB book is loaded when Sigil is first opened, but since you already have an existing file you can just load your file.

To open your EPUB or HTML file, use the menu option File→Open:

Select the file you want to open from your file manager.

You will now see your file in the Book Browser window under the Text folder on the left, and the file will be opened in the Book View editor in the middle with its filename showing on the tab header:

Your HTML file is now part of the EPUB ebook. From now on you you are editing your EPUB and not just an HTML file.

Note

When converting your file to EPUB or loading an EPUB Sigil may add some necessary details and re-organize your files into standard folder names.

SAVE YOUR EPUB

Now that you've loaded your file, you should save your new EPUB. You should do this right after loading your file to make sure there are no problems.

To save your EPUB, use the menu option File→Save As:

Enter a name for you file in your file manager. It will be given a .epub extension since it will be saved as an EPUB file.

Note

You can now use File→Save to save your EPUB at any time – and you should save often.

To make sure your ebook conforms to EPUB standards, you need to add a bit more information.

EDIT YOUR BOOK

If you need to make any basic changes to your text, you can just edit your book in the Book View editor.

You can then follow the remaining steps to create a complete EPUB ebook. You can always make more changes once you've created your EPUB – read through the User Guide for more details on editing, working with files, images and formatting.

ADD DETAILS ABOUT YOUR BOOK

In addition to the actual content of your book, EPUB files also contain information that is useful for your readers such as book details like Title and Author.

To add details about your book (called metadata) to your EPUB, use the menu option Edit→Metadata Editor:

The Metadata Editor window will be displayed:

You now have to add the Title, Author, and Language to your book in order to have a valid EPUB:

- Title: the full title of your book

- Author: for example enter Carroll, Lewis

- Language: the language the book was written in

Once you've updated the information, you can select OK and then save your EPUB again.

Tip

You may have noticed that there is a lot of room for other values in the Metadata Editor. Only the Title, Author, and Language are required for EPUBs, but if you want to add more values using the Add Basic or Add Role buttons you can.

See the Metadata Editor chapter for more details.

ADD A COVER IMAGE

Every book should have a cover image, and Sigil can help you add one to your EPUB. You'll need to have an existing cover image available to use (and have permission to use it).

In order to define an EPUB cover you will need to import the image into your EPUB, create a file to hold your cover, and mark the image and file as covers as described below.

ADD YOUR COVER IMAGE TO YOUR EPUB

To select the image you want as your cover, use File→New→Add Existing Files:

Select your cover image from your file manager.

Your EPUB now contains your cover image:

Tip

You can double click your image file to display it in the main window.

However, there are still a few steps needed to identify it as a cover.

CREATE AN HTML FILE WITH YOUR COVER

You need to create an HTML file and insert your cover image into the file.

Create a new HTML file in your EPUB by right clicking on a file name in the Book Browser and selecting the menu option Add Blank Section:

A new HTML file will be created in your Text folder:

Rename the file so you know what it is by right-clicking on the filename and selecting Rename from the menu:

Enter cover.xhtml as the new name (you can just type cover – the extension will not change by default):

Move the file to the top of the Text folder since a cover should be the first file of a book. You can drag-and-drop the file to its new position (click on the filename and hold the mouse down while you move it to its new position):

Now that we have an HTML file, we need to put your cover image into it.

Double-click on the cover.xhtml file to open it in the Book View editor window (you will see cover.xhtml as the title of the open tab in the editor window), click somewhere in the blank window to start editing.

Use Edit→Insert Image to select your image from the Images folder, or use the Insert Image icon on the toolbar:

This will display the Insert Images window:

Select your image from the list of images in your EPUB.

Your cover image will now appear in the file:

MARK YOUR COVER FILES AS A COVER

Now that you have both a cover image and an HTML file with a cover in it, you need to mark both as Covers to make sure the various ereaders can recognize the cover:

To mark the HTML file as a cover right-click on cover.xhtml in the Book Browser window, select the menu item Add Semantics, then choose the Cover entry:

And to mark the image as a cover image right-click on the cover image in the Book Browser window, select the menu item Add Semantics, then choose the Cover entry. You must set both the image and the HTML file to type Cover to make sure all ereaders recognize the cover.

Your EPUB now has a cover defined (if you look at the Add Semantics menu again for the files you will see the Cover items now have a checkmark next to them).

You should save your book if you haven't already.

Tip

See the Images chapter for more details.

CREATE A TABLE OF CONTENTS (TOC)

EPUBs support an interactive Table of Contents (abbreviated as TOC) to help readers find their way around your ebook. In an EPUB, the TOC is stored in a separate file in your book and readers can usually open it with a menu entry or button on their ereader at any time. You don't have to directly edit the TOC file since Sigil provides a way to generate it automatically from your ebook.

Sigil will display the current TOC in a separate window. If you haven't defined any text as a chapter heading, then the Table of Contents window will be blank – except for the Start placeholder text and two buttons for generating a new Table of Contents:

MARK YOUR CHAPTER HEADINGS

In order to tell Sigil what your chapter headings are you need to highlight the text in your files (e.g. Chapter 1) and then click on the Paragraph Format icon (which will probably list Normal on the button if you have selected some standard text) at the top of the Book View window:

Select Heading 1 for a top level heading. This will mark the the text as a heading at level 1 – you can see that the format of the text and the dropdown menu has changed:

Tip

When you click on a heading in your text the Paragraph Format menu will change to show the heading level.

You should now mark all the chapter headings in your document in the same way.

GENERATE THE TOC

Once you have marked all your chapter headings you can click the Generate TOC from headings button on the Table of Contents window:

This will open the Heading Selector dialog:

The dialog allows you to mark which headings to include or not include in your Table of Contents. Click OK when you are finished.

The Table of Contents window has now been updated to show your current TOC – which includes the headings you selected:

You should save your book if you haven't already.

Note

You can also use Sigil to create create an inline TOC page using the Generate Inline HTML TOC button. This is not required or usually used in EPUBs, but if you convert to other formats or want a fancy TOC then its available.

Tip

See the Table of Contents chapter for more details.

SEPARATE YOUR BOOK INTO FILES

This is an optional step – you can skip this if you don't want separate files for your chapters.

If you loaded an HTML file into Sigil, this usually means all of your text and chapters are in one large file. This is okay, but the standard practice with EPUBs is to put each chapter in your book into a separate HTML file. This makes it much easier to edit.

Tip

Since most ereaders start a new file in the EPUB on a new page, it means your chapters will also start on a new page.

The easiest way to split your book into one chapter per file is to do a bulk update by marking all the locations of your chapters and then have Sigil split at those points.

You should save your book now, in case you want to undo any changes.

ADD SPLIT MARKERS TO YOUR FILE

For each chapter heading in your book, click just to the left of the chapter heading so that your cursor is at the start of the line:

Now select Edit→Insert Chapter Marker to insert a marker in your text:

The marker will appear as a horizontal line:

Do this for every chapter in your book.

SPLIT YOUR BOOK

Once you have inserted all your Chapter Markers into your file, you need to run Edit→Split at Chapter Markers:

Your book will now be split into separate files as shown in the Book Browser:

You can rename the chapters, and you should save your book once you have made your changes.

Tip

See the Splitting and Merging chapter for more details.

CHECK YOUR BOOK

Your book is almost ready. You just need to check your EPUB to see if there are any issues that might cause problems for ereaders. This can range from missing or extra files, or broken links, etc. This may be unlikely for your first file, but its good practice to do the checks to make sure your EPUB is standard.

To check or validate your book, use File→Validate. This will open a window just below your document and list any problems that were found. For instance, if you forgot to enter the Title of the book in the Metadata Editor you might see:

It can be difficult to interpret exactly what the issues are sometimes, but you should read through them to see if there is anything that you recognize and can fix.

Once you've fixed all the errors Validate will confirm everything is okay:

Tip

See the Validate and Clean chapter for more details.

SAVE YOUR BOOK

All you need to do now is save your EPUB and you're done. Congratulations!

EDIT AN EPUB

— USING CODE VIEW AND FIND & REPLACE —

This tutorial shows you how to get started with advanced editing of an EPUB in Sigil.

BASIC EDITING

If all you want to do is make a few simple changes in your book, then you can just open each of the files (by double-clicking on them in the Book Browser) and make the corrections in Book View. Then save your EPUB.

But if you want to do more significant changes then you need to learn about Code View and Find & Replace.

INTRODUCING CODE VIEW

Up to now you have probably only been viewing your text exactly as ereaders would display your book – using the WYSIWYG Book View mode in Sigil.

However, your text is not actually stored in an EPUB looking like it does in Book View. In fact, it is stored in HTML format – which is a mix of your text and HTML tags that tell ereaders how to interpret and display your book.

You can see the HTML code in your files by using Code View.

So why do you need to know all this? Because in order to bulk edit text or to control the formatting of your book easily, you need to use Code View. And as its name implies, Code View shows you the raw HTML code that makes up your book.

CODE VIEW

To switch to Code View, use View→Code View. You can switch back to Book View at any time by using View→Book View. Or you can use the Book View and Code View icons on the toolbar.

This is what Code View looks like:

That's quite a lot of text, but its not as jumbled as it appears. First, ignore everything at the top of the file up to and including the line <body> as it is just information required by HTML files and usually the same in every file.

Your text starts after the <body> tag – you can see the chapter name and several paragraphs of text, along with other odd looking codes explained below.

HTML BASICS

A full description of HTML is beyond this tutorial, but understanding the basics will help you edit your text.

If you look at the HTML version of your file in Code View you will see lots of words like <p> or <h1>, etc. These are the HTML tags that tell ereaders what to do with your text.

For instance, the HTML code below tells the ereader that the text Chapter 8 is a level 1 Heading:

<h1>Chapter 8</h1>

The <h1> tag is the start of the text to be treated like a heading, and the </h1> tag indicates the end of the text included in the heading. Depending upon some other settings, ereaders will typically make the text of a heading larger and center it on the screen.

And the HTML code below tells the ereader that the text This is a paragraph is an ordinary paragraph. Since its a paragraph the ereader will apply a certain formatting, perhaps indenting the first line.

<p>This is a paragraph.</p>

Tags can get more fancy since they can include attributes that modify how they are interpreted. For example, the following paragraph tag (p) has an attribute called style with a value of font-weight: bold:

<p style="font-weight: bold">A bold paragraph</p>

The code tells ereaders that for this particular paragraph, the style of the text should be bold.

These are just a few examples of HTML code, but they give you an idea of what the majority of HTML is all about.

What is important to remember is that in Code View you have access to both your text and the formatting codes that control the look of your book – so you can find and change them. Sigil provides a way to easily edit your text and HTML tags.

Tip

See the Introduction, Code View and Stylesheets chapters for more details.

EDITING IN CODE VIEW

Once you are in Code View you can edit your text just like in Book View. Try changing some of your words (but not the HTML tags just yet), and then switch back to Book View. You will see the updates you made. In fact, any changes you make in Book View or Code View will be visible in the other view as they both only change one copy of your file.

Note

Unlike Book View, where you can make whatever changes you want without breaking your EPUB, when you are in Code View it is essential that you edit carefully. You will need to make sure all the tags you use are valid and are opened and closed properly – if they aren't, you will get a warning when you try to save and you will be unable to save your EPUB until they are fixed.

Tip

Save often to have your code checked for any errors to catch them early.

INTRODUCING FIND & REPLACE

In Sigil, Find & Replace can be used to find any text in any of your files. And even more important, it can be used to change text – but only in Code View.

To open the Find & Replace, use Search→Find / Replace. The window will remain open and below the editing window until you close it.

This is the Find & Replace window in Book View:

As you can see, in Book View you only have the option to Find text.

You need to switch to Code View to see the full set of options available in Find & Replace.

FIND & REPLACE IN CODE VIEW

In Code View, to open Find & Replace use Search→Find / Replace or the Ctrl+F keyboard shortcut:

Tip

The Find and Replace text boxes are where you enter what to look for and change. The four buttons on the right (Find, Count All, Replace, Replace All) are used to run your search. The Mode dropdown boxes on the bottom allow you to change what to search for, where to search, and which direction to search in.

Each dropdown and button has a tooltip with more details.

To make a simple change enter some text to search for in the Find box, and what to replace it with in the Replace box, then click Replace:

Or click on Count All to show how many matches there are:

To test Find, enter a search string and click Find a few times (any text in the Replace box is ignored if you are just doing a Find or Count All). Your matched text will be highlighted in the Code View window.

Now click on Replace.

Since your matched text was already highlighted, Sigil has replaced it with your new text (which could be empty if you wanted to delete that text in your document) and then automatically found and highlighted the next match. If matching text wasn't highlighted already, then Replace would have just found and highlighted the next match without replacing it.

You can scroll back to verify your text was replaced.

If you are satisfied that the Replace is working okay, you can use Replace All to update all the matching text in your document at once instead of one at a time.

Tip

Always use Count All and possibly a few Replace commands before using Replace All – to make sure you have entered your find and replace strings correctly.

You may have noticed the selection box containing Current HTML File. If you change Current HTML File to All HTML Files, your Find or Replace will be done across every HTML file in your EPUB:

This is why editing in Sigil can be done quickly.

ADVANCED FIND & REPLACE – REGEX

The real power of Find & Replace in Sigil is provided by its support of Regular Expressions (also called regex).

You use regex in Find & Replace by changing the mode of the search from Normal to Regex.

Regex is a very important tool in Sigil, but only a very brief introduction can be given in this tutorial.

For example, instead of searching for very specific text to replace or delete, such as "Page 123", it would be much more useful to search for text that contains "Page" followed by a number – that's exactly what regular expressions can provide.

Instead of putting your actual text into the Find or Replace boxes, you can substitute it with special regex codes. So in the example above you could search for "Page \d+" instead of "Page 123" because "\d+" is a regex code that means any digit repeated at least once.

USING REGEX TO REPLACE TEXT

But even more useful is that you can use regex to help with replacing text as well. In the example above, you might want to keep the page numbers but replace the word "Page". You could use then use something like:

- Find:

Page (\d+)

- Replace:

This is page number \1

This will replace any occurrence of "Page" followed by a number with "This is a page" followed by the same number:

- Before:

Page 418

- After:

This is page number 418

The first point to note about this replacement is the use of the regex code (\d+) in the Find box. The \d+ code tells the search to look for numbers as above. But the use of parenthesis around the code tells the search to remember what those numbers were. The other point to note is the use of the regex code \1 in the Replace box which tells Replace to substitute the characters remembered in the Find statement for the string \1 wherever it finds it.

USING REGEX TO CHANGE FORMATTING

As a further example of regex, this is how you might change the formatting of certain text into chapter headings.

Let's say that you have an imported HTML file that contains lots of chapter headings, but none of them are marked using the h1 heading tag. Instead they are all marked as paragraphs like this:

<p>CHAPTER 7</p>

Assuming every paragraph like this is a chapter heading, you could use this regex:

- Find:

<p>\sCHAPTER\s(\d+)\s</p>

- Replace:

<h1>Chapter \1<h1>

That's quite a lot to digest, but if you look carefully you can see that its very similar to the Page number example above in that its remembering the digits in the chapter name and using them in the replace.

Its the Find that is the most interesting. It breaks down like this:

- <p> – look for a starting paragraph tag

- \s – regex code to match any white space (blanks, new lines, etc.)

- CHAPTER – match the word CHAPTER (Regex is case-sensitive by default)

- \s – regex code to match any white space (blanks, new lines, etc.)

- (\d+) – regex code to match any number of digits in a row and remember them

- \s – regex code to match any white space (blanks, new lines, etc.)

- <p> – look for an end paragraph tag

You could just use a space instead of \s but \s is more flexible since it will match any number of blank spaces and tabs and even across new lines (regex only searches one line by default).

So the results of that search could be:

- Before:

<p>  CHAPTER    14

</p>

- After:

<h1>Chapter 14<h1>

Note

It becomes more difficult to use regex if the formatting used in a file is not consistent – in these cases you may have to do several Find & Replace passes and even resort to making the updates one by one manually.

This is only a very basic description of what regex is, but it gives you an idea of what is possible. The trick with regex is getting the right find and replace strings, and that only comes from reading, asking questions, and experience.

See the Regular Expressions chapter for more details.

USE REGULAR EXPRESSIONS

— REGEX REFERENCE —

This tutorial is basically a quick reference for Regex. You should read Edit an EPUB first as an introduction to Regular Expressions.

Regex is a very powerful way for you to edit and cleanup your EPUB when using Find & Replace. However, when you first start using regex it can be confusing because there are a lot of commands you can use. This is a brief summary of some basic regex commands.

You can find more details about regex at these links (or ask for help in the Sigil forum):

- Regex overview at MobileRead [http://www.mobileread.com/forums/showthread.php?t=118569]

- A one page command summary [http://www.cheatography.com/davechild/cheat-sheets/regular-expressions/]

- Regex as used by Python [http://docs.python.org/library/re.html]

- Official PCRE details – start at the PCRESYNTAX(3) section [http://www.pcre.org/pcre.txt]

OVERVIEW

When using regex commands in Find & Replace the purpose is to allow you to search for patterns instead of exact text. This means that you can tell Find & Replace to search for "a number" instead of "8", or to match any words between certain tags and then replace it with new tags or new words.

In order to allow you to search for patterns, you need to use regex commands in place of the specific text you want in your search. For instance, instead of searching for 8 you could search for \d (which means one digit) or \d+ (which means one or more digits).

An example Find & Replace command using regex might be to change all level 1 headings to level 2 headings:

- Find: <h1(.*?)</h1>

- Replace: <h2\1</h2>

where the Find command searches for any text between the h1 start and end tags, and using () to save the text. (The start tag is left open in order to catch any class definitions, and the ? tells .* to do minimal matching). The Replace command is used to replace the matched text with the saved text (indicated by \1) surrounded by the h2 start and end tags.

The following sections give a sample of common regex commands that you may find useful.

GENERAL MODIFIERS:

You can put these commands at the start of any regex to modify how the expression behaves:

- (?s) – search across lines when using .* since by default .* only matches within a line of text.

- (?U) – match the first occurrence of your string (also called minimal or ungreedy matching). This is very useful when using .* to avoid matching too much.

- (?i) – ignore case when matching.

You can combine modifiers, e.g. (?sU) is commonly used.

SINGLE CHARACTERS:

You can use these regex commands to represent single characters:

- . – matches one character

- \d – match one digit

- \t – match one tab

- [abc] – any character that is a b or c

- [^abc] – any character that is NOT a b or c

- [0-9] – any digit from 0 to 9

- [:alpha:] – any letter, upper or lower case

- [^:alnum:] – any character that is NOT a digit or upper or lowercase letter

MULTIPLE CHARACTERS:

These regex quantifiers or codes allow you to represent multiple characters:

- * – use after a character to mean 0 or more, e.g. .* means 0 or more of any character

- + – use after a character to mean 1 or more, e.g. \d+ means 1 or more digits

- ? – use after a character to mean 0 or 1 instance, e.g. \d? means none or 1 digit

- \s – matches whitespace, including space, tab, end of line carriage returns or newlines

And there is a special character that tells your search to stop at the first match it finds instead of the largest match which you can use instead of the general modifier (?U):

- ? – use after a quantifier to do a minimal search, e.g. .*? or \d+?

GROUPS:

In some cases you need to group your expressions together so that, for example, you can save them for a later replace, or to indicate a choice of words:

- (atext|btext) – atext or btext

- (group) – group the words together for later retrieval – you can use multiple groups

REPLACING:

When replacing text, one of the most useful features is to be able to use text that was matched by storing it in a group. Once you have grouped text you can reference it in your replace command:

- \1 – use in Replace to retrieve the value of a saved group (use \2 for the second group, etc.)

CREATE LINKS AND FOOTNOTES

— LINKING YOUR TEXT —

This tutorial describes how to create links or footnotes in Sigil.

Sigil provides a couple of ways to link text to other parts of your book, such as chapter names and footnotes, so that readers can select the link and jump to the identified text.

IDS AND LINKS

In order for Sigil to create a link from certain words in your book to other words in your book, you first need to give an ID or a name to the words you want to link to. You can then link text like a footnote reference to that ID (sometimes called an anchor ID).

An ID is just a unique name, like footnote1 that you will assign to a part of your text so that you can refer to it. ID names must be unique within an HTML file, but its best if they are unique throughout the whole EPUB in case you move text around.

Tip

If you want the destination to be the top of a file, then you don't need to create a special ID – you just need to know the filename.

A link is a way to refer to your ID. It could just be footnote1 if the ID is in the same file as your link. Or if the link and ID are in different files it could look like filename#footnote1 – the # character is just used to separate your filename from the ID name. The link could also include directory names like ../Text/filename2#footnote7 but still just refer to a filename and ID.

Note

Links to websites or other pages outside of your EPUB will not work if you click on them in Sigil, even though they may work on some ereaders.

CREATE LINKED TEXT IN BOOK VIEW

The Book View editor provides some basic functions to allow you to edit IDs and links.

CREATE AN ID

In Book View, you can create or assign an ID to text so that you can point to it:

- Select the text you want to link to, e.g. [1] This is a footnote

- Click on the Anchor icon () to open the anchor properties window:

- Enter a name for the anchor – names must be unique in the file

- The text is marked as an anchor:

- You can double click the text to view or edit the anchor's ID name

Tip

You can remove an anchor tag and its ID in Book View by right clicking on it and selecting Remove.

CREATE A LINK

In Book View you can create a link to text you have already marked with an ID as follows:

- Select the text you want to be linked, e.g. [1]

- Click on the Link icon ()

- In the Link dialog change the URL type to <other> and enter the ID to point to your destination, e.g. footnotes.xhtml#footnote1 (you can leave out the filename if the ID is in the same file):

- The text is now marked as a link:

Tip

You can remove a link in Book View by right clicking on it and selecting Unlink or use the unlink icon.

Note

Most of the other options in the Link properties window are not used. For instance you could change the Link Type to "Link to anchor in the text" but this is only useful if you used anchor tags in the current file that you want to link to. Target and Advanced options are also generally not used.

CREATE LINKED TEXT IN CODE VIEW

In Code View IDs and links are created as with any HTML document.

Create an ID

In Code View you can create two types of IDs that can be used for links.

- Anchor IDs like in Book View: just use an a tag around the destination text, e.g. <a id="footnote_1">This is a footnote</a>

- ID names assigned to existing HTML tags, e.g. <h3 id="chapter1">Chapter 1<h3>, or <p id="id7">text</p>

Which form you use is up to you, although Chapters should always use IDs in the heading tag.

CREATE A LINK

In Code View use the following syntax:

<a href="file2.xhtml">Linked to file</a>

<a href="file2.xhtml#footnote1">Linked to a footnote</a>

<a href="#samepage" id="id7">Linked to text on the same page</a>

<a href="../Text/file2.xhtml#footnote2">Linked to a note in another file</a>

Note

You can point directly to a text file without a path since text files are in the same directory in the EPUB, but you can also prepend the filename with "../Text/".

REVERSE LINKING

Most ereaders have a Back button that you can click once you follow a link to take you back to the original linked text. But for those that don't, you can create a link from your destination text back to your original source text. This is often called reverse linking

Reverse linking is just like any other kind of linking – it just means you have to create a link from your destination text back to your source text – so both source and destination will have an href and id tag and will be mirror versions of each other.

In Book View, assign an ID to your source text just like you did to your destination. Then create a link from your destination text back to your source text in the same way you created the original link.

In Code View an example would be:

<a href="file2.xhtml#footnote1" id="text1">See footnote1</a>

<a href="file1.xhtml#text1"     id="footnote1">This is footnote1</a>

USE STYLESHEETS

— FORMATTING WITH STYLE —

This tutorial describes stylesheets and how to use them in your EPUB.

A stylesheet (or CSS – Cascading Style Sheet) is a list of instructions that tells ereaders how to display the text in your book. More specifically it tells the ereader how to style text in HTML tags used in your book. Understanding and using CSS is the best and most flexible way to layout your book exactly as you want.

You can find other introductions to CSS online, including:

- W3Schools CSS Guide [http://www.w3schools.com/css/]

And if you really need to dig into the details, the CSS2 technical specification is available:

- CSS 2.1 Specification [http://www.w3.org/TR/CSS2/]

Tip

Using CSS can get quite complicated, but if you become familiar with the basics it will make it much easier to understand why your book looks the way it does and how to modify its layout.

Note

This chapter assumes you are familiar with Code View since you need to use Code View to see the details of styles.

WHAT IS A STYLE?

Styles are used in a book to say things like “make this text blue”, or “make text centered”, or leave a little more space above this text. A style definition is just text that looks like:

color: blue;

which says make the color of the text blue.

But styles aren't very useful unless they are applied to something. In the case of an EPUB styles are applied to the HTML elements in your document, like p (paragraphs), h1 (level 1 headings), div (divisions), span (spans), etc.

There are 3 ways styles can be used for HTML tags in an EPUB:

- Style Attribute: a style applied directly to one specific HTML element in the document

- Style Element: a group of styles in one document that can only be used by that document

- Stylesheet: a separate CSS or stylesheet file that can be used by many HTML files

A separate stylesheet file is the recommended way to use styles. The descriptions below of each approach will help you understand why.

STYLE ATTRIBUTES

To apply a style directly to an HTML tag, you can use the style attribute in the tag. For example, to apply the style color: blue to a paragraph you would change

<p>Hello</p>

to:

<p style="color: blue">Hello</p>

In fact this is exactly what Book View does when you select the buttons to make text Bold, Italic, Underline, etc., only in this case it will usually use the span tag, e.g.

<span style="text-weight: bold">bold text</span>

This works perfectly well if you just want to change a few things and rarely update the formatting. But if you later want to change from using bold to italic for certain words then you will have to edit every place in the book that set the specific style.

Styles attributes are rarely used unless they were created by software doing an automatic conversion or update and should be avoided.

There is a much better way to manage styles: using style selectors.

STYLE SELECTORS

A style selector is a way to give a particular style a name, and then use the style in the document just by referring to its name. More specifically the style selector is used to select which elements in your document should use the style you define.

For example, if you wanted to style all paragraphs in your EPUB to be centered, you could define a rule for a style selector as follows:

p {

text-align: center;

}

This defines a style selector p that will match (or select) all paragraph elements.

You can control which tags get selected by modifying the selector. One of the most popular ways to select specific tags is by using a class name. This is just a name that you choose (like "firstparagraph" or "centeredtext") to give to your tags.

For example if you wanted to style the first paragraph in a chapter slightly differently than other paragraphs, you could define a style selector as follows:

p.first {

text-indent: 0em;

}

This defines a style selector that will match (or select) paragraph tags that use the class name first. You could then use that style in your document for a paragraph by assigning the class name first to the paragraph as follows:

<p class="first">First paragraph in a chapter</p>

The great advantage in this abstraction is that you can now update the values of the style (to change the indentation or other settings) without having to update your text.

Tip

It is common practice to use class names that refer to the purpose of the style and not what the style does in case you change the styling later. For instance, use span.placename instead of span.bold in case you want to change your place names to italic later.

Now you need to actually store your styles somewhere in order to use them.

In an EPUB you can store your stylesheet in the same file as your text (using the style element), or in separate files (external stylesheets or CSS files).

STYLE ELEMENTS

When you store style selectors and rules in the same file as your text they can only be applied to the HTML file they are in and cannot be shared by other HTML files.

When using these internal styles, the style definitions are stored inside a style tag at the top of your HTML files. If you open a file in your book and switch to Code View, you will see that the top of the file contains text between two head tags. This section of your document contains information about the file, and one of the things you can put here is the style tag that defines your internal style rules.

Here is a typical use of internal styles (they are surround by the style tag):

<?xml version="1.0" encoding="utf-8" standalone="no"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"

"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html >

<head>

<title></title>

<style>

h1 { text-align: center; }

p.boldtext { font-weight: bold; }

</style>

</head>

Once you have created style rules, you can apply them to your HTML tags. In the case of the h1 tag in the example you don't need to do anything because you've stated that every h1 tag should be centered (because you haven't specified a specific classname the style will apply to all text using the tag). But for the p tag, you need to tell your paragraph to use the class boldtext as above, e.g.

<p class="boldtext">A paragraph.</p>

Internal styles are a way of grouping styles together and using style selectors, but when you have many files in an EPUB it becomes a bit confusing as you have to have separate style rules in each file.

Internal styles are usually only created by software doing automatic conversion or cleaning, and should be avoided if you are creating the styles yourself or doing an extensive edit of a book.

The best way to manage styles is to use a separate stylesheet file to hold your style rules.

Tip

You can convert your inline styles and your internal stylesheets into a separate stylesheet file. Just remember to assign the appropriate classes to your tags and to delete the old style attributes and elements.

EXTERNAL STYLESHEETS

If you create a separate file to hold all your style rules, they can apply to the entire book. They are also much easier to find and edit, and updates are much easier to manage as you add and remove files. It also helps to ensure your book is formatted consistently as you can see all your styles in one place.

In Sigil, external stylesheets are stored in the Book Browser in the Styles folder. You can double click on the stylesheet file to add and edit your styles as necessary.

Tip

If there isn’t a .css stylesheet file in the folder already, you can create a blank one by right clicking on Styles and selecting Add Blank Section.

For example, if you open the styles.css file in a simple EPUB you might see something like this:

Warning

If you have any errors in your style definitions they will silently be ignored. You can use Preview View to check for errors.

Even though you've created the external stylesheet, its not actually used by anything yet.

To use it, you need to tell your HTML files to use the stylesheet – by linking to them as described below.

LINK YOUR HTML FILES TO A STYLESHEET FILE

To tell your HTML files which stylesheet file to use you need to link the stylesheet to your HTML file:

- Select one or more files in the Book Browser

- Right-click on the selection

- Choose Link Stylesheets from the context menu

- Click on the stylesheets you want to be used for the files and select OK.

You can link multiple stylesheets to one page if separate CSS files help you organize styles better, but most EPUBs use just one stylesheet.

Note

If you link multiple stylesheets they will be applied in order so the styles in the last stylesheet will override the styles in the preceding stylesheets.

WHAT STYLES SHOULD BE USED?

The styles you use for your text are entirely up to you.

The best way to learn to use styles is to look at an EPUB that contains formatting you like and look at what its CSS files contain and how it uses those styles in the book.

EMBED FONTS

— USING CUSTOM FONTS IN YOUR BOOK —

This tutorial shows you how to use custom fonts in your EPUB.

Tip

One of the benefits of ereaders is that you can choose your own font, so its usually best to just use embedded fonts to highlight specific types of text such as chapter headings, quotes, etc. and not to change the font of the entire book.

To use a font in an EPUB you must first load the font into the EPUB, define a style for the font, and then apply the style to your text.

Note

You will need to know about stylesheets to embed fonts so you should read through the Stylesheets chapter first.

ADDING FONTS TO YOUR EPUB

To add fonts to your book, use File→New→Add Existing Files, or right click in the Book Browser and select Add Existing Files from the context menu. This will display a dialog allowing you to select one or more files from your computer. Select as many font files as you want.

The fonts will be added to the Fonts folder in the Book Browser. However, they are not yet actually used anywhere in your book – they are just available to use.

Note

Many fonts are not free. Before you include fonts in your EPUB please make sure that you have a license or permission to use them. There are many free fonts available online if you search for them.

Fonts files must be either OpenType (.otf) or TrueType (.ttf) format. All ereaders should support otf but most will likely support both formats.

DEFINING STYLES FOR YOUR FONT

Once the fonts are in your EPUB, you must define a style that includes them.

Open a stylesheet that you will use to include your fonts (see the Stylesheets chapter for more details).

Add a definition of the font, e.g.:

@font-face {

font-family: 'MyFont';

font-weight: normal;

font-style: normal;

src: url(MyFont.ttf);

}

@font-face {

font-family: 'MyFontBold';

font-weight: bold;

font-style: normal;

src: url(MyFontBold.ttf);

}

Note

You must define one @font-face rule for each style of font (normal, bold, italics, etc.).

When using font-family in @font-face and later, the font name must either be quoted or unquoted every time you use it, but not both. Always using quotes around the font name makes things more consistent and avoids having to check if a name is valid without quotes.

The font still isn't actually being used in the book yet, that's the next step.

APPLY YOUR FONT TO TEXT

To make use of the font you need to create another style that you will then assign to sections of your text.

So, for example, to use your new font for headings, define the style for the heading tag as follows:

h1 {

font-family: 'MyFontBold', serif

}

Or to certain paragraphs:

p.longhand {

font-family: 'MyScriptFontItalic', serif

}

Or if you want, although its not recommended, you can apply the font to all text in the book:

body {

font-family: 'MyFont', serif

}

Tip

The font-family rule above says to use your font if possible for the text, but if its not possible use a generic serif font.

Note

You may need to save your EPUB and then re-open it in Sigil to make sure Sigil reads your new style.

Due to a bug in the Qt libraries used by Sigil, fonts may not display correctly in Sigil so you will may have to test them on your target ereaders.

FONT OBFUSCATION

When you use a font in an EPUB, the font file could be extracted by someone and used somewhere else. If your fonts are licensed you may want to prevent this.

You can use Sigil's font obfuscation menu to scramble the font file using one of two standard methods, Adobe or IDPF – which one is up to you, but you should test on your target ereader to make sure the font is still readable. Obfuscation is not encryption – it just modifies the font file making it hard to use elsewhere while still being useable by readers to display fonts.

To use font obfuscation, right click on your fonts in the Book Browser window, right-click and select Font Obfuscation from the menu and choose a method to use for obfuscation.

TIPS

— ADVICE ON USING SIGIL —

This chapter is a list of tips from experienced users of Sigil.

Everyone uses Sigil differently but the tips may still be helpful to you. Keep in mind that Sigil is used by people making only a few occasional updates to books as well as people converting or cleaning up books professionally on a daily basis.

When you start to use Sigil more often you may find some of these suggestions useful:

- Save often to allow automatic error checking and cleanup to run – to catch issues before they become larger.

- Make backup copies of your file as you edit, especially before doing major changes.

- Learn about stylesheets (CSS) and use them to control formatting instead of inline styles. This will make formatting your book much easier in the long run.

- Use Code View for editing. Book View works great, especially for quick word corrections and some basic styling like headers, but if you want to format a lot of text or to control the exact styles used, then use Code View to avoid Book View using its own styles or inserting extra blank spaces, etc. And since many of Sigil's advanced functions are only available in Code View you should become familiar with it sooner rather than later.

- Set Clean Source to Pretty Print instead of the default Tidy setting. Then exit and restart Sigil. This will help to clean up the spacing of code without changing styles or the code itself. Using Tidy can be helpful for a lot of people, but once you start editing your HTML code directly you won't want it creating inline style tags or making other changes. If you really don't want your code changed at all, then turn Clean Source off.

- Keep the Well-Formed check turned on. If this is turned off then Sigil will automatically correct errors when you switch views or save – which could mean deleting some of your text. Leaving it on means you will be prompted to fix any errors.

When you have finished editing, consider following this checklist:

- Validate to check for errors then fix them.

- Spell Check, and consider creating a separate dictionary for your book if it has lots of unique words.

- Set Title, Author, Language, Copyright and, if you want, Publication Date, Subject, Description, Copyright and ISBN if there is one.

- Use Add Semantics to set your cover image and cover file (if you have one) as type Cover.

- Set your first text file (where the book will open) as semantic type Text.

- Test your text links or footnote links work as expected.

- Regenerate your TOC or check that it's up to date and working, and regenerate your inline TOC if there is one.

- Test your TOC links work as expected.

- Link your stylesheets to all files that need them.

- Search for and remove or update text like &nbsp;, &quot;, <br />, empty paragraphs <p>&nbsp;</p>, empty <div> tags, src="", href="", - to ndash, etc..

- Search for sgc- classes, <style> tags or style= attributes and convert them CSS files.

- Scan your book in Code View line by line for unexpected formatting, especially if you've used Book View to make updates.

- Validate again.

- Proofread on actual ereaders. Sigil can only give an approximation of what your book will look like. There are lots of ereaders and not all software or devices support all EPUB features and formatting in the same way.

FAQ

— FREQUENTLY ASKED QUESTIONS —

WHERE TO GET HELP

WHERE CAN I GET HELP WITH SIGIL?

If you have any questions about Sigil not covered in the Sigil User Guide, then visit the Sigil Forum at MobileRead [http://www.mobileread.com/forums/showthread.php?f=203] where the users and developers of Sigil will try to help.

WHERE CAN I ASK QUESTIONS ABOUT EPUB?

You can post on the EPUB Forum at MobileRead [http://www.mobileread.com/forums/forumdisplay.php?f=179] if your questions are more about how to format and style something in an EPUB than how to do something in Sigil.

WHERE CAN I REPORT BUGS OR REQUEST FEATURES?

Read the Reporting Issues [http://code.google.com/p/sigil/wiki/ReportingIssues] information to submit a bug report or feature request.

STARTING SIGIL

SIGIL DOES NOT START ON MY 32 BIT WINDOWS OS?

If you are running a 32 bit version of Windows make sure you downloaded the 32 bit version of Sigil and not the 64 bit version.

SIGIL DOES NOT START ON MAC OS 10.6?

Sigil on the MAC requires x64 bit cpus and MAC OS 10.6 (Snow Leopard) or later.

SIGIL DOES NOT START ON LINUX?

You need to use a version of Sigil packaged for your version of Linux – go to the Linux Distro Packages [http://code.google.com/p/sigil/wiki/LinuxDistroPackages] page to see if Sigil is packaged for your Linux version.

USING SIGIL

IS THERE A TUTORIAL OR MANUAL FOR SIGIL?

Yes – in Sigil use Help->User Guide to see an HTML version of the Sigil User Guide which also includes tutorials. Or visit the Sigil home page for a link to the HTML and EPUB versions.

CAN I WRITE MY BOOK USING SIGIL?

Yes, you can, but Sigil is primarily an editing program for books that have already been written in one of the many existing word processors. You are probably better off writing your book in your favorite editor, exporting it to HTML, and then using Sigil to format it for EPUB. But if you really want to write and edit it in Sigil, then you certainly can.

ARE DOC, MOBI, KF8 FORMATS SUPPORTED?

Sigil is an EPUB editor. It can open EPUB files and import HTML files, but all other formats must be converted to HTML first before importing.

There are a lot of formats out there, and converting from one format to another is not a trivial issue. Since there are already excellent tools for converting from one format to another, Sigil will remain focused on being the best EPUB editor available.

For converting EPUB to other formats, calibre [http://calibre-ebook.com/] is strongly recommended.

For exporting Word files to HTML for import into Sigil, use Word's Save As Filtered HTML open, or refer to Save as HTML Word macro [http://www.mobileread.com/forums/showthread.php?t=142530].

To convert Mobi to HTML you can use calibre to unpack the Mobi file to access the HTML file or convert Mobi to HTML.

HOW DO I USE REGEX?

See the Regular Expressions chapter in the User Guide for more details and tips on using Regex.

SIGIL CRASHES WHEN IMPORTING MY FILE?

Sigil can only import or open valid HTML and EPUB files. It will try to recover from some common problems in files, but if there is a significant issue (missing standard code or files) then it may be unable to open the file. In some cases the file is so corrupt that it will cause Sigil to crash. Sometimes you will get an error message that might identify the problem with the file. In this case you may be able to open your file with a Zip or archive program and edit the files to correct them. But often the cause of the problem is not clear or not reported well from the low level software that Sigil is based on.

If you want to report a problem with a file that cannot load and crashes Sigil, then you must attach the EPUB file to your bug report. You can set bug reports to private so that non-developers cannot see your file. But in most cases you will need to correct the file.

SPELL CHECK DOES NOT HANDLE QUOTES OR DASHES CORRECTLY?

If you install your own dictionary and it isn’t recognizing curly quotes, em-dashes, etc. then you may need additional hyphenation dictionary files. See Preferences in the User Guide for more details.

I PASTED SOME RICHLY FORMATTED TEXT INTO SIGIL BUT IT’S ONLY PASTED AS PLAIN TEXT?

Don't paste rich text directly into Sigil. It doesn’t work very well.

Instead, export (or convert) you text to HTML and then import the new file directly. This will preserve all formatting. Or if its a small amount of text you could try using the Paste from Word feature in Book View.

FORMATTING AND STYLES

WHY DOES MY BOOK DISPLAY RANDOM QUESTION MARKS?

This may be because your original file has soft hyphens [http://en.wikipedia.org/wiki/Soft_hyphen#Hyphens_in_computing]. ADE (the Adobe software that is used to display EPUB files on many systems) does not handle soft hypens. So just remove the soft hypens from your file and the question marks will go away. Look for something like &shy; or &#8209;. Basically anything “strange” that exists between those two characters. But you have to look in Code View to see the raw HTML.

It may also be because ADE cannot perform font substitution.

In Sigil, if the font you are using does not have the required glyphs [http://en.wikipedia.org/wiki/Glyph] to render a character present in the text, glyphs from a different font that can render it are used. This is called font substitution. So as long as some fonts on your computer can display these characters, so can Sigil.

ADE on the other hand only displays a small subset of Unicode characters by default. The supported characters are listed in the Adobe PDF Reference v1.7 [http://www.adobe.com/devnet/pdf/pdf_reference_archive.html], Appendix D, tables D.1 and D.3.

If you want other characters than these to display in ADE, you will have to embed the required fonts.

HOW DO I CHANGE THE STYLE OF MY TEXT?

Read the Stylesheet chapter in the User Guide – you’ll need it to make use of many of the answers in this section.

Note that ereaders may support displaying formats or styles differently and how text is display in one reader, or in Sigil, may be slightly different to how its displayed in another ereader.

WHAT ARE STYLESHEETS AND CSS?

CSS stands for Cascading Stylesheets. See the Stylesheet chapter in the User Guide for more details on CSS and why you should use stylesheets to format your text.

CAN I EMBED MY OWN FONTS USING SIGIL?

Yes – see the Fonts chapter in the User Guide.

WHAT DOES SGC-1 MEAN IN MY DOCUMENT?

SGC just indicates a Sigil class that is used by Sigil for formatting information in internal stylesheets.

HOW DO I ADD BLANK LINE?

Don't. Its much better to use stylesheets to define the amount of space above or below your special sections using a style definition. For instance to leave 1.5 lines of space above a paragraph:

p.blankabove { margin-top: 1.5em; }

If you really want to, you can insert a break:

<br />

or an empty paragraph:

<p>&nbsp;</p>

For multiple blank lines, its best to use a style to define the amount of space you want to leave.

HOW DO I START A NEW PAGE?

If you use a separate file for your page, then almost all ereaders will start a new page for your text.

HOW CAN I USE AN IMAGE FOR A CHAPTER HEADING IN THE TOC?

Switch to code view and find your image – it will look something like:

<img src="../Images/myimage.png" />

Add the heading tag you want to use for the image and give it a title to display in the TOC, e.g.

<h1 title="CHAPTER 1"><img src="../Images/myimage.png" /></h1>

The TOC will now have an entry called "CHAPTER 1" which links to your image.

You can even use heading tags with no text in your document if you just want a Chapter entry:

<h2 title="Chapter Subsection"></h2>

HOW DO I ADD MARGINS TO THE TEXT?

Add this text with your preferred left and right margins to your CSS definitions:

@page {

margin-left: 5px;

margin-right: 5px;

}

HOW DO I REMOVE THE WHITE SPACE BETWEEN PARAGRAPHS?

To remove the white space between the paragraphs, add this to CSS definitions:

p {

margin: 0;

padding: 0;

}

This will affect only the paragraph spacing (the p means paragraph). To remove all the whitespace between the various elements and make the document look more “book like”, use this code:

body, div, p, h1, h2, h3, h4 { margin: 0; padding: 0; }

HOW DO I ADD A “DROP CAP”?

Drop caps are not supported in all readers, but there are several ways to do a drop cap. If your book is formatted just right, it can be done just with CSS.

Add this code to your CSS definitions, which will set the text using the “dropcap” class in a span tag to use certain values:

span.dropcap {

float: left;

font-size: 4.7em;

line-height: 0.8em;

margin-right: 3pt;

margin-bottom: -0.1em;

}

In Sigil, find the paragraph you want to start with a drop cap, and switch to Code View. Change the text from something like this:

<p>Hello</p>

to:

<p><span class="dropcap">H</span>ello</p>

Switch back to Book View and you should see the drop-cap.

Add <span class="dropcap"></span> around all the letters at the start of paragraphs where you want a drop cap.

You might need to adjust the values for font-size, line-height and margin-bottom to get the effect you want. Sigil’s Book View may not show exactly how it’ll appear on all ereaders, but it’s pretty close.

CONTRIBUTING TO SIGIL

— HELPING DEVELOPMENT —

Sigil is free and open-source, and it is developed and supported entirely by volunteers. Your contributions can help improve Sigil.

TRANSLATING SIGIL

Translating Sigil into other languages is highly encouraged. There is an active community of volunteers who translate Sigil already, and new languages can always be added.

The best way to translate Sigil is to use the web based translation system provided by Transifex. Translations done using Transifex are downloaded just before releasing a new version:

Sigil translations @ Transifex [https://www.transifex.net/projects/p/sigil/]

Alternatively you can use local Desktop tools for translation. Sigil uses Qt's Linguist tool for creating and editing translations. You can either download Qt and compile the tools manually or use the pre-built packages:

Pre-built Translation tools [http://code.google.com/p/photivo/downloads/detail?name=translator-tools-win32.zip]

Updating and creating new translation files using the Desktop tools is the same process:

- Open a terminal and change to the src/Sigil/Resource_Files/ts directory. This holds all of the raw translation files.

- Run lupdate ../../ * -ts out.ts to either generate a new translation file or to update an existing one with any new strings that have been added.

- Use Linguist to write translations for the strings in a given ts file.

All translations files should have the form sigil_lang.ts. Where lang is a two letter language code. For example the Polish translation will have the filename sigil_pl.ts.

ASSISTING USERS

If you are an experienced Sigil user you can help development by helping to answer user questions – primarily at the official Sigil Forum at MobileRead. You can also check issues on the development website and add comments.

CODING

If you are a C++ programmer and have suggestions for improvements or bug fixes you are welcome to submit patches for consideration.

DONATIONS

Sigil is free software, but your donations are greatly appreciated.

Please use Help→Donate to say thanks and to help Sigil development continue.

The Sigil User Guide is also free. If you've found it useful, please say thanks by donating directly to the author.

Table of Contents

Introduction

About Sigil

About EPUB

Contents

Installation

Windows

Mac

Linux

Features

Overview

User Interface

Open and Save Files

Book View

Code View

Preview View

Book Browser

Table of Contents (TOC)

Metadata Editor

Find & Replace

Images

Splitting and Merging

Spell Check

Validate and Clean

Preferences

Tutorials

Create an EPUB

Edit an EPUB

Use Regular Expressions

Create Links and Footnotes

Use Stylesheets

Embed Fonts

Tips

FAQ

Where to Get Help

Starting Sigil

Using Sigil

Formatting and Styles

Contributing to Sigil