
Why and How I Wrote My Academic Book in Plain Text - diodorus
http://wcm1.web.rice.edu/my-academic-book-in-plain-text.html
======
explosion
Another huge reason to use plain text that he didn't mention is version
control. With plain text, you can check the files into a git repo and diff any
two commits. You then get all the advantages of working with version-
controlled code, e.g. commenting on diffs.

Word and Google Docs do save revision history, but they slow to a crawl when
you have a document with a lot of pages, to the point of being unworkable.

~~~
sampo
> _Another huge reason to use plain text that he didn 't mention is version
> control._

But version control tools are designed for code, i.e. showing which _lines_
have been edited. With English text one would rather want to see which
_sentences_ have been edited. Are there tools for this? (Except MS Word's
track changes feature.)

Well, one could write one sentence per one line, but that makes a pretty ugly
txt document, when viewed raw.

~~~
munificent
> Well, one could write one sentence per one line, but that makes a pretty
> ugly txt document, when viewed raw.

Many of the tech writers I work with advocate exactly this.

In my stuff, I just hard line wrap the text. Diffs do tend to have more
spurious whitespace changes because of this than I'd like, but that's still
miles better than a completely opaque binary format like Word.

~~~
tomsthumb
Not to advocate for word or anything, but technically it's a zip of xml and
other stuff (images, etc) that get's pulled in through ... OLE(??). VC +
markdown/latex excellent for collaboration or branching drafts.

------
beambot
LaTeX is the standard "plain text" [1] format for academic publishing in STEM.
For those (like the author) who were unfamiliar with LaTeX or find it
daunting, I recommend LyX ([http://www.lyx.org/](http://www.lyx.org/)). Lyx
gives you the best of both worlds: LaTeX under the hood, but with a GUI
interface.

Also... you should look into BibTeX for citation management. This is much
easier than the examples given in the article -- especially with Google
Scholar citations pre-prepared in BibTeX format.

[1] Considering the definition of "plain text" very loosely, since markdown
and LaTeX include rendering cues.

~~~
RexRollman
I don't question the value of Latex but I really don't understand why it
should be so huge.

~~~
bdhe
When Don Knuth wrote TeX, the engine underlying LaTeX, he made sure that
typesetting was a top priority. This includes all sorts of novel spacing,
hyphenation, and other algorithms. See some more examples here:
[http://en.wikipedia.org/wiki/TeX#Typesetting_system](http://en.wikipedia.org/wiki/TeX#Typesetting_system)

For anyone who appreciates Typography, there are few things out there that can
produce aesthetic results as pleasing as LaTeX.

It does have its downsides though, no question, including a steep learning
curve, unintuitive error msgs etc.

~~~
cubix
LaTeX tables drive me crazy. There are tools to help, but for me, it's the
least pleasant aspect of using it. Still beats Word masochism, however.

~~~
singingfish
The only thing I like about word is it's actually quite a good table
composition tool. Just so long as you ignore the defaults that is.

~~~
deerpig
Org-mode has very good support for plain text tables -- which can be converted
into multiple formats.

Org-mode tables are pretty cool, bordering on being a spreadsheet... It's
worth watching a demo, even if you never use it.

[https://www.youtube.com/watch?v=fTJVLJd_gz0](https://www.youtube.com/watch?v=fTJVLJd_gz0)

~~~
singingfish
I've had a go at org mode being a die hard user, but never got past the
original hump. Maybe I need something that better reflects my workflow, maybe
disorg-mode.

------
wetmore
I really like how this guy clearly knows his way around computers (poke around
his site a bit, like the colophon[1]) but his academic interests are in
history. It's great to see hacking interests and skills in someone working in
a different field; I think it's important that these skills don't remain
solely in their usual domain.

[http://wcm1.web.rice.edu/colophon.html](http://wcm1.web.rice.edu/colophon.html)

~~~
wcaleb
Thanks! Important to note that writing my book in Markdown, and having to
learn to use the command line for Pandoc, is what started me down the path to
learning more programming.

------
GoodIntentions
I use plain text editors mainly and agree with the author's premise about
cutting the cruft/using a focused tool. The cost complaint doesn't really fly
though.

Those times When I need something to be in Doc format, I use libre office -
[https://www.libreoffice.org/](https://www.libreoffice.org/) It used to be
called "openoffice". It's free. You can verify the documents look right in the
free word viewer provided by Microsoft if you're planning to mail it to
someone who will open it in Word.

~~~
metasean
> It used to be called "openoffice".

OpenOffice.org still officially lives as Apache OpenOffice -
[http://www.openoffice.org/](http://www.openoffice.org/)
[https://en.wikipedia.org/wiki/LibreOffice#End_of_OpenOffice....](https://en.wikipedia.org/wiki/LibreOffice#End_of_OpenOffice.org)
&
[https://en.wikipedia.org/wiki/Apache_OpenOffice](https://en.wikipedia.org/wiki/Apache_OpenOffice)

LibreOffice was forked from OpenOffice.org back in 2011.

And there are plenty of articles summarizing their similarities and
differences -
[https://duckduckgo.com/?q=openoffice+vs+libreoffice](https://duckduckgo.com/?q=openoffice+vs+libreoffice)

~~~
GoodIntentions
Thanks for an informative post. I was under the impression OpenOffice was dead
post-fork. Colour me wrong...

~~~
rpcope1
Not GP, but LibreOffice is much more actively developed than OpenOffice.org
currently. Any more it looks like OO.org is just getting maintenance from a
few IBMers [1]. It's rather a shame, with all of the brand recognition that
was built up in OpenOffice before being acquired by Oracle.

[1] - [https://lwn.net/Articles/637735/](https://lwn.net/Articles/637735/)

------
abetaha
This author's comment rings true

> One of mine is adjusting the “look” of a word processing document.

I find that editing text in a WYSIWYG word processor distracts me from the
content and makes me tinker with the formatting. Like other commenters
suggested, I switched to using LaTeX and never looked back. Sadly though LaTeX
is not for the faint of heart.

~~~
bkcooper
_I find that editing text in a WYSIWYG word processor distracts me from the
content and makes me tinker with the formatting._

I still end up doing this in LaTeX, only now there's a time lag.

------
shepardrtc
I wrote my Master's Thesis in Word, and I wholeheartedly agree that it is a
terrible, terrible idea. There are so many great options out there today that
academics should have no problem finding something else. Plain text is
certainly an option. Had I been a little more resourceful back in my day, I
would have given it a try. Nowadays though, if I'm writing something big, I
prefer Scrivener. Small, powerful, and cheap:

[https://www.literatureandlatte.com/scrivener.php](https://www.literatureandlatte.com/scrivener.php)

~~~
Someone1234
I'll add this about Scrivener: It is a tool that needs to be learned to
understand it's inherent usefulness. You're are ultimately writing in plain
text, Scrivener is there to help organise, categorise, and to go full screen
for distraction free writing.

------
jamessantiago
Plain text is great. There's so much you can do with it that you can't in word
or even latex. I'll write all my coursework assignments in sublime with a
double column layout so I can have my notes in one window and my draft in the
other. I can then check it all into my git server, run stats against my
writing, and see more text without the need for scrolling. I can also search
the entirety of my coursework or work notes much faster which is great to find
all the references I made to a specific author. I still often have to copy
text into word or latex formats but if you have the templating and styles set
up that can be pretty quick work. It's nice having the raw text and formatted
work seperate.

~~~
baby
I've been writing a book for many years and my set up has always been this:
Sublime text with 2 columns: notes on the right, text on the left.

When I write notes, or a blog post, or an essay, etc... I use Sublime and
markdown. I can easily convert that to LaTeX with pandoc. For more complex
rapport I have a script that do the translation from several .md files to one
.tex file.

If I write a technical paper I just use LaTeX.

I will only use word for a quick and dirty rapport.

------
tschaume
Thanks much for writing this up! At some point, I hope to get to it, too ;-)
Until then, I thought I'd share my approach on how I wrote my entire PhD
Thesis using AsciiDoc here. In my field of High Energy Nuclear Physics, data
analyses usually are accompanied by so-called "Analysis WebPages" which I
generate from the same AsciiDoc source files using Wordpress and Stuart
Rackham's blogpost [1,2]. Images and other binary files I organize and
version-control at a central location using git-annex [3,4] which also allows
me to easily backup and share figures with my collaborators online.
Bibliographies I auto-generate from the usual bibtex file via asciidoc-bib
[5]. I've developed a Makefile [6] that does all of the above "automagically",
triggered by simple commands like `make thesis` (generate full PDF), `make hp`
(push AsciiDoc source to corresponding Wordpress page), and `make tag`
(generate a new thesis version based on git tag and upload to webpage).
Unfortunately, my thesis isn't publicly available, yet, but will be soon along
with the sources and git history (I hope). In the meantime, the HN readers
with STAR privileges [7] can feel free to explore a full working example at
[8-10].

[1] [https://github.com/tschaume/wp-pdf](https://github.com/tschaume/wp-pdf)
[2] [https://srackham.wordpress.com/blogpost-
readme/](https://srackham.wordpress.com/blogpost-readme/) [3] [https://git-
annex.branchable.com/](https://git-annex.branchable.com/) [4]
[http://downloads.the-huck.com/README/](http://downloads.the-huck.com/README/)
[5] [https://github.com/petercrlane/asciidoc-
bib](https://github.com/petercrlane/asciidoc-bib) [6]
[https://gist.github.com/tschaume/a28fdf3522b81a7a4674](https://gist.github.com/tschaume/a28fdf3522b81a7a4674)
[7] [http://www.star.bnl.gov/](http://www.star.bnl.gov/) [8] [http://cgit.the-
huck.com/phdthesis/tree/](http://cgit.the-huck.com/phdthesis/tree/) [9]
[http://star.the-huck.com/](http://star.the-huck.com/) [10] [http://star.the-
huck.com/download/](http://star.the-huck.com/download/)

~~~
k__
Cool. I'm going to look into this :D

I am going to write my Master Thesis in AsciiDoc. It's about modular work-
space awareness features in single page applications. The proof of concept app
is a online AsciiDoc editor with live-preview and eBook/PDF generation, where
I want to write my thesis in.

~~~
tschaume
Very nice! Since writing a thesis is a very special task I think it'd be great
to have such a app be geared towards that purpose. In addition to the features
I now know I needed, I feel like I've gathered quite some experience on how to
achieve control, reproducibility and flexibility using AsciiDoc but I didn't
have the chance to get it out of my head and written down :-) There are a few
pitfalls with the asciidoc and dblatex chain which you only learn to navigate
when you're in the middle of writing the thesis (floating images, word count,
bibliography, organization etc.). The framework/workflow I've set up considers
most of them already and has been a huge timesaver and ease of mind for me.
You can see some of the underlying ideas went into the Makefile I shared and
you could recycle/use them to get a head start on your thesis/project. I'd
definitely be happy to collaborate with you and share all my (MIT-licensed)
experience :-) Feel free to shoot me an e-mail, I'm certain you'll find me
through a quick google inquiry [1] ;-)

[1] [http://lmgtfy.com/?q=lbnl+huck](http://lmgtfy.com/?q=lbnl+huck)

------
copperx
One word of caution: Plain text (or Markdown et al.) are great if you are a
one-man operation or your collaborators share your love of plain text.
However, if any of your collaborators, proofreaders, or editors use Word to
mark up changes, it is incredibly painful to manually go through through the
marked-up Word document, and go back and manually backport every change.

As much as I love plain text and LaTeX and its wonderful typesetting
(especially with the Microtype package, XeLaTeX, and pro fonts), I stick to
Word because it is the status quo in the publishing toolchain: doing otherwise
is swimming upstream.

I would welcome to hear about solutions to this conundrum.

~~~
kijin
If all your documents were in a GitHub repository, you could teach people to
comment on specific lines, view diffs, etc.

However, that's probably still too much for the majority of academic writers
and editors, and you can't blame them because they're too busy specializing in
other fields.

~~~
agumonkey
The homotopy type theory book was managed over github :

[https://github.com/HoTT/book/commit/cb5b01618ac3cf2774430b50...](https://github.com/HoTT/book/commit/cb5b01618ac3cf2774430b503d39e4763c8a4c1e)

------
TomAnthony
This whole articles seems to presuppose that the only alternative to plain
text is Microsoft Word.

Also by his definition 'plain text' seems to include other markup, including
LaTeX. Many academic books and articles are written this way.

Am I missing something?

~~~
bnegreve
The author is an assistant professor in history. I'm guessing LaTeX is not
very popular in this field.

~~~
wcaleb
Original author here. Yes, I'm mainly assuming my reader is a humanities
person less familiar with LaTeX. Though there's increasing interest in
Markdown and LaTeX among historians since I wrote this post. See, for example:

[http://programminghistorian.org/lessons/sustainable-
authorsh...](http://programminghistorian.org/lessons/sustainable-authorship-
in-plain-text-using-pandoc-and-markdown)

~~~
dragonwriter
Asciidoc might be an interesting thing to consider, as well, in this vein.

------
itaysk
Just pointing out the two of the arguments against Word: iPad\iPhone support
and price, are not really valid since MS has official Office for iPad\iPhone
for free. [http://www.theverge.com/2014/11/6/7163789/microsoft-
office-f...](http://www.theverge.com/2014/11/6/7163789/microsoft-office-free-
for-ipad-iphone-android) It might not be as feature rich as the full desktop
version but it sure is more feature rich that plain text.

------
WalterBright
I write all my articles as plaintext. One reason the author didn't mention is
longevity - I don't have to worry about .txt files becoming unreadable. As
long as computers exist, they'll be able to read .txt files.

I then mark up with ddoc, and the result works just fine in
[github]([https://github.com/D-Programming-
Language/dlang.org](https://github.com/D-Programming-Language/dlang.org)).

------
danschuller
Pandoc is great. I'm writing my book in markdown and using some Lua scripts
and a latex style file with Pandoc to produce a nicely formatted pdf. (It's
also one of the more prominent Haskell products but you wouldn't even know
because it just works!)

I'm looking forward to increasing support for things like figure labelling
(Automatically linking figure numbers and labels e.g. see figure 1.2) at the
moment I handle this manually.

------
collyw
In the late 80's when I was in computer classes at school (UK school, not
University) I always remember my teacher citing a study where people using
PC's (probably on DOS at the time) produced better work than people using
Macs. At the time Macs were way ahead with their GUI's and so students would
mess about with formatting and making it look pretty, while the PC users
focused on content.

A few years late studying my Batchelors in Molecular Biology, we got access to
a room full of computers, mainly Macs. Most of the students found this fairly
novel and typed up essays spending ages in the process. We were told that 5%
of the mark would be given for presentation. At the time I found Word really
frustrating (Trying to type 1 / 2 which was part of my address would always
reformat it to a single character half). I gave up quite early on and went
back to focusing on content. To this day I avoid Word, or fancy markup in
favour of text when I can.

------
exodust
I think everyone should have a shortcut icon to a temp.txt file on their
smartphone homescreen. Sometimes you just want to write something quickly
without worrying about what category or what app to open, or where to store
it. You want one tap and start typing immediately, saving and syncing as you
go. I use Note Everything on my Galaxy phone as the text editor. It's fast and
good and stays out of the way. Way better than stock text editors.

On another note, just found this web text editor via an old comment on linked
article. I like it, seems like it's been around for awhile...
[https://writer.bighugelabs.com/](https://writer.bighugelabs.com/)

It just still feels weird to me, using apps that output files, in a web
browser. I'm a developer so shouldn't feel strange, but web browsers just seem
inappropriate to run even a text editor, regardless of the strength of the web
app. I need to get over this mindset.

------
sago
I write my books (5 published so far through Elsevier and others) in Markdown.

It seems the OP uses markdown too. I wondered how he did footnotes in plain
text, he just uses a markdown-style syntax.

It is an excellent approach with benefits over LaTeX. It has better separation
of appearance and content, the content tends to have less visual clutter, and
there are pleasant tools for distraction free writing, which I personally
like. I wrote my thesis and academic papers in LaTeX, so I have used it a lot.

The downside (for both LaTeX and markdown) is dealing with proofing at a
publisher. This is minor the first time, but getting a corrected manuscript
back from the editor when you need to work on a second edition can prove very
cumbersome.

------
justincormack
I was quite (pleasantly) surprised that the O'Reilly workflow is Markdown
based.

------
kinduff
Like George R.R. Martin that uses WordStar 4.0 on DOS to write his books.

I personally use gedit (gnome) and markdown to write my tutorials and
articles. Less distractions, content focused.

------
zackchase
I don't know anyone in computer science that writes academic documents in
Microsoft Word. The standard is LaTeX. It seems the author may be well behind.
All markup (in any markup language) is simply text (as opposed to WSIWYG),
which is the main thing the author seems to find alluring. However, .txt files
by themselves give you no way to manage special characters, references,
footnotes, or any other typesetting functionality.

~~~
Maken
The author isn't from computer science nor have a computer science background.
Outside computer science most people moved from typewriters to WSIWYG editors,
which is the natural transition if you are unfamiliar with how to use a
computer.

Nowadays, when most people being digital natives or being accustomed to use a
computer, it makes more sense for people to move away from analog metaphors to
proper computer-designed tools.

------
edwinyzh
WritingOutliner ([http://writingoutliner.com](http://writingoutliner.com)), is
a Word addin that tries to help professional writers, including academic
writers to write large scale documents, the main concept is splitting long
documents into smaller trunks. The screenshots there will tell a lot.

Disclaimer: I'm the author :)

------
Havoc
Same thing with notes. I used to use fancy formatting in OneNote...then
Microsoft screwed me with an update that shifted, moved & changed everything.

Kick that crap to the curb and swore never to use anything more than
bold/underline/italic for notes again. Plus checked export options on
everything...

------
rynes
I bought a book a long time ago that appears to have been printed on a
standard IBM 1401 line printer.

Title Compiler construction for digital computers Author David Gries Edition
illustrated Publisher Wiley, 1971 Original from the University of California

~~~
cpr
(I had that book for years, when it first came out. Also my first compiler
book.)

Yes, but note that he was using the special upper AND lower-case chain on the
1401, which made it at least vaguely readable.

------
themoonbus
For my thesis, I would write paragraphs in a plain text editor, and then
insert them into a word document. No distractions while writing, and then all
of the formatting / footnoting features when I needed them.

------
mark_l_watson
I agree with most of what he said. With plain text markdown files it is easy
to write using leanpub on my android phone or iPad.

That said, the Office 365 apps run very well on my mobile devices but I only
use them ocasionally.

------
legulere
One reason not to use plain text is that you usually need to manually add
newlines inside a paragraph. This makes me furious when I have to edit
something.

~~~
jamer
Some text editor programs do this for you, either automatically or with a key-
stroke.

------
ninjakeyboard
I'm writing "Learning Akka" for Packt publishing in Emacs Org Mode with
Pandoc.

------
sdrizo
I am partial to notepad++. I agree that formatting is a major buzz kill to
creativity.

------
rynes
I wrote my thesis in 1976 on IBM punch cards. I hired a typist to add the
equations.

------
hagope
My main problem with using text files instead of word, is the lack of
spellcheck...

~~~
collyw
The html text are I am typing this into includes a spell checker.

------
aidenn0
Which markup format does pandoc use by default for a .txt extension?

------
nickysielicki
Can you imagine this guy's reaction when he learns about TeX?

~~~
omaranto
Yes, his reaction will probably be something like: "Mmh, well it is plain
text, which is nice, but it (1) tempts me to waste time adjusting the
typesetting, and (2) TeX or LaTeX source code is much uglier to look at than
Markdown".

------
therobot24
"formatted pdf" doesn't load

~~~
GoodIntentions
It loaded OK for me:

[http://wcm1.web.rice.edu/my-academic-book-in-plain-
text.html](http://wcm1.web.rice.edu/my-academic-book-in-plain-text.html)

It's html.

~~~
therobot24
i keep getting:

Not Found

The requested URL /bitstream/handle/1911/64493/mcdaniel-shear2012.pdf was not
found on this server.

~~~
TomAnthony
Me too. I think it is this:

[https://scholarship.rice.edu/bitstream/handle/1911/64493/mcd...](https://scholarship.rice.edu/bitstream/handle/1911/64493/mcdaniel-
shear2012.pdf)

------
enupten
Even better: use org-mode.

------
deeviant
Why not write with a pencil and paper, I can think of no more distracting
thing than a computer.

Or better yet, a quill and parchment, to totally withdraw from the confines
and entrapments of modern technology.

~~~
marssaxman
RSI? I can get through maybe a page of handwritten text before my hand hurts
too much to think, while I basically always run out of things to say before
typing enough to need a physical break.

~~~
skigg
It sounds like you probably have too tight a grip and write more from than the
wrist and fingers than the shoulder and forearm. This was a solved problem
more than a hundred years ago, when it had to be; in the U.S. it's famously
associated with the Palmer Method[0], although Palmer didn't originate it by a
long shot.

(While these books, of course, are written for use with dip pens, and
frequently taken up by users of fountain pens today, the methods described do
work with ballpoints, rollerballs, gel pens, pencils of not too hard a lead,
nearly whatever you have lying about.)

Of course, retooling is almost certainly not worth it for you, unless you're
dying for a break from computer screens (the only reason I ever write by hand
anymore). But I'll leave the link in case anyone is curious, either for their
own work or just to know what people used to do with a pen, and why writer's
cramp was not as serious a problem before typewriters and computers as we
might suppose it was, by how frequently we tend to induce cramp on ourselves.

[0]:
[https://archive.org/details/PalmerMethod1935](https://archive.org/details/PalmerMethod1935)

~~~
marssaxman
It's true, I have no reason to learn a different method as I have no reason to
write anything by hand, but thank you for sharing the information. I suppose I
had just assumed it was something people got used to, or that regular practice
would build up hand strength in such a way that it would no longer hurt.

------
dendory
It's stupid to use plain text for something that demands rich formatting and
where you expect others to read, like a research paper or book, especially
when there are great alternatives out there. Why not use Markdown, which can
be written and read in a text editor, and compiles as a PDF or HTML and reads
as easily as any Word doc. Or even learning LaTeX, which gives you even richer
formatting than Word yet allows you all the benefits of writing plain text.

~~~
tome
Looks like you didn't read the article.

