Dave Heiland - Sigil User Guide

Regex Reference

This tutorial is basically a quick reference for Regex. You should read 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
• A one page command summary
• Regex as used by Python
• Official PCRE details start at the PCRESYNTAX(3) section

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 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:
• Replace:

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.

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.

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

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+?

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

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.)

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

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

• CSS 2.1 Specification

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.

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

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.

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

Hello

to:

Hello

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.

bold text

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.

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.