Thank you for the resources, I actually never thought of searching for existing templates… Wrong developer mindset, I always want to do everything by myself ’^^
For the PDF version, did you consider using a tool that can convert from HTML to PDF? LibreOffice and Chromium are the two best options for this IMO. True, that would mean that you couldn’t create a PDF in one step using Pandoc. But on the other hand, you could reuse your CSS, and it’s easy enough to automate multiple steps with a build system.
One big problem with generating PDFs without hand-editing the intermediate LaTeX is that it resulsts in typesetting that is substandard to say the least. Sadly, I’m seeing it in effing print more and more often… orphans and widows everywhere.
Of course, in the current paradigm, good typesetting and living, updatable documents are mutually exclusive things. However, I wonder… until Donald Knuth and friends did it, people didn’t think it’s possible to automatically create good-looking formulas, or hyphenate and justify text properly, but now both are solved problems. Maybe automatic elimination of orphans and widows isn’t even that hard to make good enough, we just haven’t seriously tried yet.
Anyway, speaking of Pandoc, I claim a dubious accomplishment of making it product CommonMark-compliant code blocks using a Lua hook. ;)
Sometimes I think that a dumb and aggressive heuristic for widow elimination would be much better than what we have now: if there’s a widow, just pull the entire paragraph to the next page, nevermind the whitespace it creates.
A page with empty space at the bottom is clearly better than a page with a widowed line. Most paragraphs in the wild also aren’t so long to make the extra whitespace on the previous page look really ugly.
I didn’t know LaTeX or css, it was difficult to set it up and I was trying to fiddle with settings for quite a while. I’ve avoided tinkering for past few months though, writing the book is painful enough. I’ve even stopped updating pandoc - one of the releases introduced some bugs, so I rolled back to a working version. My biggest todo item is custom theme for syntax highlighting, existing ones are so buggy for command line snippets and REPL snippets (highlighting needs to work only for the command prompt line, not the output).
I don’t know make, so unlike OP’s set up, I do use bash scripts.
I put up my ebooks online as well, for which https://github.com/rust-lang/mdBook works nicely. I needed to write a script - single file to multiple chapters and then change internal links because of the split, using <code> tag instead of backticks whenever I need | as part of a table entry, etc.
Thanks for the overview. I’ve come to enjoy writing as part of programming. My workflow is different from this atm, but I’m not writing things to publish so they don’t need to look very fancy. It’s good to know you can do stuff like this with Pandoc!
If you want a simple template for pandoc that creates OK PDFs (just edit font and line spacing), I shared mine at some point: https://github.com/itamarst/pandoc-book-template
Another really nice template, that I use when I have to convert my org-mode files into a decent looking PDF is Eisvogel: https://github.com/Wandmalfarbe/pandoc-latex-template
Thank you for the resources, I actually never thought of searching for existing templates… Wrong developer mindset, I always want to do everything by myself ’^^
Hi, author here! Thank you for posting my article here :)
I explain in this blog post some of the ideas I followed to create my last eBook, problems I faced, and I give an overview of the technical workflow.
Don’t hesitate to ask if you want to know more or have questions :)
For the PDF version, did you consider using a tool that can convert from HTML to PDF? LibreOffice and Chromium are the two best options for this IMO. True, that would mean that you couldn’t create a PDF in one step using Pandoc. But on the other hand, you could reuse your CSS, and it’s easy enough to automate multiple steps with a build system.
One big problem with generating PDFs without hand-editing the intermediate LaTeX is that it resulsts in typesetting that is substandard to say the least. Sadly, I’m seeing it in effing print more and more often… orphans and widows everywhere.
Of course, in the current paradigm, good typesetting and living, updatable documents are mutually exclusive things. However, I wonder… until Donald Knuth and friends did it, people didn’t think it’s possible to automatically create good-looking formulas, or hyphenate and justify text properly, but now both are solved problems. Maybe automatic elimination of orphans and widows isn’t even that hard to make good enough, we just haven’t seriously tried yet.
Anyway, speaking of Pandoc, I claim a dubious accomplishment of making it product CommonMark-compliant code blocks using a Lua hook. ;)
Indeed, but you can still generate LaTeX using Pandoc from Markdown, then do whatever you want with this LaTeX code ;)
Right, but you have to have fixed “editions” then. You can’t keep a living document that is ready for a print run at any time.
True. This process only stands if you want to create a “final” version, for example, to make a print version of your book.
Sometimes I think that a dumb and aggressive heuristic for widow elimination would be much better than what we have now: if there’s a widow, just pull the entire paragraph to the next page, nevermind the whitespace it creates.
A page with empty space at the bottom is clearly better than a page with a widowed line. Most paragraphs in the wild also aren’t so long to make the extra whitespace on the previous page look really ugly.
I use
pandocas well (https://learnbyexample.github.io/customizing-pandoc/).I didn’t know LaTeX or css, it was difficult to set it up and I was trying to fiddle with settings for quite a while. I’ve avoided tinkering for past few months though, writing the book is painful enough. I’ve even stopped updating
pandoc- one of the releases introduced some bugs, so I rolled back to a working version. My biggest todo item is custom theme for syntax highlighting, existing ones are so buggy for command line snippets and REPL snippets (highlighting needs to work only for the command prompt line, not the output).I don’t know
make, so unlike OP’s set up, I do usebashscripts.I put up my ebooks online as well, for which https://github.com/rust-lang/mdBook works nicely. I needed to write a script - single file to multiple chapters and then change internal links because of the split, using
<code>tag instead of backticks whenever I need|as part of a table entry, etc.Thanks for the overview. I’ve come to enjoy writing as part of programming. My workflow is different from this atm, but I’m not writing things to publish so they don’t need to look very fancy. It’s good to know you can do stuff like this with Pandoc!