Introduction
 Page overview
Options for content checking
Your document
 Key shortcuts
 Document views
 Bulk-selecting elements
 Element toolbar
 Moving paragraphs
 Labeling elements
  Paragraphs
  Page breaks
  Images
  Tables
 Editing paragraph content
 Failed import

The Review page is where the heavy lifting happens—both for Bookalope and for the user. Once you’ve worked your way through this page, you’re almost done with creating an accessible ebook or a well-designed print book or another structured book file format. But don’t panic! Just because many options are available on this page doesn’t mean that there is a lot of work to do for you.

At the core of working with Bookalope is the opinionated and strict separation of content and presentation of your book. After you’ve uploaded your book, Bookalope’s AI analyses the content of your book and how that content is styled, and based on the results of that analysis Bookalope “labels” all structure elements of your book. And it is now your job to review those labels, to make adjustments if necessary and to add more information to really polish up your accessible book!

Depending on the size of your document the Review page can be a large and long page. That’s simply because this one page renders your entire book from start to finish onto this single page:

As you can see, there are two sections on this page: Options for content checking and Your document. Read on to discover how working with these two sections helps you get your document into perfect shape!

When Bookalope extracts the content of your book, it automatically cleans up different issues which it deems are safe to handle. Ambiguous issues, however, can be marked up for manual review on this page. In addition to that you can have Bookalope check various aspects of your content to further improve its accessibility and quality:

By default, most of these options are deselected because some checks can take a few moments for large documents, and so we decided to make them opt-in (rather than slow down your progress through the document).

At the top, you can select from a set of rules that Bookalope employs when it checks the content of your document:

• Don’t check: In this case, Bookalope won’t perform any content checks on your document.
• Simple defaults: These rules will check for multiple spaces and for spaces around punctuations, typewriter quotation marks that should be curly quotation marks, and for suspicious uses of an ellipsis.
• Chicago Manual of Style: In addition to the Simple defaults this ruleset also checks for words in all-capitals (which may be candidates for small-caps), swapped quotation marks and sentence punctuation, and suspicious uses of various hyphens and dashes. It also checks more elaborately for issues around spaces combined with other punctuation marks.

We understand that these rulesets are far from complete and may not align with the typographical rules across all languages and countries. If you need custom rules or if you’d like to expand these existing rulesets, please contact us to discuss a way forward.

Underneath the ruleset selection, you will find more content check options that you can choose from:

• Check spelling: Provided you have selected one or more languages in your Bookflow’s metadata you can have Bookalope spell-check your document. This option is disabled if you haven’t selected a language.
• Classify other languages: Provided you have selected one or more “other” languages in your Bookflow’s metadata you can have Bookalope classify the content of your book by the languages you selected. This is an advanced accessibility feature for ebook export, and it is disabled if no other languages are selected. After you apply this option to your document, Bookalope finds words that belong to any one of the selected other languages, and marks them up. If a word belongs to more than one other language, Bookalope will show you that word as an issue to review and fix.
• Check URLs: Stay tuned for this one…

Once you’ve selected the options for content checking, click the Apply options button and Bookalope will run your document through the checks you’ve selected. When done, it’ll refresh the document view with the results.

The Your document section occupies almost everything on the Reviews page, and is the most important part of the entire Bookflow. It renders your document and shows you in great detail the document structure that Bookalope has determined. It also allows you to tweak and enrich the extracted structure easily, and edit any of text content.

One thing you should note as you work your way through your document it that Bookalope saves all your changes automatically, so you can close your browser at any time and pick up your work later!

But first, let’s review some useful keyboard shortcuts that make working through your document so much easier.

To navigate this page with more ease, you can press T to jump to the top of the page, and B to jump to the bottom of the page.

A Document view allows you to filter out content that’s not immediately relevant for what you’re working on. For example, to review all images you can either scroll through your entire document and try to find the images, or you can switch into the Image view and filter out everything else.

The Review page offers five different views, each of which can be entered using a dedicated key:

• Normal View: No filter is applied in this view and all elements in your document are visible. Use the A key to enter this view.
• Headings View: The larger structure of a document is important for generating the TOC and for accessibility. This view shows only heading elements and filters out everything else. Use the H key to enter this view.
• Selected Elements View: Bulk-selecting elements can be very useful when working with paragraphs of the same type that are scattered across your document. This view filters everything but the currently selected elements. Use the S key to enter this view.
• Empty Paragraphs View: By default, Bookalope ignores empty paragraphs which may not be intended. So, this view shows you all empty paragraphs (if any) and filters the rest. Use the E key to enter this view.
• Images View: This view shows all images of your document, including their captions (if they’ve been labeled accordingly). Use the I key to enter this view.

Note that pressing the same key twice toggles the same view on and off: it switches between a view and the entire document (the Normal View).

Every paragraph, page break, image, and table in your document has a checkbox next to it which you can check and uncheck:

The purpose of the checkbox is two-fold:

• one, you can quickly create a selection of multiple elements based on different properties, and any change to a selected element then cascades to all elements in that selection; and
• two, it locks a single element so that you can fine-tune it using the Element toolbox.

There are three ways of creating a selection:

• Manual selection: By default, selecting one element will deselect the current selection. Hold the Command ⌘ key on Mac (or Ctrl key on Windows) to add more elements to the current selection.
• Selecting based on styling: Every paragraph in your document has a set of style properties (e.g. font and size, weight, color, margins, and more) which serves as the basis for structural classification. Hold down the Alt key when selecting a single paragraph and Bookalope will select all paragraphs with the exact same style properties. Like with the manual selection, by also holding down the Command ⌘ key on Mac (or Ctrl key on Windows) you’ll add to the current selection rather than replacing it.
• Range of consecutive elements: If you select a paragraph and then hold down Shift while selecting a second one, Bookalope selects all paragraphs in between those two, effectively selecting a range. Here, too, hold down the Command ⌘ key on Mac (or Ctrl key on Windows) to add to the current selection rather than replacing it.

Please note that selecting bulk items works on paragraphs and images separately.

You will notice a floating toolbar at the bottom of the browser window:

As you hover your mouse pointer over various document elements, the toolbar updates with information about the element. For example

shows additional information about a paragraph: this one is classified as a Standard Paragraph and the document formatting for that paragraph is also shown. Now, if you select a single element, e.g. a paragraph in your document then the toolbar will show several additional options that you can modify for the selected element:

We’ll talk about the different toolbar options in more detail below.

You can move paragraphs up and down by clicking their content—same as editing them—and then press and hold the Alt key and press the Up or Down keys to move the paragraph around.

When you upload your document, Bookalope’s custom-designed AI extracts the document’s content and detailed information about the styling of that content. Bookalope then classifies the document content based on that styling; for example, it attempts to determine which paragraphs are the headings of what level, what page breaks are useful, what text portions might be emphasized text, and so forth.

Bookalope shows the result of that classification as a label to the left of every element in your document. You can adjust that label if necessary, and you can add more detailed information to the element using the toolbar.

In our example here, you see the heading “A Blog Collection”, followed by an empty paragraph and a page break for page 2. To the left of each paragraph you have its label: the correct label Chapter Title for the paragraph “A Blog Collection”, the Ignore label for the empty paragraph (because we won’t need it anymore), and the Ignore label for the page break. We’ll detail these labels later.

Right next to every label is a checkbox for bulk-selecting elements. We talked about that above.

Bookalope’s AI puts great effort into assigning correct labels to the paragraphs of your document. These labels express headings (therefore creating the larger structure of your document) or they represent other text elements like abstracts, quotes, poems, and so forth. Click on the label select box, and you’ll see a complete list of supported paragraph labels:

You’ll notice that the labels are grouped:

• Headings: The Headings labels are reserved for those paragraphs that are a heading for a new section of your book; from Part through Chapter, down to a Sub-subsection. The Subtitle label allows you to label paragraphs below a heading as a subtitle of that heading. Please note that Part and Chapter headings open a new page! Also note that for accessibility reasons multiple consecutive heading paragraphs are merged into one single heading, and their paragraph breaks are transformed into line breaks.
• Paragraphs: The majority of paragraphs in your document are simple, narrative paragraphs with the Paragraph label. But some stand apart from the normal narrative visually and therefore are meaningful structurally. By using any of the following labels you can instruct Bookalope to style these according to their label, and also to generate appropriate accessibility markup if necessary. Let’s take a look at those other paragraph labels:
  • Paragraph: This is just a normal paragraph anywhere in your text.
  • First Paragraph: Use this label if you want to treat a random paragraph as if it followed first after a heading. Normal paragraphs following a heading are the same as the First Paragraph, but occasionally you might like to treat a random paragraph as a first one.
  • Dedication: A paragraph that’s a dedication, often used on a dedication page in a book. If you mark your chapter as Dedication then you won’t need to use this paragraph.
  • Letter: Sometimes narrative contains a letter or note, and you can use this label to indicate that.
  • Quote: A quotation from another source.
  • Poem: A verse or line of a poem.
  • Quote Author and Poem Author: Use this label if your paragraph follows a Quote or Poem and if it contains the author or reference for it.
  • Verbatim: If your narrative contains code or other text that needs to stand out using a fixed font, then this label can come in handy.
  • Abstract: A summary or abstract that should follow a heading. You can use this when you work with an academic publication which often contains an abstract at the beginning of chapters.
  • Exercise: An experimental label for future use. It’s intended for paragraphs that contain an exercise or a set of instructions to the reader, and in the future perhaps may also contain interactive GUI elements.
  • Address: A paragraph that contains a real-world address.
  • Caption: Use this label in conjunction with an image or table to mark up the caption of an image or table.
• List Items: Sometimes a paragraph is the item of a bulleted or numbered list, and these are the labels for such list items. If you label a paragraph as a list item and if the paragraph starts with a number or a bullet character of sorts, then Bookalope will automatically attempt to remove them (because it won’t be needed anymore). The TOC Item label is somewhat special here; we discuss the Table of Contents in more detail in our recipes.
• Insets: On occasion it is useful to set apart a paragraph from the main text, and that’s what an Inset does. You can choose a paragraph alignment within the inset as well.
• Other: Finally, some paragraph labels don’t really fit into any of the above categories.
  • A Note is a paragraph linked to from somewhere else in the text and Bookalope will usually label note paragraphs for you. Often you can find those paragraphs after importing an ebook (for more details see our Footnotes and Endnotes recipe).
  • A Separator paragraph is a narrative break which you may need to make explicit. Some such breaks are expressed using an empty paragraph, or a typographical ornament or a dinkus glyph like an asterism ⁂ or three asterisks * * *.
  • If you want to ignore and remove a paragraph from you document, simply use the Ignore label ; note that Bookalope will set all empty paragraphs to Ignore by default!

As a general rule, Bookalope is strict about placing labels, and it will ignore labels that it deems irrelevant in a given context. For example, the Subtitle label only makes sense if it follows a heading, whereas the Caption label only makes sense for paragraphs that precede or follow an image or table.

We often want to add more detailed information for a paragraph (and for accessibility’s sake we should). To do so, click the checkbox to the right of the paragraph’s label to lock in that paragraph for the toolbar:

With the paragraph labeled a Chapter Title, we can now further specify the kind of the chapter that this title opens, e.g. a Halftitle or Copyright chapter, an Epilogue, and so forth. Additionally, you can check the Remove from Table of Contents option if you don’t want to list that heading in your book’s TOC; and you can check the Hide chapter title option if you don’t want the heading shown in the chapter at all.

Notice again the text at the bottom of the toolbar: Bookalope shows you a summary of the paragraph properties that it has extracted. It can sometimes be useful to know these properties, and to compare them with other paragraphs to make sure you get the paragraph labels right.

Section, Subsection, and Sub-subsections have a similar dropdown:

Here too you can remove the heading from the book’s TOC or hide it in the book.

If your paragraph is a list item, whether for a bullet list or a numbered list, you can modify the list item’s indentation level:

That’s particulalry useful if you’re working with plain paragraphs whose text content mimics a list item. Bookalope is good about recognizing such paragraphs and labeling them correctly. More importantly, once you’ve confirmed that the paragraph is indeed a list item then Bookalope automatically removes the bullet or number, thus creating a properly structured list.

If Bookalope detects an explicit page break in your original document, then it preserves that page break and displays it on the Review page. Remember that a Part Title or a Chapter Title always opens a new page, and therefore a page break before a Chapter Title is redundant and is automatically classified to be ignored and later removed.

Notice that explicit page breaks are always labeled as Ignore, and they also always show their respective page number:

As mentioned just above, a Part Title or a Chapter Title always open a new page, although here we don’t actually have heading paragraph! So, if we want to preserve this explicit page break we must add an appropriate heading paragraph after the page break—and again Bookalope forces us to ensure proper accessibiltiy by entering a meaningful heading:

Notice that we label that new paragraph with Chapter Title of “Copyright” kind, and we also remove its entry from the book’s TOC and hide the title. By doing so, our book will maintain meaningful structure without us changing the text flow that’s visible to the reader.

With respect to ebook accessibility, images need extra attention and you can manage all required details with Bookalope. Like with paragraphs, you can assign different labels to an image and thereby giving it the correct meaning:

Let’s take a closer look at these different labels:

• Image: This label is for normal images that show up as images in your book (with or without captions).
• Decorator: By marking an image as a Decorator you tell Bookalope to treat this image as a visual embellishment that has no further meaning in the context of your book. Thus, Bookalope won’t require an alternative text for that image anymore.
• Separator: Similarly to a Separator paragraph, some images are used to illustrate a narrative break. A fleuron or other ornaments are commonly used, and this option allows you to mark the image as a separator.
• Ignore: Ignores and removes the image entirely.

When you select the checkbox right of the image’s label then the toolbar at the bottom of the screen offers you options to modify your image and add more information:

You can adjust an image’s horizontal Alignment and its Scale (i.e. “small”, “medium”, or “large” image) easily with the two select buttons, and, more importantly for exporting an accessible book, you should enter an alternative text for the image. That alternative text should be a meaningful description of your image; reading apps will present that alternative text to readers who cannot see the image itself.

Note that Bookalope will alert you to missing alternative text by using a red border around the dropdown button and the text input field!

If you’d like to add a caption to the image, simply add a new paragraph above or below the image using the content editor and label that paragraph a Caption.

If you need to replace an image with a new one, then simply click on that image. Clicking on an image opens a file selector which allows you to choose a new image, either in JPG, PNG, or GIF format, and upload that new image to Bookalope.

Like paragraphs and images, you can keep tables as they are or you can set them to be ignored and removed, depending on the label you select.

Select the table’s checkbox to activate its toolbar. Then, using the First row is the table’s header and the First column is the table’s header checkboxes, you can also specify how Bookalope should treat a table’s first row and column.

And, like with images, you can add a caption text by adding a new paragraph and labeling that paragraph a Caption.

So far we’ve only talked about managing the paragraph itself, but we haven’t discussed its content yet. You may have noticed already that some paragraph text is blue, some text has a light-blue background color, or the text is printed in italic or bold font.

Bookalope wasn’t designed to be a fully featured text editor, but we do want to fix the occasional issue and often times we want to make smaller tweaks and adjustments to the text content of our book.

For that purpose, Bookalope offers a simple paragraph editor. Just click on any heading or paragraph to start editing:

You can move the cursor around within the paragraph, and edit content at will. Whenever you click outside of the edited paragraph or skip to the next one (see below) then Bookalope writes your edits to the server. This takes only a moment, though.

As you move the cursor into inner paragraph elements like emphasized text, notes, and others you will notice a Cursor Toolbox popping up right above your cursor. Currently, that toolbox contains only a single button: an Eraser that removes the element’s markup (e.g. the “Emphasis”) from the text.

A few more things you can do:

• Hit Enter anywhere in a paragraph to split the paragraph into two. If you hit Enter at the beginning/end of the current paragraph then Bookalope inserts a new and empty paragraph before/after the current one. Note that the new paragraph inherits the features of the current one, i.e. if you split a list item you will insert a new list item; if you split a simple paragraph you will insert another simple paragraph; and so on. Note also that you can’t split headings!
• Hit Shift + Enter to insert a line break.
• To merge two neighboring paragraphs, you can move the cursor to the very start of a paragraph and hit the Backspace key to merge it with its previous neighbor, or move the cursor to the very end of a paragraph and hit the Delete key to merge the next neighbor with the current paragraph.
• You can move from one editable paragraph to the next by using the cursor Down and Up keys.

Using text selections, however, we can do more with our paragraph text! Try it out: double-click on a word or select a text portion with your mouse or press the Shift key while moving the text cursor to create a text selection. The Selection Toolbox pops open and it contains a bunch of very useful buttons:

The purpose of these buttons is to add meaningful markup into the text. From left to right, the buttons do the following:

• Add a Strong Emphasis to the selected text;
• Add a normal Emphasis to the selected text;
• Add an Idiomatic Emphasis to the selected text; and
• Call Attention to the selected text.
• Turn the selected text into a Note which, when converting your book, can be exported as a footnote or an endnote.
• Add Language markup to the selected text. This option is only available if you’ve selected one or more secondary languages for this Bookflow. (Take a look at our Managing multiple languages recipe for more details.)

There is one button that shows only if you’ve selected numbers only, and that button marks up that selected number as a Page Break relating to the print book’s page:

Alas, the toolbox shows only for selections that can be wrapped safely into markup. For example, if you were to select text that partially covers a link then no toolbox shows because Bookalope won’t allow you to break apart the link’s markup.

Furthermore, buttons within the toolbox depend on the selected text. For example, if you’ve selected text inside of a Note then the Note button won’t be available because you can’t nest notes inside of notes.

Bookalope might fail to import an object that it encounters in a document. This can be, for example, a more complex nested text box in a Word file, or an unsupported image file format. If that happens, Bookalope will alert you to the problem by inserting a warning image instead:

Note that you can either label this placeholder as Ignore or you can click on it to replace it with another image.

It’s a lot to take in, but this Review page is the most involved you’ll ever get with your document using Bookalope. Once you’ve worked your way through this page you’re almost done!

At the bottom of the page, click the Confirm and Finish button to commit any changes and to tell the Bookalope server to clean up and structure your document, and to move on to the Convert page.