
How to Write a Book in Emacs (2015) - sea6ear
https://www.masteringemacs.org/article/how-to-write-a-book-in-emacs
======
emmanueloga_
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/](https://www.dita-ot.org/)

* [http://projectmallard.org/](http://projectmallard.org/)

* [https://www.xmlmind.com/tutorials/HTML5Books/HTML5Books.html](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](https://www.xmlmind.com/ebookc/download.shtml)

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

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

~~~
Koshkin
> _a lot of emphasis_

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

~~~
nickpeterson
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.

------
datashow
How does this compare to R Bookdown (
[https://bookdown.org/yihui/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?

~~~
funklute
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.

------
kragen
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](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](http://canonical.org/~kragen/dercuano.20191230.pdf).

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

------
dang
Discussed at the time:
[https://news.ycombinator.com/item?id=9714695](https://news.ycombinator.com/item?id=9714695)

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

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

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

Still a good read.

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

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

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

~~~
kragen
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?

~~~
cpach
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]

~~~
kragen
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.

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

~~~
cpach
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.

------
haecceity
Anyone know what window manager he's using here?

[https://www.masteringemacs.org/static/uploads/ediff.png](https://www.masteringemacs.org/static/uploads/ediff.png)

~~~
mickeyp
That's _Emacs_ itself. It supports tiling in myriad forms.

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

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

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

~~~
grayclhn
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.

~~~
artwr
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](https://github.com/noamross/redoc) It's
still in beta though.

------
Stay_frostJebel
So why not AsciiDoc instead of rst?

------
bhaak
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)?

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

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

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

