Creating a PeBL book from an existing eBook

Introduction

PeBL books are EPUB 3 files, which means that at their core they are HTML 5 files contained in a .zip file. See IDPF standard documentation on EPUB 3. Converting from HTML 5 to EPUB 3 is usually quite straightforward, with many tools to accomplish this at your disposal. These tools ensure that certain EPUB 3-required files are included within the .zip file (e.g., the book's "spine") to make them conformant to the EPUB 3 standard and help create a structure for the book. All of this means that once you have converted a file to HTML 5 format, from whatever file format and using whatever process, you have probably done most of the work, depending on extensions that you may need to create.

File format conversions are always full of unexpected challenges and labor-intensive details to address, and PeBL is no different. Finding a 100% automation solution to the conversion process is probably not realistic; you should plan on multiple iterations of manual input to arrive at a product that looks, feels, and operates as intended.

A very common scenario is to have an existing eBook or PDF document that you want to convert to PeBL. The conversion first involves converting to ePUB 3. This process depends on the starting point, as described in the following sections and shown in the diagram below. The final step is to optimize from EPUB 3 to PeBL; we use the word "optimize" here rather than "convert", since PeBL books are already EPUB 3 conformant. The optimization process merely adds extra functionality. Each production pathway described below is numbered, referring to the numbers on the diagram. The EPUB to PeBL optimization process is covered in a separate section after the conversion to EPUB sections.

Step 1: Export to EPUB3
Using PDF to EPUB 3 conversion pathway

Production pathway #1 in the diagram

Using Google Docs conversion pathway
  1. Upload PDF to Google Drive in Google Chrome browser.
  2. Install PDF to gDoc add-on to Chrome
  3. Convert PDF to Google Doc.
  4. Download Google Doc as EPUB 3 (using File>Download as>EPUB Publication).

Pros

  • Fast
  • Creates reflowable text, a requirement for PeBL
  • Once you have converted PDF to Google Doc, a work team can access and edit

Cons

  • Images need to be manually inserted
  • Table of Contents (TOC) text shows up, but without links. No TOC navigation menu.
  • Bullet lists convert poorly. Indents are lost.
Using PDF to HTML conversion pathway

Production pathway #2 in the diagram

  1. Open PDF in a PDF to HTML converter (Adobe Acrobat Pro recommended) and Export to a single HTML page.
  2. Open HTML file(s) in HTML to EPUB 3 converter. This is not complex software hence there are many of these. An open source one can be found here.
  3. Export to EPUB 3.

Pros

  • More control over final output (Look and function)
  • Builds proper TOC (depending on software used)
  • Can append CSS style sheets and JavaScript libraries
  • Opportunity to add PEBL extension shortcodes

Cons

  • A complicated process with many manual steps
  • If using InDesign, significant software cost and steep learning curve
Using PDF to EPUB conversion pathway

Production pathway #3 in the diagram

  1. Open PDF in a desktop publishing program (Adobe InDesign recommended).
  2. Make any changes desired to the content.
  3. Export as EPUB 3. There are many settings available to control the output.

Pros

  • More control over final output (Look and function)
  • Simpler and quicker process than other PDF conversion pathways
  • Builds proper TOC
  • Can append CSS style sheets and JavaScript libraries
  • Opportunity to add PEBL extension shortcodes

Cons

  • If using InDesign, significant software cost and steep learning curve
  • Tradeoff of control (see pro above) for complexity in having control over final output
Using word processing to EPUB conversion pathway

Production pathway #4 in the diagram

  1. Open word processing file (MS Word recommended).
  2. Import into desktop publishing program (InDesign recommended).
  3. Export as EPUB 3. Settings are available to control the output. You can create the Table of Contents at this point.

Pros

  • More control over final output (Look and function)
  • Simpler and quicker process than other PDF conversion pathways
  • Builds proper TOC
  • Can append CSS style sheets and JavaScript libraries
  • Opportunity to add PEBL extension shortcodes

Cons

  • If using InDesign, significant software cost and steep learning curve
  • Tradeoff of control (see PRO above) for authoring complexity
Using word processing to HTML conversion pathway

Production pathway #5 in the diagram

  1. Open word processing file(s) in text to EPUB 3 converter. Recommend Word to EPUB Converter (if using Word)
  2. Export to EPUB 3.

Pros

  • It is a likely scenario that you will encounter a word processing file as source file for the book. If this is the case, you can reliably design a stable production process for this.
  • Requires minimal software

Cons

  • Will likely need to do a lot of tweaking, since export from word processing programs to EPUB (which is essentially HTML5) is not always clean.
Using EPUB pathway

Production pathway #6 in the diagram (i.e., presumes that you already have an EPUB 3 book)

  1. Open EPUB 3 file in a text editor.
  2. Make any authoring changes needed.
  3. Resave as an EPUB 3

Pros

  • Extremely fast, but can only do this if your source file is EPUB 3

Cons

  • None
Step 2: Optimize for PeBL
  1. Rename .epub file extension to .zip.
  2. Unzip the book (i.e., extract to a regular folder).
  3. Open HTML pages in a script editor (Notepad++, Brackets, etc.).
  4. Move any JavaScript to the bottom of each page so it loads last.
  5. Insert PEBL extensions and markup by doing the following:
    1. Manual Process
      1. Step 1: Download and unzip the PEBL extension starter package. This will contain:
        • Extension script template
        • "PEBL" folder with JS and CSS files.
      2. Step 2: Open the "OEBPS" folder
        1. Create a "containers" folder in OEBPS
      3. Step 3: Add PEBL folder
        1. Create a "components" folder inside of OEBPS
        2. Copy the downloaded "pebl" folder into your book's "OEBPS" folder.
      4. Step 4: Add scripts to each HTML page
        • Do the following to each HTML file in the "OEBPS" folder:
          1. Open HTML file in a text editor like Notepad or Notepad++.
          2. Copy and paste the pebl scripts into the head
          3. Copy and paste any extension scripts into the body content. Insert each widget code snippet where you would like a specific widget to appear. Replace the widget values with your own content.
          4. Insert path to each js, css, and support file added to the manifest inside content.opf
      5. Step 5: Repackage as EPUB
        • Zip the folder and rename it as a .epub book.
      6. Optional: Extension Customization
        1. The PEBL extension files are basic starter templates designed to be modified as needed.
        2. Before copying in the PEBL folder in Step 3, above, a web designer can rebrand extension files to match the looks and feel of your content. This requires knowledge of cascading style sheets (CSS).
        3. Similarly, to change the default text used in some of the extensions, a web developer should edit the Javascript files in the PEBL folder.
    2. Automated Process using shortcodes. Note: This method could also be accomplished with a custom online / local webapp, or perhaps with a .BAT file if you are inclined to expend the effort to build such.
      1. Step 1: Add Extension Markup
        1. Finalize the content in the original source file
        2. Open the original eBook source file in the program that authored it, such as InDesign, MS Word, or other.
        3. Insert extension shortcodes where ever you want an extension to appear in the book. A list of shortcodes is available here.
      2. Step 2: Export the file using your normal EPUB process.