How to Write a Book in Emacs (2015) | Hacker News Reader

How to Write a Book in Emacs (2015)

masteringemacs.org

145 pointssea6ear37 comments

I recently explored a bit the (seemingly never ending!) landscape of ways to create ebooks. In the process, I found a number of technologies I did not know before:

* https://www.dita-ot.org/

* http://projectmallard.org/

* https://www.xmlmind.com/tutorials/HTML5Books/HTML5Books.html

I find the concept of DITA very interesting: to write reusable chunks of content (called "Topics"), that one can later map into chapters and sections to generate a whole manual. DITA is geared towards creating manuals, but got me thinking it would be a useful way of splitting content for books and even blog posts.

Mallard seems inspired by DITA but more minimalist. Looks pretty cool if I was generating documentation for a software product.

The last resource is what I will actually try [1]: "XMLmind Ebook Compiler (ebookc for short) is a free, open source tool which can turn a set of HTML pages into a self-contained ebook. Supported output formats are: EPUB, Web Help, PDF, RTF, WML, DOCX (MS-Word) and ODT (OpenOffice/LibreOffice)."

Similar to the author of the OP, I also like PDF better than other formats for reading ebooks.

1: https://www.xmlmind.com/ebookc/download.shtml

I wrote Powerful Python in Emacs.

In short, it worked great. Can't imagine choosing to write a technical book like that in any other editor today.

As an aside I want to say I really like this book. One of the best resources to learn emacs, it puts a lot of emphasis on teaching how the help system works and how to find the way around the editor independently of how it is configured.

> a lot of emphasis

Wouldn’t this be a distraction and an unnecessary cognitive load?

I think using emacs while being unaware of this is possible, but severely limits how comfortable you'll be actually using it. If you don't intend to heavily invest in learning emacs, one is probably much better off using something like VS Code or Sublime Text.

Teaching you how to get online help inside emacs is the equivalent of "teaching how to fish instead of giving you food"... The idea is that you will know how to find your way in emacs no matter which configuration is present on the system. Of course the book does also show how to do a lot of different navigational and editing things.

How does this compare to R Bookdown ( https://bookdown.org/yihui/bookdown/ ), which can do the regular markdown stuff, plus LaTeX, and also run the R code and embed results (tables, plots, etc.) into the book?

I feel that would be comparing apples to oranges. A lot of the stuff he talks about in the article is about emacs as an editor, and not specific to restructured text. Whereas R bookdown is a package for converting complex R markdown into books (via pandoc). By the way, I believe there are packages now for using R markdown in emacs, though I haven't tried any of them myself - R studio's support for R markdown is just too good to consider a switch. (On the other hand I use emacs exclusively for latex)

If you want to compare restructured text with R markdown, then they are simply different tools for different problems. If you want to embed code/figures/tables directly in the writing, R markdown is difficult to beat. Personally I would tend to prefer writing in either latex or markdown, but my reason is similar to the author's: I know latex and (R) markdown much better than I know restructured text.

I just did something similar. Maybe others will benefit from my experience.

For Dercuano I mostly just used Markdown (in Emacs and occasionally Vim, with Git) but then at the end I wrote a janky HTML renderer that outputs PDF in order to have a format people can read on cellphones. If I hadn't done such a rush job on the HTML renderer, I think it would have come out pretty well.

A couple of aspects that did work well were Latin Modern Mono Condensed Light (lmtlc), a TeX font derived from Computer Modern Teletype, page-number links, and Reportlab. lmtlc made it possible to produce a PDF that can display 80 columns of fixed-pitch text on a cellphone screen at a readable size, although I had to fall back to FreeMono for characters outside lmtlc’s repertoire and for boldface. And page numbers make it possible to follow links in Google Drive’s inept PDF viewer, which otherwise lacks any such ability and is disappointingly the Android default, with about 15 seconds of focused effort. Not great, but not bad for a 3700-page book. And Reportlab, a PDF output lib for Python 2, is just a pleasure to work with, which is a phrase very rarely found near the word “PDF”.

The PDF renderer is at https://github.com/kragen/dercuano/blob/master/genpdf.py but probably it would have been a better use of time to figure out how to do it in pandoc, which has an actual box model, even though Petersen isn't enthusiastic about his experience with it.

Readability on cellphone screens is really difficult, demanding a lot of compromise, and I'm very happy with what I was able to achieve there. With another couple of days I would have added hyphenation and justification, which would have made it considerably better still. The result is at http://canonical.org/~kragen/dercuano.20191230.pdf.

The author doesn’t like markdown, but if you like markdown consider using leanpub.com

Emacs and VSCode (the two editors I use) have great support for markdown and the leanpub work flow is very nice.

Discussed at the time: https://news.ycombinator.com/item?id=9714695

Quite a number of mathematics and computer science books are written using latex + emacs.

things I were missing while writing my thesis were completely different from things mentioned in the article:

1) A left hand pane with a tree structure of everything, including chapters, headlines, figures and tables. Dragging and dropping should move sections and the tree should understand that chapters are stored in separate files.

2) An autocomplete for referencing the above.

3) An autocomplete for references in my bib file (and no, I shouldn’t have to remember which paper acl2008a is. I should be able to autocomplete on name or author or date and see exactly which paper I’m pointing to)

Hugely impacted by reStructuredText. Had the author made any other choice the problem space would have been different.

Still a good read.

You can write the text in anything really, but Microsoft Word won out in books and legal work because it has group editing capabilities (comments, track changes, reverse or accept changes etc). Google Docs seems like it might be a contender.

That description of the editing process sort of convinced me not to try emacs for this.

I like org mode too, but giving up the editing for org mode doesn't seem like a fair bargain.

edit: I know this author doesn't use org-mode. I was just pointing out my favorite feature of emacs.

Probably it would have been okay if he'd found an editor who knew how to use a text editor and Git.

Yup. But those people doesn’t grow on trees. AFAICT knowledge of git is practically nonexistent outside of software development.

Would you hire a lifelong celibate editor to edit an anthology of erotica? If not, why would you hire an editor who doesn't know how to program to edit a book on Emacs?

I guess it all boils down to supply and demand. If the publisher can find editors that also knows how to program then kudos to them.

But isn’t the crux that if you can program, you can often land another job that pays much more than being an editor?

[Edited]

I think that in this case the author hired the editor directly, not through a publisher. I'm sure you're right about the wages thing, so presumably you'd have to pay programmer wages rather than regular editor wages.

Question on the book itself: as a 20 year vim user, is it a good book to learn Emacs?

Haven’t read it so I can’t comment on the book itself. But the built-in tutorial in Emacs is quite good. Just type C-h t to launch it.

I find my way to emacs everytime I want to do anything lisp or scheme related, for everything else I use a mix of VS Code and IntelliJ Idea (former for TypeScript, latter for Java). So emacs can be the best IDE for certain languages.

Also, in the same way I have vim key bindings enabled for everything that supports it, a lot of UIs come with emacs bindings out of the box, so it is useful to learn some of them.

I also can't comment on the book, but I'd recommend trying out Spacemacs if you are interested in learning Emacs. With Evil mode, you get to continue using a lot of your muscle memory from vim, and it's just overall a more pleasant experience with the discovery feature.

https://www.spacemacs.org/

Anyone know what window manager he's using here?

https://www.masteringemacs.org/static/uploads/ediff.png

That's Emacs itself. It supports tiling in myriad forms.

I don't know, but I suspect is some window theme on some gnome window manager? It looks like the window split is a normal emacs split.

I love Emacs, but my editors will never touch anything that's not a docx, so Word it is...

Pandoc can output to word. Writing in markdown and sharing the word output with editors/reviewers is a reasonably nice workflow — just treat the docx file as a pdf (or any other output format).

Not for me. I have to track changes in a document through the whole editing back and forth. And I have special org templates.

Yeah, I don’t have a great solution for tracking changes across multiple back-and-forths within Word, I use git with markdown for that. Pandoc is pretty ok with word templates, but the final version of a document will usually need a little manual tuning before it looks right.

A former teacher of mine was working on a way to do this with pandoc and Rmarkdown. The result is called redoc: https://github.com/noamross/redoc It's still in beta though.

So why not AsciiDoc instead of rst?

ePub on Kindles? When did that happen? Or is the author missing a step?

Or is the AZW/KFX format similar enough to HTML that - like with ePub - a generic HTML file will get you almost everything you need (plus some metadata and a simple conversion)?

XML, not HTML. I use Calibre to manage my kindle as well as my larger digital library and it handles conversions just fine.

Easy! Just push all the buttons on your computer in the right order.

Yeah, but you’d want to open Notepad first.

Reply on news.ycombinator.com