EPUB layout for screen and programlisting

EPUB logo

Source: Wikipedia

When deciding on formats for ForgeRock documentation, I figured we needed at least both online and also printable docs. Printed documentation can be used to cure insomnia and start fires, and it can also be used when configuring a system not yet on the network, or recovering when systems are down.

Trouble is, printed documentation can be a pain in the lower back. I recall reaching the 5000 page mark for Sun Directory Server documentation at one stage of review before we released version 6. Although we dropped some documentation, reducing the burden before release, that’s way too much paper to carry around. And that was just one doc set for one product. So when I saw DocBook support for EPUB, it seemed like a good compromise.

The part of the compromise that I have not worked out yet is layout for <programlisting> and especially <screen>. If you have an electronic book reader, or even the plugin for Firefox, and have taken a look at the EPUB documentation as it is currently styled, then you have seen one of the big problems with EPUB layout for technical documentation: on a normally sized monospace font, you have far fewer than 80 columns. Yesterday I got to have a look on a Kindle after converting .epub to .mobi. I counted 38 characters before lines wrapped. (Wrapping at something other than space is also a problem.) This was with a 9 pt monospace font.

Making these blocks as wide as the whole page despite the context is perhaps a way of limiting the mess. Letting readers show the doc in landscape instead of portrait could be another workaround. If you have found a good solution, though, one that preserves the indent in procedures and also works with the HTML and printable docs, I would like to know about what you have done.

Advertisements

2 Comments

Filed under Docs, Tools

2 responses to “EPUB layout for screen and programlisting

  1. Talking about ePUB (you can embed additinal font) one can use “condensed typewriter font”. I know at least one such font (in LatinModern collection http://www.gust.org.pl/projects/e-foundry/latin-modern/index_html lmtlc10, LMTypewriter10-LightCondensed lmtlco10, LMTypewriter10-LightCondensedOblique). Designed for typesetting wide listings 😉

  2. Heya i’m for the primary time here. I came across this board and I find It truly useful & it helped me out much.
    I’m hoping to offer one thing back and help
    others such as you helped me.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s