Hacker News Reader

Comment by acidburnNSA | Hacker News Reader

I just wrote a little e-book in vim using reStructuredText and Sphinx for all the bookkeeping. It took a bit to get started, but ended up being a really nice combo. Vim for all the editing and navigation, of course, and RST+Sphinx for all the hyperlinking, footnotes, TOC, glossary, index, headings, images, etc. Then I just rendered it to HTML, PDF, ePub, and pure text (for grammar checking). I think RST is less popular than Markdown, but it's really incredibly powerful. You can in-line LaTeX formulas, a Tikz image, a graphviz dot, and all sorts of things.

Formatting and theming is a bit of a pain, but I think with just a little more work, it'd be easy to recommend this path for anyone making technical books, courses, etc. Lightweight markup languages and vim feel like steampunk at first, but they're actually more productive than mainstream modern tools.

View on HN

My favorite so far is the org-mode format. It has more features than Markdown(like tables) and can also be mixed with LaTeX syntax.

RST seems pretty interesting and versatile as well.

Org is absolutely amazing, though unfortunately as a markup language defined by its reference implementation (Org Mode in Emacs), it won't gain much popularity. If you're working alone, and especially if you're already using Emacs, it's the best tool out there. If you have to collaborate with non-Emacsers on a document, RST and Markdown are unfortunately the better choices.

You don't need Emacs in order to work on org-mode documents, in the end it's just a text file. I write all my org documents in Vim and then convert them via Pandoc or with a keybinding making Emacs convert it in batch mode. It's barely different than working with Markdown, it just offers much more.

You don't need Emacs to work with org-mode, but without Emacs, org-mode is just marginally better but much less popular Markdown. Org-mode really shines through its Emacs implementation - the absolutely magical interface for working with tables, the TODO/agenda capabilities, spreadsheet capabilities, the executable source blocks and literal programming - which turn it into a better version of Jupyter notebooks, etc.

I don't need any magical features, I just looked for something like Markdown but with support for tables and LaTeX, so this format is perfect for me.

Also, table support and LaTeX commands bring far more functionality than all of Markdown in the first place, I wouldn't call that marginal.

Table support is one thing. Conveniences for editing those tables are another :).

Still, it's great to know org as a format fills your needs outside Emacs. Maybe I'm being too pessimistic about it's adoption potential.

Speaking of your little e-book, I just sent you an e-mail with some thoughts on it, as promised.

(I may have forgotten to set the Title on that e-mail, sorry about that.)

do you have a more detailed write up for this publishing process? or some references that you followed to get this set up?

I'm looking for alternate ways than just github-style-markdown+pandoc for creating ebooks for more features and polished look

I'm also looking into alternates like https://github.com/rstudio/bookdown, https://github.com/hplgit/doconce and https://www.methods.co.nz/asciidoc/index.html

Not yet, but writing one for today's versions of all the tools is something I plan to do within a week. I can ping you if/when I get it up.

I started with older links like this: https://pedrokroger.net/using-sphinx-write-technical-books/

This is inspiring but less useful: https://www.tompurl.com/2012-11-22-writing-a-book-with-vim.h...

This was useful for theming: https://github.com/FriendsOfEpub/eBookTricks

cool, thanks a lot for the links

yeah, I'd like to know if your article is done - a reply to this comment would do, thanks again

Ok it's done: https://digitalsuperpowers.com/blog/2019-02-16-publishing-eb...

thanks a lot, will go through and get back to you if I have clarifications :)

some suggestions if I may:

* could you add your website to your HN profile? https://news.ycombinator.com/user?id=acidburnNSA - makes it easier to know about it, that was where I looked up first before commenting in this thread

* just saw about your book on the website... for the regex video showcase, I see that you are using double quotes - I'd suggest to always use single quotes unless you need double quotes (see https://mywiki.wooledge.org/Quotes and https://stackoverflow.com/questions/7680504/sed-substitution...) as double quotes are interpreted by the shell before it is passed to the command

the topics covered in your book are super interesting and make for a nice workshop, will check it out :)

Cool, thank you for the suggestions. I added info to my profile. Thanks for the tip on double-quotes! I didn't fully grasp that nuance.

Hey, maybe I should try to put on a little workshop as a book promotion. Thanks again.

RST+Sphinx is really fantastic other than the impossible to remember syntax.

Bonus of writing a book in it: about 50 pages in you finally get the hang of it.

"Which side of this does the underscore go on!?"

Reply on news.ycombinator.com