Robert Desprez Communications

Controlling alignment and orphans in an EPUB file

by 4 Comments

This blog entry explains some tips and tricks on how to con­trol align­ment and wid­ows and orphans in an EPUB file.

Some basics

An EPUB doc­u­ment is a zip file with the .epub exten­sion. EPUB files can be read using e‑reader soft­ware on many devices includ­ing the iPad, iPhone, PCs, and smart­phones run­ning on Android.

For tech­ni­cal writ­ers, I believe EPUB files are one of the tech­nolo­gies to watch. The iBooks book­store sells its e‑books in an EPUB file for­mat. With tablets and smart­phones out­selling PCs, users are increas­ing­ly read­ing content—including tech­ni­cal communications—on these devices. Help Author­ing Tools also make it easy to cre­ate EPUB files.

Controlling alignment

In your Help Author­ing Tool, you can spec­i­fy your text align­ment. Most of the time, tech­ni­cal writ­ers left-align their con­tent. But if you are view­ing your EPUB file on an iPad, it over­rides your align­ment set­tings and presents the con­tent as justified.

Here’s an exam­ple of jus­ti­fied align­ment on an iPad:

EPUB file shown on an iPad

For­tu­nate­ly, you can over­ride the iPad settings.

The eas­i­est way to do this is by ask­ing users to make a con­fig­u­ra­tion change on the iPad. As this is a pret­ty straight­for­ward change, I think it’s rea­son­able to ask users to fol­low a few steps.

To change the jus­ti­fi­ca­tion set­tings on your iPad:

  1. Go to Set­tings on your iPad.
  2. Go under your Apps set­tings and click iBooks.

Settings screen on an iPad

  1. Turn off Full Jus­ti­fi­ca­tion to over­ride the settings.
  2. Open an EPUB file in iBooks.

Your con­tent is then aligned the way you designed it.

Controlling widows and orphans

In some e‑readers, you can con­trol wid­ows and orphans. A wid­ow is the last line of a para­graph, marooned on one side of a page break. Here is an example:

Example of widow in an EPUB file

An orphan is a word, part of a word, or very short line that appears by itself at the end of a paragraph.

Using the Cas­cad­ing Style Sheet (CSS) in your EPUB project, you can con­trol wid­ows and orphans in Adobe Dig­i­tal Edi­tions and Nook. As of May 2013, you can­not con­trol wid­ows and orphans in iBooks.

Unzipping an EPUB

Com­plete the fol­low­ing steps to unzip your EPUB file: 

  1. Locate your EPUB file.
  2. Change the .epub exten­sion to .zip.
  3. Unzip the con­tents of the folder.
  4. Dou­ble-click the OEBPS fold­er (“OEBPS” stands for Open eBook Pub­li­ca­tion Structure).

Structure of EPUB

  1. Locate the default.css file. This is your CSS file.

Editing your CSS

Using a text edi­tor, type the fol­low­ing code that spec­i­fies the for­mat­ting for wid­ows and orphans.

widows_orphans_CSS

For the para­graph tag (“p”), the high­light­ed exam­ple ensures that at least two lines of con­tent appear togeth­er at the bot­tom or top of a page so that you don’t have sin­gle-line wid­ows and orphans. Of course, you can change the val­ue to what­ev­er you prefer.

Next steps

After you make changes to the CSS, re-zip the EPUB project, rename so it uses an .epub exten­sion, and test it on all the dif­fer­ent e‑readers that your users may be using. Dif­fer­ent e‑readers may ren­der your EPUB file dif­fer­ent­ly so test­ing is vital.

I am speak­ing about for­mat­ting EPUB files at the Cana­da West Chap­ter of the STC on July 16th, 2013.

Controlling page breaks in an EPUB file

by 5 Comments

New­er Help Author­ing Tools such as Mad­cap Flare or Adobe Robo­Help will quick­ly cre­ate an EPUB file that includes a title page, table of con­tents, and the top­ics that you authored. If you don’t mind open­ing the EPUB file after author­ing it in a Help Author­ing Tool, edit­ing the Cas­cad­ing Style Sheet (CSS), you can gain a lot more con­trol over the for­mat­ting of the file.

In this blog entry, I’ll briefly explain how to unzip the EPUB file and edit the CSS so that you gain more con­trol over page breaks. In March, I spoke about for­mat­ting EPUB files using a CSS at the Writ­er­sUA conference.

A few basics

An EPUB doc­u­ment is a zip file with the .epub exten­sion. EPUB files can be read using e‑reader soft­ware on a myr­i­ad of devices includ­ing the iPad, iPhone, PCs, and smart­phones run­ning on Android.

For tech­ni­cal writ­ers, I believe EPUB files are one of the tech­nolo­gies to watch. The iBooks book­store sells its ebooks in an EPUB file for­mat. With tablets and smart­phones fore­cast to out­sell PCs in the future, users will increas­ing­ly be read­ing content—including tech­ni­cal communications—on these devices.

One of the key advan­tages of an EPUB file is its abil­i­ty to reflow on dif­fer­ent devices.  The fol­low­ing image shows how an EPUB file appears on an iPad:

EPUB file shown on an iPad

The next screen shot shows how the same file appears on an iPhone:

EPUB on an iPhone

In con­trast, a PDF file may look beau­ti­ful on your 24-inch mon­i­tor at home but is dif­fi­cult to read on your smartphone.

Controlling page breaks inside RoboHelp

If you work as a tech­ni­cal com­mu­ni­ca­tor, you prob­a­bly use a Help Author­ing Tool, such as Robo­Help or Mad­cap Flare. These tools pro­vide a lot of the “heavy lift­ing” for you: they cre­ate the title page, a table of con­tents, and the top­ics them­selves. You can use them to con­trol some basic page breaks. But if more con­trol is need­ed, edit your CSS.

Unzipping an EPUB

Com­plete the fol­low­ing steps to unzip your EPUB file: 

  1. Locate your EPUB file.
  2. Change the .epub exten­sion to .zip.
  3. Unzip the con­tents of the folder.
  4. Dou­ble-click the OEBPS fold­er (“OEBPS” stands for Open eBook Pub­li­ca­tion Structure).

  1. Locate the default.css file. This is your CSS file.

Using page breaks

Inside the CSS file add the fol­low­ing code using a text editor:

h2 {

page-break-before: always;           

}

In the CSS, it might appear like the fol­low­ing image:

Changing your CSS to force page breaks

 

This first entry adds a page break before every instance of a head­ing 2. This might be use­ful if you want to insert a page break before a chap­ter title.

Here are some oth­er options to consider:

  • H3 {page-break-before: avoid;} This entry pre­vents an ele­ment (in this case, a heading3) to begin on a new page, unless absolute­ly nec­es­sary. You might want to use this code to try and ensure that con­tent is grouped together.
  • H3 {page-break-after: avoid;} This entry dis­cour­ages a page break after an item.
  • H3 {page-break-inside: avoid} This pre­vents an ele­ment such as a table or long list from being divid­ed by a page-break. Keep in mind that if your table or list spans mul­ti­ple pages, the e‑reader needs to cre­ate a break some­where.

Next steps

After you make changes to the CSS, re-zip the EPUB project, rename so it uses an .epub exten­sion, and test it on all the dif­fer­ent e‑readers that your users may be using. I’ve installed Adobe Dig­i­tal Edi­tions on my com­put­er and iBooks for the iPhone and iPad. Dif­fer­ent e‑readers may ren­der your EPUB file dif­fer­ent­ly so test­ing is vital.

In future blog entries, I’ll explain how to con­trol text align­ment, wid­ows and orphans, and fonts.

Additional resources

EPUB Straight to the Point
by Eliz­a­beth Castro

Cas­tro’s web site on for­mat­ting EPUB files:
http://www.pigsgourdsandwikis.com

 

 

Tripane help and PDF files: past their prime?

by 18 Comments

Web­Help gives me flash­backs from the 1990s. A client of mine recent­ly looked at a Web­Help project and said it was not “sexy enough.” I had a hard time disagreeing.

Tri­pane help is like the K‑car (I know, I am dat­ing myself here): reli­able but a rel­ic of anoth­er decade. The table of con­tents and skin look like they belong in a museum.

Not the most attrac­tive vehi­cle every made. But it was reliable.

 

I sub­se­quent­ly cre­at­ed a ver­sion of brows­er-based Adobe AIR help.  It’s much more mod­ern look­ing. But it’s still fun­da­men­tal­ly an old tech­nol­o­gy and par­a­digm. Sure, there’s the sleek exte­ri­or and the more mod­ern pre­sen­ta­tion of the con­tent but there’s still the tried-and-true ves­tiges: the table of con­tents, index (if you still cre­ate one), search, and con­tent in the right-hand pane.

Oth­er writ­ers have cri­tiqued the tri­pane online help too. Tech­ni­cal com­mu­ni­ca­tor and blog­ger Tom John­son wrote in his blog:

“Although you can tweak its styles here and there, you can’t make tri­pane help look like a reg­u­lar web­site. It just doesn’t fit in with any­thing on the web that you find post-2005. The more we move into the future of the web, the greater the divide grows between tech comm and inter­ac­tion design. That divide wor­ries me. When peo­ple see a tri­pane help site open up, it imme­di­ate­ly sig­nals a sense of outdatedness.”

Ben Min­son, anoth­er tech­ni­cal com­mu­ni­ca­tor, wrote a blog entry about why he does not like tri­pane help. 

Oth­er than the out­dat­ed look, my main issue with tri­pane help is that there are ver­sions of it that do not play well with iPads, iPhones, and most smartphones—all of the devices that one could argue are the future of com­put­ing. When I ran Web­Help on an iPad and iPhone, it was almost too slow to be con­sid­ered usable.

PDF files

PDFs are anoth­er old-style tech­nol­o­gy that writ­ers still churn out (myself includ­ed). I don’t think PDFs are quite yet on life-sup­port but I am inter­est­ed in explor­ing alter­na­tives. I plan to attend Bob Boiko’s talk about “Life after PDF” at the upcom­ing Writ­er­sUA con­fer­ence in March 2013.

Cre­at­ing PDFs is a snap for authors. But when the doc­u­ments are long, they risk being mono­lith­ic and unwieldy for users. For instance, imag­ine hav­ing to read a 50- or 100-page PDF on a smart­phone or even tablet. Painful.

To be fair here, help author­ing ven­dors have inno­vat­ed. We can cre­ate EPUB files, “mobile friend­ly” ver­sions of help, and HTML5 files. But the endur­ing pop­u­lar­i­ty of old tech­nolo­gies like tri­pane help and PDFs makes me won­der whether it’s time to ditch the famil­iar par­a­digms and embrace new­er tech­nolo­gies that look like they belong in this century.

HTML5 or EPUB: What is best for technical documentation?

by 2 Comments

When you cre­ate doc­u­men­ta­tion for tablets or smart­phones, should you cre­ate an EPUB file or an HTML5 file?  As usu­al, it depends on your audience.

What is an EPUB file and how does it differ from HTML5?

An EPUB doc­u­ment is an XML file that is zipped file with the .epub exten­sion. You cre­ate EPUB files using Microsoft Word, Adobe InDe­sign, and help author­ing tools such as Mad­Cap Flare and Adobe Robo­Help. This enables users to read the file in Adobe Dig­i­tal Edi­tions, or iBooks, Apple’s free e‑reader for iOS.

HTML5 is not soft­ware that has to be installed but rather a new ver­sion of HTML that appears in your brows­er. It’s a work in progress. Safari and Chrome pro­vide good sup­port for HTML5 where­as Inter­net Explor­er has been slow to sup­port it.

Why would you create an EPUB file?

The main advan­tage of an EPUB file is that is changes the flow of the text, based on the device you have. If your users are view­ing your con­tent on an iPhone, the pre­sen­ta­tion of the con­tent appears dif­fer­ent­ly than if it is viewed on a PC or an iPad. For exam­ple, see the fol­low­ing two screen shots:

EPUB file shown on an iPad
EPUB file shown on an iPad
EPUB on an iPhone
EPUB on an iPhone

With EPUB files, you can also choose the fixed lay­out option as well. Fixed lay­out EPUB files are per­fect for cook­books, illus­trat­ed books, and some text­books. With the fixed lay­out func­tion­al­i­ty you can embed fonts, choose par­tic­u­lar text sizes, and pre­cise­ly posi­tion images. Basi­cal­ly, fixed lay­out options give con­tent cre­ators greater con­trol over the pre­sen­ta­tion of a doc­u­ment. For the tech­ni­cal details of a fixed lay­out option for EPUB, see the Fixed Lay­out Doc­u­ment sec­tion of the Inter­na­tion­al Dig­i­tal Pub­lish­ing Forum web site.

One dis­ad­van­tage of an EPUB file is that it may require your users to install soft­ware such as iBooks, which is not pre-installed on iPads or iPhones.

Why would you create an HTML5 file?

You prob­a­bly want to con­sid­er cre­at­ing an HTML5 file when your users are run­ning browsers (such as Safari or Chrome) that sup­port it. If you are con­fi­dent that your users are using one of these browsers, it’s eas­i­er for them to view your work. There is no extra app to install.

Anoth­er advan­tage of HTML5 is that if your user assis­tance is avail­able in a brows­er, any revi­sions to the con­tent will imme­di­ate­ly be seen by your users. With an EPUB file, there’s the addi­tion­al work of cre­at­ing the lat­est EPUB file and dis­trib­ut­ing it again to your users.

HTML5 also sup­ports offline support—meaning that you can view the con­tent when you have an Inter­net con­nec­tion, your brows­er caches the con­tent, and then you can view the same con­tent when you are offline. This may be per­fect for users who need user assis­tance but do not have a reli­able net­work connection.

Other Resources

* What is EPUB 3? by Matt Gar­rish ( a free O’Reil­ly book).

* Eliz­a­beth Castro’s book EPUB Straight to the Point. 

* Test your brows­er for HTML5 sup­port

*A free online book: Dive into HTML5 by Mark Pilgrim.

Generating iPad content using RoboHelp 10

by 6 Comments

Robo­Help 10 makes it much eas­i­er to gen­er­ate EPUB files, the most wide­ly accept­ed file for­mat for e‑books. EPUB files can be read on an array of devices includ­ing the iPad, iPhone, and smart­phones run­ning on Android.

What is an EPUB file?

An EPUB doc­u­ment is a zip file with the .epub exten­sion. You cre­ate EPUB files using Microsoft Word, Adobe InDe­sign, and help author­ing tools such as Mad­cap Flare and Adobe Robo­Help. This blog entry explains the major steps of cre­at­ing EPUB files using Robo­Help 10, which was released this summer.

Advantages of EPUB

* Easy to pro­duce. Cre­at­ing EPUB files are easy to pro­duce with new­er author­ing tools.

* EPUB con­tent reflows. In Eliz­a­beth Cas­tro’s book EPUB Straight to the Point, she writes: “If you’re read­ing it (an EPUB file) on an iPhone, the width of the page is a fair bit small­er than if you’re read­ing it on an iPad, or on some oth­er read­er. The beau­ty of EPUB is that it flows the text to fit what­ev­er screen it’s on.” In con­trast, the pre­sen­ta­tion of a PDF file stays large­ly sta­t­ic, regard­less if you’re using a PC, a Mac, an iPhone, or an iPad.

* Can be viewed offline. Once you down­load a EPUB file, you can view it with­out an Inter­net connection.

Disadvantages of EPUB

* Nav­i­ga­tion is not ide­al. The EPUB file for­mat sup­ports a table of con­tents at the start of the EPUB file. But if you’re want­i­ng to skim the table of con­tents, you need to jump to the front of the doc­u­ment. A tra­di­tion­al online help sys­tem always dis­plays the table of con­tents, mak­ing it easy to jump to anoth­er topic.

* Best suit­ed to lin­ear read­ing. The EPUB file for­mat is fine for tra­di­tion­al books in which you read lin­ear­ly. Users of tech­ni­cal doc­u­ments do not read this way. They skip from top­ic to top­ic in an effort to find the answers they need.

* Extra app required. iBooks, Apple’s e‑reader app, is not pre-installed on the iPad. Users first need to down­load the free app before they can read EPUB files. Not a huge deal but it is anoth­er step for users.

Writing EPUB content in RoboHelp

I assume that you are famil­iar with Robo­Help so I don’t try to explain every option and con­cept in the soft­ware. I focus on what’s new in Robo­Help 10 and how it can eas­i­ly cre­ate EPUB files.

Step 1: Write your content in RoboHelp

Write your doc­u­men­ta­tion in Robo­Help as you nor­mal­ly would.

Step 2: Generate your content as an EPUB format

  1. In the Sin­gle Source Lay­outs sec­tion, dou­ble-click eBook.

Step 3: Select your options

General section
  1. In the eBook Set­tings dia­log box, click Gen­er­al.
  2. In the eBook For­mats sec­tion, select the EPUB 3 check box. You can also gen­er­ate an out­put file that is com­pat­i­ble with the Kindle.
  3. If need­ed, make changes to your out­put fold­er and file name.
  4. In the Options sec­tion, you may want to select the Val­i­date EPUB 3 Out­put check box. An open source tool called epub­check val­i­dates your EPUB file.

Content section
  1. In the eBook Set­tings dia­log box, click Con­tent.
  2. In the Table of Con­tents drop-down list, select the table of con­tents that you cre­at­ed in RoboHelp.
  3. In the Index and Glos­sary drop-down lists, select an index and glos­sary if you set them up in RoboHelp.
  4. In the Con­di­tion­al Build Expres­sion sec­tion, change your con­di­tion­al text set­tings if need­ed. With con­di­tion­al text, you can tag cer­tain sec­tions of your con­tent for dif­fer­ent audi­ences or deliverables.
Meta Information section
  1. In the eBook Set­tings dia­log box, click Meta Infor­ma­tion.
  2. In the Title box, type the name of the EPUB file.
  3. In the Author(s) box, type the name of the author. This may be your name or the name of your department.
  4. In the Publisher(s) box, type your com­pa­ny’s name.
  5. In the Descrip­tion box, type a sen­tence or two that pro­vides a good sum­ma­ry of your document.
  6. In the Cov­er Image sec­tion, select the image you’d like to be on the cov­er on your EPUB file.
  7. Click Save and Generate.

Step 4: Download Adobe Digital Editions

Adobe Dig­i­tal Edi­tions free soft­ware offers a way to view and man­age EPUB files and oth­er dig­i­tal pub­li­ca­tions. I think of it as soft­ware to quick­ly test your gen­er­at­ed file before trans­fer­ring the file to an iPad.

This step is option­al but could save you time if you intend to gen­er­ate mul­ti­ple EPUB files. When Robo­Help fin­ish­es gen­er­at­ing the file and you click View Result, you can imme­di­ate­ly view your EPUB file in Adobe Dig­i­tal Editions.

If there’s a prob­lem with the file, you can fix the issue and then quick­ly regen­er­ate the content.

Step 5: Transfer the file to an iPad

After you have gen­er­at­ed the con­tent, Robo­Help cre­ates the EPUB file in a fold­er that you specified.

To syn­chro­nize the file to an iPad, ensure you have iTunes installed on your com­put­er. In addi­tion, you need to install iBooks, a free e‑reader on your iPad.

  1. Con­nect your iPad to your computer.
  2. In iTunes, click the Sum­ma­ry but­ton and select the Man­u­al­ly man­age music and videos check box.
  3. Locate the gen­er­at­ed EPUB file on your computer.
  4. Drag it to your device in iTunes.

iTunes syn­chro­nizes the file to your iPad.

Step 6: View the file in iBooks

  1. Open iBooks.
  2. In the Library in iBooks, tap the file you just transferred.
    The EPUB file appears. Here is an exam­ple of an EPUB file that is dis­play­ing in iBooks.

If you want to know more about EPUB files, check out Eliz­a­beth Cas­tro’s book EPUB Straight to the Point. 

Recent Blog Posts

About Me

Robert Desprez I have worked as a Vancouver technical writer for more than 20 years, working at Kodak, Boeing, Teck Resources, and FortisBC. In addition, I have worked as a writing instructor at Simon Fraser University in Vancouver.

Contact Me

Robert Desprez Com­mu­ni­ca­tions Inc.
North Van­cou­ver, British Columbia
Canada
Phone: 604–836-4290