path: root/2024/captions/emacsconf-2024-writing--emacs-writing-studio--peter-prevos--main.vtt

WEBVTT captioned by sachac

NOTE Introduction

00:00:00.000 --> 00:00:02.799
Hi, I'm Peter Prevos, and I'll be talking about Emacs

00:00:02.800 --> 00:00:06.039
Writing Studio. I'm a water engineer, a social scientist,

00:00:06.040 --> 00:00:08.759
and I dabble in theatrical magic. For each of those

00:00:08.760 --> 00:00:11.399
endeavors, I do a lot of writing. I take notes, I write

00:00:11.400 --> 00:00:14.559
reports, articles, books, and websites. I use Emacs for all

00:00:14.560 --> 00:00:18.719
my research, my writing, and my publishing. Emacs Writing

00:00:18.720 --> 00:00:20.999
Studio is an opinionated starter kit for authors who write

00:00:21.000 --> 00:00:23.999
for humans, not for programmers who write for computers.

00:00:24.000 --> 00:00:26.879
It consists of a configuration, some bespoke

00:00:26.880 --> 00:00:31.119
functions, but are not yet a package, a website, and a book.

00:00:31.120 --> 00:00:36.279
The book is completely written with EWS itself. The target

00:00:36.280 --> 00:00:39.039
audience are authors who are frustrated with using

00:00:39.040 --> 00:00:41.239
commercial software and hopping from application to

00:00:41.240 --> 00:00:45.879
application to achieve an objective. These are people

00:00:45.880 --> 00:00:49.986
without any Emacs experience or coding skills.

00:00:49.987 --> 00:00:53.307
The objective is to teach these people how to use Emacs,

00:00:53.308 --> 00:00:57.648
not how to configure Emacs to manage a complete writing project.

NOTE Why?

00:00:57.649 --> 00:01:00.479
So why did I write a book about Emacs when the documentation is

00:01:00.480 --> 00:01:04.719
already so extensive? Most Emacs documentation focuses on

00:01:04.720 --> 00:01:08.839
configuration, burying potential new users with choices.

00:01:08.840 --> 00:01:13.039
It forces people to work on Emacs instead of with Emacs,

00:01:13.040 --> 00:01:18.039
and it quickly can become a productivity sink. Emacs is the

00:01:18.040 --> 00:01:21.399
ultimate free software platform, but with this freedom

00:01:21.400 --> 00:01:25.879
also comes a price. Barry Schwartz wrote about the

00:01:25.880 --> 00:01:29.239
paradox of choice, which is about the dramatic explosion in

00:01:29.240 --> 00:01:32.119
choices in the modern world. Just think about the amount of

00:01:32.120 --> 00:01:34.599
effort it can take to decide what cereal to buy in a

00:01:34.600 --> 00:01:37.559
supermarket that you haven't been before. So many

00:01:37.560 --> 00:01:40.559
different choices. Paradoxically, that's become a

00:01:40.560 --> 00:01:44.239
problem instead of a solution. Emacs can perhaps suffer

00:01:44.240 --> 00:01:49.559
from the same issue. Another objective, using a COVID-19

00:01:49.560 --> 00:01:54.039
trope: EWS is about flattening the curve--that is, the

00:01:54.040 --> 00:01:56.727
learning curve--by making these choices

00:01:56.728 --> 00:02:02.451
for the new Emacs user and avoiding the paradox.

NOTE EWS configuration

00:02:02.452 --> 00:02:05.593
What about this EWS configuration?

00:02:05.594 --> 00:02:07.839
I decided to stay as close as humanly

00:02:07.840 --> 00:02:11.039
bearable to vanilla Emacs. I say that tongue-in-cheek,

00:02:11.040 --> 00:02:16.026
but also with some realism, centered around Org mode

00:02:16.027 --> 00:02:18.279
and Denote for note tagging, and citar for accessing

00:02:18.280 --> 00:02:21.319
bibliographies, and other convenience packages such as

00:02:21.320 --> 00:02:24.959
vertico for minibuffer completion. There's a

00:02:24.960 --> 00:02:27.999
dictionary, a thesaurus, and some other packages that are of

00:02:28.000 --> 00:02:32.559
interest to authors. EWS uses the standard keyboard

00:02:32.560 --> 00:02:37.359
shortcuts. Writing is much more about thinking than about

00:02:37.360 --> 00:02:40.439
maximizing the amount of words per minute. Just think

00:02:40.440 --> 00:02:43.639
about that the most used function for authors is

00:02:43.640 --> 00:02:46.919
self-insert. There's no need to use fancy keyboard

00:02:46.920 --> 00:02:50.071
shortcut systems when you write prose.

NOTE How did I develop EWS?

00:02:50.072 --> 00:02:54.534
How did I go about developing Emacs? I declared Emacs bankruptcy,

00:02:54.535 --> 00:02:57.096
like we all have every now and then.

00:02:57.097 --> 00:02:58.479
I decided to write this book with

00:02:58.480 --> 00:03:02.119
vanilla Emacs and only configure the system as was

00:03:02.120 --> 00:03:04.919
required. The first thing I did, I hooked visual-line-mode

00:03:04.920 --> 00:03:08.999
to text-mode and off I went. The configuration grew as the

00:03:09.000 --> 00:03:13.119
need arose. I was actually surprised with how far you can

00:03:13.120 --> 00:03:17.759
get with just using Vanilla Emacs. I also developed two

00:03:17.760 --> 00:03:21.953
packages to enhance how I can use Denote.

NOTE Overall workflow

00:03:21.954 --> 00:03:25.375
Well, let's get to a demo.

00:03:25.376 --> 00:03:30.157
EWS is based on a typical research and writing workflow.

00:03:30.158 --> 00:03:32.759
First step is you need to get some inspiration.

00:03:32.760 --> 00:03:35.479
Usually we do that by reading, by watching, by

00:03:35.480 --> 00:03:39.319
listening. Then the next step is ideation. You develop your

00:03:39.320 --> 00:03:42.679
ideas, summarize ideas from other people, write down your

00:03:42.680 --> 00:03:46.439
own ideas. For that, you need a note-taking system. EWS

00:03:46.440 --> 00:03:50.279
also talks about managing bibliographies. The third step

00:03:50.280 --> 00:03:53.439
is production. This is the actual writing process where, in

00:03:53.440 --> 00:03:57.479
this case, the EWS book. Once that is finished, we

00:03:57.480 --> 00:04:00.639
convert this Org mode file into something that can be

00:04:00.640 --> 00:04:04.119
published. That might be an e-book in an EPUB format, or a

00:04:04.120 --> 00:04:08.759
PDF for the interior of a a paperback book or perhaps as an

00:04:08.760 --> 00:04:12.159
e-book as well. There's also configuration in Emacs to

00:04:12.160 --> 00:04:16.759
produce MS Word documents if you need to collaborate with

00:04:16.760 --> 00:04:22.359
other people. Let's jump in to Emacs and walk through this

00:04:22.360 --> 00:04:25.399
workflow, give you a very quick demonstration of what's in

00:04:25.400 --> 00:04:29.319
the box.

NOTE Inspiration

00:04:29.320 --> 00:04:32.879
So the first step in the EWS workflow is inspiration. We all

00:04:32.880 --> 00:04:35.319
stand on the shoulders of each other. Some giants; most of

00:04:35.320 --> 00:04:38.079
them are normal people. We get inspiration by reading,

00:04:38.080 --> 00:04:40.799
listening, and watching, and Emacs can help you access

00:04:40.800 --> 00:04:44.279
text, sound, and video. It depends on external software.

00:04:44.280 --> 00:04:47.639
Emacs acts as a beautiful interface, and EWS helps you

00:04:47.640 --> 00:04:50.919
with the configuration. But we also need a tool to manage our

00:04:50.920 --> 00:04:53.631
electronic library, and BibTeX

00:04:53.632 --> 00:04:56.054
and citar package by Bruce D'Arcus

00:04:56.055 --> 00:04:58.119
provides a perfect interface to manage this

00:04:58.120 --> 00:05:02.959
literature. If I open my bibliography here, you see that

00:05:02.960 --> 00:05:06.959
I've got 1864 references in my BibTeX files. There's a

00:05:06.960 --> 00:05:11.999
whole bunch of stuff about, I guess, the weird things that I

00:05:12.000 --> 00:05:14.479
read. Let's look for Emacs, right, because that's a joint

00:05:14.480 --> 00:05:18.679
interest that we have. Let's open here this paper by

00:05:18.680 --> 00:05:23.799
Marcus Birkenkrahe, who did some research using Emacs to teach

00:05:23.800 --> 00:05:26.679
data science. Data science is my day job, so that had my

00:05:26.680 --> 00:05:29.759
interest. We have here a Denote file, which I'll talk

00:05:29.760 --> 00:05:33.399
about in a second. There's a library file, which is a PDF, but

00:05:33.400 --> 00:05:35.599
it could be a whole collection of different files in

00:05:35.600 --> 00:05:39.119
different formats, even video or sound. We can create a new

00:05:39.120 --> 00:05:42.279
Denote file, or there's a link to the document object

00:05:42.280 --> 00:05:46.959
identifier. Let's go to the PDF. Here we can now do our

00:05:46.960 --> 00:05:50.479
reading. We can get our inspiration by what Marcus has

00:05:50.480 --> 00:05:52.679
written here about teaching data science with literary

00:05:52.680 --> 00:05:54.760
programming tools.

NOTE Ideation

00:05:54.761 --> 00:05:57.599
Next step is ideation. Taking notes is

00:05:57.600 --> 00:06:00.999
the core of all creativity. When I read that paper, I might

00:06:01.000 --> 00:06:05.079
want to copy some ideas, I might get some of my own ideas, and I

00:06:05.080 --> 00:06:07.679
need to write that down. I basically write everything in a

00:06:07.680 --> 00:06:10.919
paper notebook, but then I transfer the things that are

00:06:10.920 --> 00:06:14.079
worth keeping to the Denote note-taking system. Now, there

00:06:14.080 --> 00:06:17.519
are many systems that exist out there that promise you

00:06:17.520 --> 00:06:20.639
note-taking heaven when you just follow a certain process.

00:06:20.640 --> 00:06:24.919
My advice: don't worry about Zettelkasten, PARA, or

00:06:24.920 --> 00:06:28.479
whatever is out there. Just write your notes and worry about

00:06:28.480 --> 00:06:31.479
structure and all that later. Even Niklas Luhmann, the

00:06:31.480 --> 00:06:34.639
inventor of Zettelkasten, called his system a septic tank

00:06:34.640 --> 00:06:38.319
of ideas. I call my collection of notes a primordial soup

00:06:38.320 --> 00:06:43.439
from which my books emerge. Now, Denote by Prot Stavrou is a

00:06:43.440 --> 00:06:45.919
flexible note-taking system that can implement any of the

00:06:45.920 --> 00:06:49.119
popular methods. I transferred thousands of files to

00:06:49.120 --> 00:06:54.319
this format, so all my information is at my fingertips. We

00:06:54.320 --> 00:06:59.759
can jump to the Denote directory. In my case, that's

00:06:59.760 --> 00:07:04.279
~/documents/notes. We see here the marvel that is Denote,

00:07:04.280 --> 00:07:09.759
which is its ingenious file naming convention that has a

00:07:09.760 --> 00:07:15.279
timestamp, a title, and some (what do we call them) tags or

00:07:15.280 --> 00:07:18.559
categories, whatever you please. This is a very quick way

00:07:18.560 --> 00:07:28.763
to find things. Then there is an ews-dired-narrow function.

00:07:28.764 --> 00:07:30.799
For example, I can find anything,

00:07:30.800 --> 00:07:34.679
_ews means anything that has the EWS tag, and

00:07:34.680 --> 00:07:39.112
there we go, it's narrowed down in my EWS notes.

NOTE denote-explore

00:07:39.113 --> 00:07:45.040
Now, this is all very well, but I also decided to

00:07:45.041 --> 00:07:47.102
write a package called denote-explore,

00:07:47.103 --> 00:07:54.071
which helps us sort of explore these collections of notes.

00:07:54.072 --> 00:07:55.519
One of the fancy things we can do is

00:07:55.520 --> 00:07:56.519
do some visualization.

00:07:56.520 --> 00:08:02.159
Let's go to the network function and create a community of

00:08:02.160 --> 00:08:05.359
notes. A community is a collection of notes that match a

00:08:05.360 --> 00:08:10.039
regular expression, _ews. All the notes here

00:08:10.040 --> 00:08:15.599
that are on this list, the ones with the EWS tag. In a second,

00:08:15.600 --> 00:08:22.159
my browser pops up. I shall move that to my other window in a

00:08:22.160 --> 00:08:28.599
second. There we go. denote-explore creates a SVG file and

00:08:28.600 --> 00:08:33.213
it creates an arrow between all the nodes that are linked.

00:08:33.214 --> 00:08:36.199
It puts a title up there when the node has more than two links

00:08:36.200 --> 00:08:39.599
going in or out. We can also click on the note to read it in

00:08:39.600 --> 00:08:43.679
the browser, if you choose. If you set up Firefox properly,

00:08:43.680 --> 00:08:49.639
I'm sure it can also go into Emacs. This is the note tagging

00:08:49.640 --> 00:08:54.580
that's available within EWS.

NOTE Writing with Org

00:08:54.581 --> 00:08:57.021
Now, we've taken all these notes. Now we need to

00:08:57.022 --> 00:09:00.518
start writing stuff. Org mode, for me,

00:09:00.519 --> 00:09:03.559
is the ideal tool. Org mode is what you see is what you

00:09:03.560 --> 00:09:06.919
mean. The text and the syntax instruct the computer on how to

00:09:06.920 --> 00:09:10.479
produce the final result. This means that one file can

00:09:10.480 --> 00:09:12.879
become many different formats, an e-book, a printed book,

00:09:12.880 --> 00:09:16.759
or a website. It doesn't matter. Now, a lot of people talk

00:09:16.760 --> 00:09:18.959
about what you see, what you get, and that we should have a

00:09:18.960 --> 00:09:21.079
what you see, what you get mode in Emacs. I think that's

00:09:21.080 --> 00:09:24.799
irrelevant, because showing the final result while you're

00:09:24.800 --> 00:09:28.639
writing is actually a distraction. Traditional writing,

00:09:28.640 --> 00:09:31.359
producing the content, and designing the layout and

00:09:31.360 --> 00:09:34.119
typesetting are separate processes done by different

00:09:34.120 --> 00:09:38.079
professionals. In Emacs Writing Studio, the writing is

00:09:38.080 --> 00:09:40.359
still done by a human. There are no provisions for large

00:09:40.360 --> 00:09:45.039
language models in EWS. But layout and typesetting is done

00:09:45.040 --> 00:09:49.599
by external software, be it CSS, LaTeX, or XML, all mediated

00:09:49.600 --> 00:09:50.359
by Org mode.

00:09:50.360 --> 00:09:57.399
EWS also has some other tools for case conversion,

00:09:57.400 --> 00:09:59.799
thesaurus, a dictionary that I haven't got time to show,

00:09:59.800 --> 00:10:02.909
but what I will show you is how the book functions,

00:10:02.910 --> 00:10:05.919
and then how we create these publications.

NOTE The project file

00:10:05.920 --> 00:10:11.639
Okay. Let's go to my project file.

00:10:11.640 --> 00:10:17.058
So these are the EWS chapters,

00:10:17.059 --> 00:10:20.200
and each chapter is an Org mode file.

00:10:20.201 --> 00:10:25.079
Let's go into the main document, which is set up with

00:10:25.080 --> 00:10:30.359
olivetti-mode just to make it easier to read. What we see

00:10:30.360 --> 00:10:34.839
here is all the fluff from Org mode. These are all the

00:10:34.840 --> 00:10:37.719
various bits of metadata that I used to create the final

00:10:37.720 --> 00:10:43.439
result. Then for each chapter, I have an inclusion.

00:10:43.440 --> 00:10:46.721
This references another file. I've got some properties.

00:10:46.722 --> 00:10:49.839
In this case, the forward is unnumbered. There's some notes.

00:10:49.840 --> 00:10:53.599
In this case, Prot actually wrote this for me. Then we

00:10:53.600 --> 00:10:59.039
can jump into that text. Then what we see at the bottom

00:10:59.040 --> 00:11:02.919
here is some inclusions for HTML. This is the EPUB version,

00:11:02.920 --> 00:11:07.159
but it's different in LaTeX. Again, the same file can

00:11:07.160 --> 00:11:09.479
serve different purposes.

00:11:09.480 --> 00:11:14.719
So now let's, as the final part of this demonstration,

00:11:14.720 --> 00:11:17.759
actually create the book, because the book's freely

00:11:17.760 --> 00:11:23.159
available. You can download the source files from GitHub,

00:11:23.160 --> 00:11:29.839
and you can roll your own. Let's open the dispatcher.

00:11:29.840 --> 00:11:33.468
We'll export the LaTeX and we want to open the file.

00:11:33.469 --> 00:11:37.349
Now this takes a minute because there's a lot happening within

00:11:37.350 --> 00:11:42.199
all this code, so I'll shorten this video. I'll be silent now.

00:11:42.200 --> 00:11:49.959
There we are. This is the Emacs Writing Studio PDF version,

00:11:49.960 --> 00:11:53.439
which will eventually become the interior for the

00:11:53.440 --> 00:11:55.159
paperback version.

00:11:55.160 --> 00:12:02.399
So the EWS book is available in all major e-book shops.

00:12:02.400 --> 00:12:05.319
I'm also working on a paperback, which I hope to finish when

00:12:05.320 --> 00:12:09.279
Emacs 30 comes out. But the Org Mode files that I use to

00:12:09.280 --> 00:12:11.039
produce the book, they're available in the GitHub

00:12:11.040 --> 00:12:13.999
repository, so you can also roll your own, because the EWS

00:12:14.000 --> 00:12:18.719
configuration is the one that I use to produce the book.

NOTE Conclusions

00:12:18.720 --> 00:12:22.799
Now, some conclusions from this journey is that the best way to

00:12:22.800 --> 00:12:26.239
learn is to teach. That was my personal objective. I

00:12:26.240 --> 00:12:28.599
learned a lot from systematically working out how to

00:12:28.600 --> 00:12:33.559
implement the EWS workflow. One of the surprising things

00:12:33.560 --> 00:12:35.759
that I learned is to have reliance on external software

00:12:35.760 --> 00:12:39.359
throughout the writing process. I spent a lot of time in

00:12:39.360 --> 00:12:42.159
the book about explaining these connections that Emacs is

00:12:42.160 --> 00:12:46.399
not just a text processor, it is also an interface with other

00:12:46.400 --> 00:12:49.599
software. Now, future developments, as I mentioned,

00:12:49.600 --> 00:12:52.119
there'll be a paperback version of the book when Emacs 30

00:12:52.120 --> 00:12:55.959
comes out, and I might reconfigure things a little bit. I'm

00:12:55.960 --> 00:12:58.719
only planning to update the configuration when packages

00:12:58.720 --> 00:13:04.639
break or with another major Emacs release, because I want to

00:13:04.640 --> 00:13:08.079
work with Emacs, not work on Emacs. A big thank you to

00:13:08.080 --> 00:13:11.199
Prot Stavrou, who helped me with Denote packages, and he

00:13:11.200 --> 00:13:14.999
also wrote the forward to the book. There's also several

00:13:15.000 --> 00:13:18.119
test readers that I met through Mastodon that helped me out

00:13:18.120 --> 00:13:20.719
quite a bit. Of course, all the Emacs and package

00:13:20.720 --> 00:13:25.519
developers without which none of this would exist. Thank

00:13:25.520 --> 00:13:27.559
you all for your attention, and I look forward to your

00:13:27.560 --> 00:13:30.720
questions and suggestions.