Computer code in Ebooks

[madfilkentist]

elf just called this community to my attention today, so hello, everyone.

I'm working on a book, with the plan of publishing it on Smashwords, called Files that Last. There's a Kickstarter campaign for it, but with time rapidly running out, its chances don't look good. If you want to throw $700 at it, though, I won't object!

Even without the Kickstarter money. I'll publish the book, though without the level of professional review I'd like. I'll still have a professionally designed cover and get proofreading in exchange for a promise of reciprocity.

But to get to my actual question, I've discovered from a trial run book that putting computer code into a Smashwords book and have it come out of the meatgrinder readable is very difficult. I solved the problem there by linking to code files. Has anyone else had experience with code or other difficult-to-format text in ebooks? Any advice would be appreciated.

Comments

[amalthia]

If I'm reading your question correctly you need to be able to display computer code in your ebook however the conversion program keeps translating the code into some sort of text that makes no sense?

If this is the case, I've run into the problem on a website where I needed to display code (for a tutorial) I had to use HTML entities: examples located at W3schools. This may help...

[madfilkentist]

Sorry, I should have been more precise. The conversion process messes up the line breaks and indentations. It's still valid code, just very hard to read.

I didn't have to turn all the angle brackets in my XML into entities, fortunately. That would have been an even worse pain.

[amalthia]

What are you using to convert your book? I use calibre and my page breaks work fine and the indents stay.

[madfilkentist]

With my trial book, I let Smashwords run its all-purpose conversion software, called "Meatgrinder," on it. It converts to lots of formats, none of them very well. Calibre may be the better way to go.

[elf]

Fortunately, Smashwords will soon be able to accept (maybe already accepts; I haven't checked recently) epub files, not just word docs. The Meatgrinder is indeed awful for anything that needs precise formatting. And it's touchy besides that.

I usually build epubs more-or-less manually in Sigil; amalthia is great at building them with Calibre. There's likely some problems with either methods, because there is just *nothing* that's going to make long code sections look good on a 6" screen, which is most ereaders.

There are ways to improve it. You can make different styles for each type of indentation so the indents don't vanish when the lines have to wrap, and define them with smaller indents than paper publishing usually wants. (Half an inch is a *lot* of space on 3.5" wide screen.) There are, unfortunately, no ways to make it work well, and one of the first rules of ebook design is "you don't get to choose how it's seen by the reader." You can make suggestions, but their settings, be those software or hardware, might override the formatting in the file.

This ties in wonderfully with issues of data preservation; markup is only as useful as the ability to recreate the original intent.

The issue of formatting code in ebooks hasn't much been dealt with (because presumably, stripping the formatting out gets you functional, if hard-to-read, code instructions), but formatting poetry has, and there are several good posts about that.

Formatting a Tail for EPUB: Concrete Poetry and Varying Screen Width uses the classic Mouse’s Tale poem.

Formatting Poetry for EPUB and Small Devices shows how poetry displays with a few different settings, and how to apply   instead of spaces between some words to make sure that if the lines break, they break where you want them to.

[madfilkentist]

Yes, I've got Calibre and have started playing with it, and may use that for FTL rather than submitting it to Meatgrinder. The downside if I go with Smashwords is, of course, that I don't get conversion to all the other formats. I think one good-quality format, if it's as widely used as Epub, is better than bad quality in lots of formats. It's just a shame if I won't be able to deliver a PDF.

The issues of poetry are certainly similar, and any solution that can get "The Mouse's Tale" right ought to be good enough to get code right. I'll have to study that article carefully.

[elf]

You can do both--submit an epub for the epub buyers, and a Word doc for the meatgrinder for other formats. The conversion to PDF is probably the best of the options (although, ugh, PDF is tolerable as an archive format and lousy as an ebook format).

You may want a mobi version or KF8 version (which is epub in an Amazon-flavored wrapper) for sale at Amazon; I don't think Smashwords feeds to them. And unless you've got specific moral or business issues with Amazon, it's a bad idea to ignore the place with about 80% of the market share.

Part of how "The Mouse's Tale" works is that it's *tiny.* Each line only needs a few words of text at most. It can allow for heavy empty-space padding on each side and still fit in a small window. It won't work on e.e. cummings' Buffalo Bill's.

[madfilkentist]

Being able to do both may be new since the last time I checked. Thanks for calling that to my attention. If I provide only an Epub file, Smashwords won't provide a preview, which would hurt sales, so it looks as if I need to do both even though it's more work.

[amie]

Hey! Funny thing, I just found out about your book and backed your kickstarter about 10mins ago! So just letting you know word is getting out :) good luck!

[madfilkentist]

Thank you!