14

What's a good format for making an ebook that contains code. Is markdown a good option or is there something better available? I may want to convert it to ePub/Mobi and PDF later.

Is it a good idea to add custom styles to markdown files? Would these styles play well with softwares like pandoc?

What other options do I have?

Edit

The book is about prolog and will contain mainly these types of structure:

  • Headings- h1, h2, h3 ...
  • Paragraphs
  • Tables (without headers)
  • Indented Text
  • Code Snippets
  • Big example code blocks which may contain text and code or just code (ranging from 15 to +100 lines). I need these parts to look different from code snippets.
Improve this question
3
  • Do you mean source code in some programming language? Or e.g. encrypted data.
    – Anthon
    Commented Feb 14, 2014 at 5:55
  • I mean Source code
    – Sourabh
    Commented Feb 14, 2014 at 11:13
  • 2
    Markdown -> pandoc -> Sigil seem to be a decent pipeline. Stylesheets can be added by pandoc or manually later.
    – Raphael
    Commented Feb 18, 2014 at 9:55

5 Answers 5

Reset to default
8

Embedding code in EPUB can be accomplished with pure HTML and CSS. The <code> tag and monospace attribute will bring you most of the way. See https://github.com/oreillymedia/HTMLBook for a lot of detail.

Improve this answer
1
  • For backwards compatibility with older readers, <pre><code>stuff here</code></pre> might be a good idea - if I recall, some older devices don't like the <code> tag, also font selection through CSS might fail for various reasons.
    – Hazzit
    Commented Feb 21, 2014 at 0:41
1

It is possible to use Markdown to do that, but it is not in my experience, the best option. Reason for this is that what you should really do is incorporate the code from from real programs that can be tested using some (unit-)test harness. That way there is far less chance that the code you include in your book contains some error that would go unnoticed because it was never run.

markdown is however kept very simple and does not support inclusions of code from somewhere else.

  • There are ways around that limitation using pandoc, as it allows merging of files as it allows merging of files, but for including code snippets of a few lines at a time that is a bit too course to my liking, and you loose the overview in your markdown text where goes what.
  • There are other add-ons for markdown to assemble that keep the include information within the file. You would need to somehow generate the snippets of code to include in your text in separate files and include them.

If you have anything more than a few snippets you should look at the reStructuredText format, and especially its use within sphinx. It was particularly written to document source code. Originally for Python but also supporting other programming languages. It has native support for the including/assembling.

Sphinx has build in support for epub and pdf generation, the latter without having to go through LaTeX. With pandoc, you would have to use LaTeX which is not always trivial to set up, depending on your OS.

Improve this answer
1
  • rST looks interesting. The code in the book won't change very often so I won't need to include source files. I updated the question. For the last point, is there a neat way to do this in rST?
    – Sourabh
    Commented Feb 14, 2014 at 12:28
1

If you don't have to include long blocks of code, maybe the simplest way is to use some form of styled html/xhtml where you will define that code text will use a fixed width font, that you usually should include. Starting from html will make subsequent conversion very easy.

If you have to include long blocks of code, maybe there are better solutions, but I'm not very helpful here.

Improve this answer
1

You can use LaTeX. Packages like listings or minted can be used to include code snippets and syntax highlighting. Both are supported by tex4ht, so conversion to html and then epub is possible. And as bonus, you can get perfect PDF file.

If you are interested, I have a sample document (in Czech language, but I hope the code is readable) where packages minted for syntax highlighting, biblatex for bibliographies, and glossaries for acronyms were used: TeX source and generated html. For conversion, make4ht was used. make4ht is frontend for tex4ht which allow you to use your own build scripts and it has some filters for generated html cleanup.

There is also another tool, tex4ebook, based on make4ht, which can be used to convert LaTeX to epub, epub3 and mobi formats. Note that I am the author of make4ht and tex4ebook.

Improve this answer
1

Leanpub might be a solution. See this section (html) of their manual on code snippets. If you have a lot of code you can put it in an external file and reference it. Leanpub uses markdown and a dropbox folder you share with Leanpub for each book. It generates pdf, epub and mobi so it seems perfect for what you want to do. Their Syntax highligher, pygments supports prolog.

The only downside I have found is the way it handles images. The images have to be at least 300PPI (pixels per inch) so unless you want your book to be huge you have to limit how many images you use. The images look terrible if they are less than 300 PPI.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.