In HTML, if you want to render a block of code, respecting white-space, but without any hyperlinking or other HTML, it’s easy; just use code. Secondly, if you want to have hyperlinks within your code then there are several options, including placing each line within a li of a list. Thirdly, if you want to render it with intelligent syntax highlighting, there are syntax highlighters from Google and others. But what if you want to combine the first two? Have a code block that respects white-space like indents and line-breaks but also includes HTML? Here we look at one solution.

CSS

div.code-linkable {
  background-color: #f7f7f7;
  border-radius: 4px;
  color: #44443c;
}
.code-linkable > ol {
  font-family: Menlo,Monaco,Consolas,"Courier New",monospace;
  list-style-type: none;
  padding: 7px;
  text-shadow: none;
}
.code-linkable > ol > li {
  white-space: pre-wrap;
}

HTML

<div class="code-linkable">
  <ol>
    <li>SELECT</li>
    <li>  iOrderId</li>
    <li>FROM</pre>
    <li>  <a href="/schema_browser?schema=Orders&table=tOrder">
        Orders.tOrder</a>
    <li>WHERE</li>
    <li>  fGross &gt; 100.00</li>
  </ol>
</div>

As you can see with the greater-than symbol, a disadvantage is that everything ambiguous must be html-ified. If you want a distinct background colour for the code block, do that in a wrapping div since list items have varying lengths (widths).

Having an ebook reader means you can take a library with you to remote locations, and in that library you might want to include tech docs that are available online as HTML. The ebook conversion tool calibre can convert HTML to many formats, but getting non-ugly results relies on a bit of fiddling. This is how I’m doing it today.

My ideal is to have a downloaded collection of web pages included as chapters in the ebook. This is done by downloading each file (via Firefox) with Save Page As... > Web Page, complete and putting each page into a shared folder. Then create an index page that links to each of those pages, in order. Test it by pointing your browser at your index page and checking the links work.

There is some configuration of calibre required.

Common Options. In ‘Look & Feel‘ leave ‘Input character encoding‘ blank.

Output Options. In ‘HTMLZ Output‘ leave ‘CSS‘ as ‘class’ and ‘class based CSS‘ as ‘external’.

Adding Books. Set ‘Automerge added books‘ to ‘Overwrite existing duplicate formats’.

Plugins. In ‘File type plugins‘ > ‘HTML to ZIP‘ set char encoding to ‘UTF-8’ and tick ‘Add linked files in breadth first order‘.

Then

  1. add your book by adding your created index page,
  2. convert, changing the output format to HTMLZ,
  3. extract the resulting htmlz file (it’s really just a zip),
  4. edit the generated index.html and style.css,
  5. keep editing till your browser confirms you have it how you want it,
  6. re-zip the files back into a file with .htmlz suffix,
  7. use that file to create your real target format (eg mobi).

Without those steps you won’t just get ugly fonts and layout, you’ll also have unprintable chars thanks to faulty handling of encodings. For example, Firefox saves “&mdash;” as UTF-8 ’em-dash’, and if that’s fed to calibre using its guessed default encoding it will come out as a garbled blob in your ebook. The above steps ensure calibre does the ‘add’ using UTF-8 (smartly converting it back to &mdash;) and then is allowed to make correct guesses from that point onwards.

Let’s say you want to send a text file to the printer, but a2ps recognises it contains html and tries to send it to something that can turn html into ps. But all you want is the text to be printed, possibly with the html syntax highlighted. The solution is to turn off delegations:

a2ps --delegate=no file_containing_html.txt