This chapter shares some of the stumbling I had when I initially learned how to use AsciiDoc. I share it to help you avoid the same mistakes.

Image Issues

It took me a while to realize I was being sloppy and causing my own problems. For example images are called by AsciiDoc using the delineator image::.

images::media\filename.png[] will not work

image::media\filename.png[] will work

It took me ten minutes to find the issue. Hopefully you can learn from my mistake and avoid this problem. The delineator is image::, not images::. There is no 's' in the delineator.

Here’s an example of what you’ll see when you do it wrong. The AsciiDoc code shows up in the book. This is an actual example of my own mistake while making this book.

Figure 1. Wrong Way Shows Code Instead of the Image

Compare that to how it looks when done correctly.

Figure 2. Correct Way Shows the Image

Another way to break images in AsciiDoc is to leave off the square brackets at the end of the image reference. The rendering app will give you an error for this mistake too.

Be careful until you build good AsciiDoc habits.

Another image problem is using rastor images not sized for your output. I edit their size with the Gimp app.

Tables Don’t Work Well Yet in Most eReaders

When I write technical documents and nonfiction, I am used to using tables. Simple tables to complex tables help communicate. I got tables working great on the first big book (80,000 words) I wrote and I tested to PDF regularly. However, when I got to eBooks the tables came out so poorly that I had to convert them to bulleted lists instead. I tried tables on Kindle e-ink readers, iBooks on iOS phones and iPads, and Adobe’s Digital Editions. They were not acceptable quality. As the reader, I was not happy with the output of tables to any of these eBook readers.

So you don’t have to experience the table pain I did, you can:

  • Option A: Avoid tables altogether. Switch from tabular structure to a bulleted list structure.

  • Option B: Use conditional publishing with AsciiDoctor and render tables for PDF and bullet lists for smaller eReader screens.

As eReader technology improves, perhaps tables will render better in eBook formats. If you think about it, the large majority of eBooks today are fiction novels that are largely narrative text. So eReader apps were optimized for large areas of text.

If you plan to use tables, see [referenceSites] for sites that show how to use tables in AsciiDoc. I’m not going to cover tables because so few reader apps today render them well. If you do decide to use tables, you may want to use conditional publishing and use tables in PDFs for print and bullet lists of the same content for most eReaders. See [conditionalRendering] for details on conditional publishing.

If You’re Going to Use Conditional Publishing, Change your Attribute Flags

This may sound obvious, but when I got into a deadline crunch I published a conditional publishing book to both conditions, but I forgot to set the conditional attribute flags for the situation.

It is not too big of a problem. It just involves a small amount of rework in the automated production. To HTML, you won’t notice the change. For a large book going to PDF, it means waiting minutes. It is not too long, but is about as much fun as waiting for an elevator to come to your floor.

Footnote Problems

Early in my use of AsciiDoc I had issues with footnotes because I forgot the include the colon. Notice that in the example, the colon is after the "footnote" key word and before the square brackets [].

footnote:[Here is the text of the footnote that will show up at the bottom of the page for PDF or at the end of the book for HTML.]

If you forget and drop the colon, it can be self-correcting because you’ll see no linked number and no footnote with that reference number. Instead you’ll see the inline footnote AsciiDoc code instead.

Here is a correct footnote example.[1]

Here is an incorrect footnote example.footnote[An example footnote only]

See how the two contrasting examples render differently? The correct example renders to an inline number that links to the footnote at the bottom of the page (PDF) or end of the book (HTML).

So when you render to HTML or PDF and you see any AsciiDoc codes still showing that tells you a mistake was made (notice the passive voice?). Yes, that tells you that you made a mistake and need to go back and add the colon.

When using audio review (see [audioReview]), if you hear the word footnote in an unusual place, that’s your cue that you missed the colon too. If you hear a number at the end of a sentence while listening to the audio version of the book draft, that means it rendered correctly.

The good news is that it’s not a difficult fix. The rendering app does what it’s told to do. So when it doesn’t look as expected, that’s your cue.

Having Internet Access During Rendering

If you use the attribute :icons: font, this needs access to the internet to work when you render to HTML. I had turned off my wireless for a while, and when I came back to the book draft none of the icons for admonitions were working.

After some troubleshooting, I realized the only thing that had changed was my shutting off the internet access. So I tested it with the internet on again (wireless on), rendered to HTML and it worked fine.

1. An example footnote only

Line By Line

Here a Little, There a Little, Layer by Layer.

Back to Overview