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.

How RoboHelp’s search could be better

by 5 Comments

Almost every­one on the Inter­net uses search. A study by Pew Inter­net last year found that 92 per­cent of adults who are online use search engines to find infor­ma­tion on the Web.

I can­not imag­ine life with­out search. When I have a prob­lem with some­thing I own, such as a DVD play­er, I might look up the prob­lem in the print­ed user guide (if I still have it!), go to the manufacturer’s web site, or just type the name and mod­el of the DVD play­er in Google’s search field. From my expe­ri­ence, Google often pro­vides results that are as use­ful as the manufacturer’s sup­port web site.

Users still search for help even on the iPad, which is fre­quent­ly her­ald­ed as “so intu­itive.”  On the iPhone, I fre­quent­ly use its search fea­ture as I try to find an elu­sive email.

Two weeks ago, I attend­ed an Adobe webi­nar called “Using new Robo­Help 10 fea­tures to make con­tent more search­able.” This blog post gives my impres­sions of RoboHelp’s search engine.

External content search is a welcome addition

Adobe intro­duced exter­nal con­tent search in Robo­Help. This fea­ture enables you to define the key­words that users might type in the Search field and then direct them to an exter­nal web site. For exam­ple, you can set up your help so that when a user types “sup­port web site” in the Search field, the search engine dis­plays an exter­nal URL that you specify.

In the fol­low­ing screen cap­ture, in the Search Terms field, I’ve spec­i­fied the terms “sup­port, ACME sup­port, tech­ni­cal sup­port.” In the help, if a user types one or more of these terms, Robo­Help dis­plays the ACME sup­port web site.

Anoth­er nice fea­ture is that you can define these terms and then export them to oth­er Robo­Help projects, if needed.

How RoboHelp’s search could be better

RoboHelp’s search could be bet­ter by dis­play­ing key­words in the Search engine field.

When you type spe­cif­ic key­words in Google’s search field, the web site dis­plays a list of sug­gest­ed terms as you type the query. This solu­tion helps users because they may type terms incor­rect­ly or may not even be sure how to phrase their queries in a search field. Google dis­plays sug­gest­ed terms and dis­plays rel­e­vant web sites before I even fin­ish typing.

In Robo­Help, users are unfor­tu­nate­ly left on their own when it comes to craft­ing a good search.

Faceted search

Anoth­er wel­come addi­tion would be faceted search. Com­pa­nies, such as Dell, have used this tech­nique for some time. On Dell’s web site you can search for a lap­top or desk­top com­put­er. Alter­na­tive­ly, you can use the fil­ters to help you search by prod­uct cat­e­go­ry, proces­sor, screen size, weight, and so on.

For users, this helps stream­line their choic­es. In an online help sys­tem, users could use faceted search to dis­play con­tent by top­ic type (con­cepts, pro­ce­dures, trou­bleshoot­ing con­tent, files with attach­ments or embed­ded movies, and so on).

“Faceted nav­i­ga­tion is arguable the most sig­nif­i­cant search inno­va­tion in the past decade,” write Peter Morville and Jef­fery Cal­len­der in their book Search Pat­terns.“…Faceted nav­i­ga­tion is being rapid­ly deployed across an impres­sive­ly wide vari­ety of con­texts and plat­forms.” I don’t see why it can­not be deployed in a Help Author­ing Tool either.

[pullquote]“Faceted nav­i­ga­tion is arguable the most sig­nif­i­cant search inno­va­tion in the past decade…Faceted nav­i­ga­tion is being rapid­ly deployed across an impres­sive­ly wide vari­ety of con­texts and platforms.”[/pullquote]

SEO functionality for RoboHelp

If you end up post­ing your online help project to a pub­lic serv­er so it can be indexed by Google, Robo­Help’s search may not add much value.

Giv­en that more peo­ple may be using Google’s search to find your con­tent instead of RoboHelp’s own search engine, I think Adobe should con­sid­er some sort of Search Engine Opti­miza­tion func­tion­al­i­ty. For exam­ple, it would be nice to see a fea­ture that enables you to adjust key­words, meta­da­ta, and link­ing in your help project so that your con­tent is opti­mized for Google’s search. See my relat­ed blog entry about prepar­ing your online help for pub­lic use.

Do you agree? Could RoboHelp’s search be bet­ter? If so, how?

 

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.

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