BB eBooks Banner

Documentation for the BB Design Pad

Purpose

The BB Design Pad was written by the team at BB eBooks to make many of the repetitive tasks of eBook development easier. It is not a one-click publishing solution, but rather a handy tool to help you in your workflow. The BB Design Pad requires that the user have a base-level knowledge of HTML. Written in JavaScript with the jQuery library, this application is used in-house at BB eBooks to aid in much of the workflow of eBook development and design. It relies heavily on the use of regular expressions, and developers are encouraged to submit improvements to the code or report any bugs. You are more than welcome to use this application to design eBooks for commercial purposes. If you have suggestions for new functionality you would like to see, please drop us a line, and we'll see what we can do.

Basic Instructions

To use the BB Design Pad, simply copy and paste some of the text you are converting to HTML into the Design Area, start using some of the functions in the Control Panel discussed below, and then copy the HTML from the design area into the text editor of your choice. BB Design Pad has been tested on Chrome, Firefox, and IE 9—older browsers may have issues. If you make a mistake, just press Ctrl-Z to undo. It goes without say that you should be saving backups of your content often during your workflow. BB Design Pad has no server-side features, so everything lives in your browser.

Caution: The BB Design Pad assumes your HTML markup uses double quotes for attributes (e.g. <a href="someurl">) and not single quotes (e.g. <a href='someurl'>). We’re advocates of using double quotes for HTML/XML/CSS and single quotes for PHP/JavaScript. We hope that doesn't cause any frustration.

Sample Work Flow

Every eBook is different, but a suggested workflow for eBook design would be as follows:

  1. Copy content from your manuscript into the Design Area
  2. Nuke the whitespace (i.e. delete tabs, extra blank lines, double spaces, etc.)
  3. Add the Fancy Quotes (i.e. the curly quotes and apostrophes)
  4. Convert the dangerous entities into HTML Entity Names (i.e. &, >, and <)
  5. Adjust white space and line breaks so that each paragraph of content is on one long line
  6. Wrap paragraph tags on every paragraph
  7. Wrap span tags on in-line text (i.e. bold, italics, etc.)
  8. Add your images with the img element
  9. Wrap hx tags on your headings, replacing the p elements
  10. Add any external or internal hyperlinks
  11. Wrap <div id="xxx"> tags around element you want to anchor for internal hyperlinks
  12. Add a standard XHTML 1.1 header and footer
  13. Validate XHTML at the W3C Validator
  14. Copy the processed HTML back to your text editor for EPUB conversion

Block Element Markup Help

Use this function to wrap opening and closing tags around an entire line of text (such as p, hx, and li elements). You can type in id or class attributes if you want them to be automatically added. Leave the id and class fields blank if you do not wish them to be added. The tags are added at the beginning and ending of the line based on your cursor position in the Design Area. A hotkey is bound to this function for rapid usage.

In-Line Element Markup Help

Use this function when wrapping in-line elements around content (such as <span> and <a>). The tags are inserted based on what content you highlight in the Design Area. If no content is highlighted, it will insert the opening and closing tag based on your cursor position. It is permissible to select content across multiple lines (useful for <div> tags). Similar to the block elements, you can add in attributes and a hotkey is bound to this function for rapid usage.

Note: The BB Design Pad wraps bold, italics, and underlined text using a span tags with the b, i, u class respectively. This is due to odd rendering results across eReading devices when using the standard <b>, <i>, and <u> elements. Simply add the necessary styles into your CSS.

Self-Closing Element Markup Help

This function is for inserting common self-closing tags (such as <hr /> for horizontal lines and <br /> for line breaks). Please note that the self-closing /> is required for XHTML validation. Insertion of the self-closing element is based on your cursor position in the Design Area. A hotkey is bound to this function for rapid usage.

Add Attributes Help

This portion of the control panel is to be used in conjunction with the markup adding functions. Type text into the fields if you want the attributes class, id, or href to be included as you markup your content in the Design Area. The BB Design Pad will not add attributes if these fields are left blank. For your convenience you can add classes to the Custom Class dropdown for repeated entries.

Stripping Operations Help

This function simply strips off the tags at the beginning and end of the line based on your cursor position in the Design Area. A hotkey is bound to this function for rapid usage.

Add Image Markup Help

Adding images inserts the self-closing <img /> element into the Design Area. Please note that EPUB validation requires the alt attribute. If none is specified, the BB Design Pad will insert a blank alt="" into the markup, which is perfectly valid. It is strongly recommended that you specify the height and width attributes in pixels to avoid unpredictable and heinous re-sizing issues on the Kindle.

Entity Operations Help

Entity Operations perform manipulation on all content in the Design Area. Please use with caution.

  • Replace Dangerous Entities: This function will convert the three special characters that will cause your HTML to break if they are not escaped properly in the content— <, >, and &. This function should be used before adding any HTML markup.
  • Replace UTF-8 with HTML Entities: This will replace special characters outside of the ASCII character set (e.g. Ô, ú, €, etc.) with the corresponding HTML Entity Name Codes. Please note that this is not really necessary, because modern eReading devices are usually capable of rendering UTF-8 characters properly. This function is only necessary if you plan on using Calibre to convert your eBook.
  • Add Fancy Quotes: This function turns the straight up-and-down quotes and apostrophes (i.e. " ') to the fancy/curled quotes and apostrophes (i.e. “quote” and ‘quote’). The function is “smart”, meaning it will try to properly alter the opening and closing quote on dialogue. It will also use the proper ‘ for words like ‘tis, ‘twas, ‘cuz, and ‘em. There is a major deficiency in Microsoft Word, which usually makes the single quote go the wrong way (i.e. ’tis), and this function helps rectify the situation. Also, this function will not break HTML markup by adding fancy quotes inside elements, which require the straight up and down quotes. Speaking from a programmer's point of view, this was a very complicated function to write, so please report any bugs or tips for improvement.
  • Add Fancy Dashes and Ellipses:This function converts double-hypens (--) into em dashes (—), and space-hyphen-space sequences into " – " (note: the proper en dash). It also converts triple periods (...) into the proper ellipses (…).

Whitespace Operations Help

Unnecessary whitespace is a very common problem when designing eBooks from a source manuscript that was written in word processing software like Microsoft Word or Open Office. High-quality HTML markup and content should have no unnecessary whitespace to ensure proper rendering by eReading devices and in the interest of lower file sizes. These functions manipulate all content in the Design Area, so proceed with caution.

  • Whitespace Nuke: This deletes blank lines, tabs, extra spaces, and trims every line of content as described below.
  • Delete Blank Lines: This function deletes any line that is blank. Proper eBook design should not use blank lines as a way to add white space between content. Use CSS instead.
  • Delete Tabs: Due to differing standards of tab rendering across various eReading devices, all tabs should be removed from eBook content.
  • Delete Extra Spaces: You know how some people still use two spaces after periods like it was 1924 or something? This function makes any sequential space of two or more reduce to a single space.
  • Trim Lines: This function strips the leading and trailing whitespace off of every line. This is a very common problem for users of Microsoft Word, which always seems to add that extra space at the end of a paragraph.
  • Delete Extra Carriage Returns: Use caution with this function, because it is experimental as of right now. It was designed to help in the tidying up of Project Gutenberg raw text files into eBooks. It attempts to convert paragraphs into one long line that do not have blank lines above or below it. This function can have unpredictable results. It may be handy when trying to delete line breaks within paragraphs on PDF rips. Developers are encouraged to submit feedback on how this can help their development needs.

HTML Bulk Operations Help

These functions help work with the entire document rather than individual markup. Please use caution, as these operations will alter everything in your content.

  • Wrap Paragraph Tags Every Line: This function wraps an opening <p> tag and closing </p> tag across each line in the content. It may be beneficial to use this function first prior to adding any HTML, and then backtrack to replace certain lines of content with heading tags or markup with distinct classes.
  • Strip All Tags: This function removes all HTML markup from your content. This is particularly useful when working with the disastrous markup that InDesign creates during the HTML export stage of your workflow. The way the function works is that anything between < and > is deleted (including the < and >).
  • Add Standard HTML Head: This function adds a standard UTF-8, XHTML 1.1 header and footer to your content. You can type in the CSS source file and document title in the fields of the Control Panel if you like (or just add it in later).

HTML Special Operations Help

These functions are designed for special tasks that are easy to script, but cumbersome to do manually. Suggestions for new operations are welcome.

  • Check for Duplicate ids: This function verifies that you do not have any duplicate ids, which is big W3C no-no. If you do have duplicates, a dialog box will indicate which ones are duplicates. It should be noted that the W3C validator and EPUB validator will catch any duplicate ids as well.
  • Check for Unique Classes: This function identifies all the classes you use in your content, which is very handy when crafting your CSS file.
  • Wrap div id= Tags: This function is designed for constructing internal hyperlink anchors for the Table of Contents. It takes as input an element (e.g. h2) or an element and class (e.g. h3 class="sectionbreak") that you type in the Control Panel. It will attempt to go through your entire content and wrap a <div id="uniqueid">…</div> element around each line that has the specified input. The values of each id attribute will be unique. The reason for the id attribute being outside the target markup is due to the Kindle blowing out the CSS when the id attribute is within the target markup. This is another function that was challenging to program in JavaScript, so please report any bugs or ways to improve functionality.
  • Apply iPad Span Fix: The iBooks app has a bug whereby some content styled with text-align: center; or text-align: right; is not properly rendered (usually getting aligned to the left of the viewport). As a hack, you can add in a <span> element in-line with the content. In your CSS, you just need to style your span element that gets added with the text-align property that you desire. This function takes as input a class, and goes through your entire content to wrap the <span class="ipadcenterfix"> </span> around the content but inside the HTML markup.
  • Fix Footnotes Sequentially: This function takes a class as an input and attempts to change the content within all <a class="inputclass"> </a> elements in the document to have a sequential numbered order (i.e. 1, 2, 3, etc.) This is useful for ensuring footnotes are numbered correctly.