Design

Technical Writing for the Kindle

By Al Stevens, July 23, 2010

Source Code

For code, begin with a paragraph style that has 10-point Courier font. Word has a style named code that fits those criteria. Then after keying the code in, select the code and apply Word's HTML code style, a character style that you apply to keywords embedded in narrative text as well as to program listings.

Lines of code should be less than 47 characters to avoid word wrapping on the smaller Kindles. If that is not possible, advise your readers in the introductory chapter to read code-ridden chapters in landscape mode and perhaps with a smaller font.

Tables

Kindle does not display tables very well. The Kindle 1 does not support borders. So, don't use Word's table feature to portray tabular data. Instead, build tables as illustrations with a graphics editor program and embed them in your Word document as you do other graphical images.

Equations

For equations, use Word's Insert/Object/Equation Editor, with which you create and edit an equation image that Word inserts into the document as a graphical image.

When you save the chapter as HTML (discussed later) Word saves equation .gifs in a folder named [filename]_files. These images are badly formed. Word saves the .gif with incorrect transparency data, and you have to fix it.

If you use a browser to display the chapter, the equation looks fine. But when converted to Kindle format, the equation displays as a solid black rectangle. Interestingly, when you open the equation's .gif in an image editor, such as Windows Paint, it too displays the solid block.

Open the .gif in a program such as Paint Shop Pro (Windows Paint won't do), and change the first color in the color palette to solid white. That's the background color, which is black, and which is supposed to be transparent but isn't. Save the .gif using the option that disables transparency. That fixes the problem. You must do that for all the equation images in all the chapters in the book.

Links

Your Kindle book might have shortcuts that allow the reader to move from the current page to another topic referenced elsewhere in the book. That topic might me in the current or a different chapter. You can use Word's Insert/Hyperlink command for these links. Open the Hyperlink dialog and specify the text to display in the hyperlink and a place for the link to go when the reader clicks it.

If the link is to a different chapter file, your first tendency is to use the .doc filename. But that won't work. The .doc file is only where you saved the chapter. It is going to be converted to HTML in a subsequent step, and the book will be built from HTML files. So, when you build the hyperlink, have it point to the filename you will use for the chapter's HTML file.

Links need a fully qualified path. Most likely all your html files will be in a common folder, in which case you can prefix the linked filename with the dot-backslash (.\) token, which Word expands to a fully-qualified path.

If the link is to a location in the same chapter, that location should have a paragraph header associated with it. The Hyperlink dialog includes a section titled Place in this Document, which shows the document's outline as defined by Header styled text. Select that option and choose a paragraph title to which to link.

Save to HTML

Save each chapter file as the Web Page, Filtered file type. That builds an HTML document without a lot of the excess CSS and HTML code that Word adds. From this point forward you'll work with HTML files in a text editor.

Tweak the Code

There are a couple of changes to make to the HTML files to get code to display properly. Since every line of code is a paragraph as far as Kindle is concerned, Kindle will indent it to the default paragraph indent level. In order to get the maximum line width, you can set the indents for code to zero. Open the chapter's HTML file and insert this line in the CSS <style> code at the top of the file.

p.code { text-indent:0in; text-align:left;}

This assumes that you use the Word style named "code" for code listings.

If your code has blank lines that are important, you'll have to manually insert them. The conversion process, described soon, eats blank lines in code listings. Look for all places in the HTML file for where you find this code:

<p class=code&gt'<code> </code></p>

Insert this tag after it:

<br>

Don't use multiple adjacent <br> tags for multiple blank lines. Insert a <br> tag after each <p…>tag that represents a blank line.

Make an Index

An index is a daunting task for any publication medium, but the Kindle makes it even more difficult. Kindle has no page numbers. Consequently the traditional format with indexed items displayed to the left of one or more page numbers does not work.

You can, however, build an index that associates indexed items with a list of hyperlinks to paragraph headings in the text. Doing a comprehensive index that way for a book of any size is an huge, tedious, error-prone task.

Many authors consider it not worth the effort, particularly since the Kindle has a text searching feature. But indexes often use phrases not found in the narrative as indexes items.

I have not built one yet, but I am a strong believer in having a comprehensive index in a technical book. Years ago I wrote and published in Dr. Dobb's Journal programs to assist in extracting indexeed items from word processing files and automatically building the index.. Those programs were, of course, relevant to traditional publishing media and indexed to page numbers. No doubt before I tackle my first Kindle index I will develop a way to streamline the procedure with software. The plan is to use a special Word character style that can be used to mark indexed items in the Word versions of the chapters. These styles serve only as markers.

Then the first program I write will scan the HTML files and insert anchor tags into the text that identify the paragraphs. Another program will extract the terms and association them with the paragraphs in which they are found. A sort and a formatting process builds the HTML file for the index.

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task.
However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Video

This month's Dr. Dobb's Journal

This month,
Dr. Dobb's Journal is devoted to mobile programming. We introduce you to Apple's new Swift programming language, discuss the perils of being the third-most-popular mobile platform, revisit SQLite on Android
, and much more!