Getting the Most Out of Your O'Reilly iPhone App
Hidden Features - Know Your App
In the summer of 2009, O'Reilly partnered with Lexcycle to begin packaging and selling our books as iPhone/iPod touch applications. Because our book apps are powered by Stanza, Lexcycle's tremendously popular reader app, they include a lot of features, many of which are documented elsewhere. The existing docs demonstrate how to implement the visual customization options-such as changing fonts (Thonburi, FTW), justification, background, indentation, and so on-and how to make the most of the navigation and rich linking. Many features are easy to discover, and you will undoubtedly want to experiment with the built-in configuration user interface. However, some of the newest, coolest, and most useful features are not as well documented, and knowing how to access them is not always obvious in the UI.
Image Detail - Get a Closer Look
Our images generally look great on the iPhone/iPod, but sometimes, crucial details or text within an image can be difficult to distinguish. You can solve this problem by tapping and holding your finger on any image. After a second or two, you are taken to a new screen in which you have access to the familiar pinch-and-spread zoom feature found in other apps. This Image Detail screen lets you see text that may be too tiny in standard reading mode.
For example, the recently published JUNOS High Availability (available as an app now) includes several large and detailed illustrations that work great for print but may leave you squinting when you view them on your device. Tap and hold to get a better look.
Example of a figure in regular reading mode and zoomed in
If you decide you're looking at the image that defines the book in your mind, you can use the Image Detail screen to designate it as the splash cover image that you see each time you open the app. You can also use this screen to add the image to your device's photo album (from which you can then email the file to your sysadmin with the subject heading, "Answer to your T series packet problem!!!1!1!").
Text Detail - Use the Dictionary and Add Annotations
From a user perspective, Text Detail works exactly the same way as Image Detail: tap and hold your finger on a bit of text, and you are taken to a new screen with a unique set of options. The Text Detail screen zooms in on both the entire paragraph and the particular word that you touch. Once you are in the Text Detail screen, you have access to various online dictionaries and a thesaurus for use within the app. The following example is from The New Community Rules (which you can purchase as an app today).
Selecting the word "viral" and looking it up in the dictionary from within the app
You can also use the Text Detail screen to add annotations. To select the text you want to annotate, touch the first and the last words (it may take a little bit of practice to get this technique down-tap "Help" for a pop-up instruction). Once you've selected your text, tap Annotate to add a note. Save and exit the Text Detail screen. The text that you annotated is now highlighted, and you can see your annotation anytime by touching it. Here's an example from the O'Reilly classic Unix Power Tools (available as an app, too).
Adding an annotation and the resulting highlighted text
Once you've added a few annotations, you can browse through them via the Table of Contents and jump directly to any entry with one tap. Adding annotations is an easy way to add multiple bookmarks in your app (in addition to the bookmarking functionality of the Table of Contents itself).
The Code Problem
|Based on reader response, we changed our position on the way that we display code in our iPhone/iPod apps. The newer apps include
white-space: pre-wrapin the CSS that controls the way that the EPUB displays, which causes long lines of code to wrap to the next line rather than run off the screen. As we update older, existing apps, they will use the newer CSS. The following sections are more pertinent to the apps that we published earliest but have not yet updated -- those apps handled code wrapping differently, as described.
Since we started selling our books as iPhone apps, the most frequent complaint that we've heard is that the app is sometimes "too big for the screen" (emphasis on sometimes-long code lines are not always an issue). In other words, the text inside the app runs off the right side of the screen. This problem occurs with blocks of code because the CSS controlling the presentation of the text prohibits line breaking. We've chosen to configure our apps this way out of respect to authors who work hard to make their code well laid out and accurate in our books. Breaking code across lines willy-nilly and treating it as a normal block of text would undermine the time authors put into preparing the code. But we realize we are doing the authors an even greater disservice by not allowing readers to see parts of their code at all!
We're testing different solutions to this problem (and we definitely appreciate the feedback and suggestions sent to email@example.com). If you are reading one of our apps with a lot of long code lines, here are a few strategies you can take to can take to address the problem.
Okay, this one is pretty obvious, and you've probably already tried it, but we still have to mention it. Like a lot of apps, our book apps take advantage of the landscape feature built into iPhones/iPods. Just turn your device sideways. This method, while obvious, does solve the problem of long code lines a lot of the time.
Customize the font type and size, margins, and justification. Tweaking some combination of these things can give you just enough screen space to make those code lines fit.
If the first two methods fail (and they will sometimes fail, depending on the book/app), you can rely on the UI. Code is just text, and you can select blocks of it using the methods described in the "Text Detail" section. Tap and hold your finger on some code to be taken to the Text Detail screen; from there, you'll be able to view all of the text. The following example is from Windows PowerShell Cookbook.
Text detail to the rescue, sort of
There are a couple of things worth noting in these screenshots.
- As you can see, I've already tried the first two methods (landscaping and customizing the text), and a line of code still runs off the screen.
- While the Text Detail screen does show all of the code that was cut off, the line breaks (as the author intended them) are no longer maintained. All of the indentation and formatting is completely lost. In this example, the loss of line breaks in the code in not a big deal since we're looking at just a couple of lines. But you can imagine the difficulty in parsing a large block of code with several long code lines.
If this method doesn't work for you, and you need to see all of the code as the author intended it, we have one other idea for you, described in the next section.
Crack it open
We'll save the HOWTO for the next section, but the bottom line is that all of our iPhone apps are, at their core, EPUB files, which in turn includes a collection of XHTML 1.1 files. Because all of our apps are DRM-free, getting to these XHTML files, viewing the code in a normal web browser, and copying and pasting from them (which is not currently supported in iPhone/iPod interface) can be accomplished with little effort. While we realize that taking the mobile out of a mobile app is not an ideal solution, the option is available.
Extracting an EPUB Pearl
Extracting the EPUB files from any of our iPhone/iPod apps takes just a few steps, and it matters very little whether you're on a PC or Mac.
- Once you've downloaded the app, select Applications in iTunes, right-click the app that you want to extract, and select Show in Finder/Explorer. The file you want is selected automatically when the window opens.
- Copy (that's copy, not move) the file to a different location, for example, your desktop.
- Change the file extension of the copied file from .ipa to .zip using whatever method is most familiar to you.
- Unzip the file using whatever archiving utility you prefer.
- There are a few files, but the directory you are interested in should be named Payload.
- This step varies, depending on platform:
- If you are on a PC, simply go into the Payload/<app_name>.app directory.
- If you are on a Mac, go into the Payload directory, right-click the file within, and select Show Package Contents.
- Again, there are lots of files and directories here, but the EPUB content is found in book/OEBPS.
Now that you've found the files, you are free to read (and copy and paste from) them in your web browser.
If you're curious about the other files in the book/OEBPS directory or about the EPUB standard in general, a good place to learn more technical detail is the "EPUB Resources and Guides" post from the O'Reilly Labs blog.
If you have questions about your O'Reilly iPhone apps, please feel free to contact us at firstname.lastname@example.org.