6 ms·

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 co

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.

randlet 8y ago
RST+Sphinx is really fantastic other than the impossible to remember syntax.
- acidburnNSA 8y ago
  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!?"
asicsp 8y ago
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/rstudio/bookdown, https://github.com/hplgit/doconce https://github.com/hplgit/doconce and https://www.methods.co.nz/asciidoc/index.html https://www.methods.co.nz/asciidoc/index.html
- acidburnNSA 8y ago
  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/ 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.html https://www.tompurl.com/2012-11-22-writing-a-book-with-vim.h... This was useful for theming: https://github.com/FriendsOfEpub/eBookTricks https://github.com/FriendsOfEpub/eBookTricks
  - asicsp 8y ago
    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
    - acidburnNSA 8y ago
      Ok it's done: https://digitalsuperpowers.com/blog/2019-02-16-publishing-ebook.html https://digitalsuperpowers.com/blog/2019-02-16-publishing-eb...
      - asicsp 8y ago
        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 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 https://mywiki.wooledge.org/Quotes and https://stackoverflow.com/questions/7680504/sed-substitution-with-bash-variables 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 :)
alpaca128 8y ago
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.
- TeMPOraL 8y ago
  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.
  - alpaca128 8y ago
    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.
    - TeMPOraL 8y ago
      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.
      - alpaca128 8y ago
        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.
TeMPOraL 8y ago
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.)

randlet 8y ago

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

acidburnNSA 8y ago
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!?"

asicsp 8y ago

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/rstudio/bookdown, https://github.com/hplgit/doconce https://github.com/hplgit/doconce and https://www.methods.co.nz/asciidoc/index.html https://www.methods.co.nz/asciidoc/index.html

acidburnNSA 8y ago
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/ 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.html https://www.tompurl.com/2012-11-22-writing-a-book-with-vim.h... This was useful for theming: https://github.com/FriendsOfEpub/eBookTricks https://github.com/FriendsOfEpub/eBookTricks
- asicsp 8y ago
  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
  - acidburnNSA 8y ago
    Ok it's done: https://digitalsuperpowers.com/blog/2019-02-16-publishing-ebook.html https://digitalsuperpowers.com/blog/2019-02-16-publishing-eb...
    - asicsp 8y ago
      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 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 https://mywiki.wooledge.org/Quotes and https://stackoverflow.com/questions/7680504/sed-substitution-with-bash-variables 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 :)

alpaca128 8y ago

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.

TeMPOraL 8y ago
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.
- alpaca128 8y ago
  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.
  - TeMPOraL 8y ago
    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.
    - alpaca128 8y ago
      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.

TeMPOraL 8y ago

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.)