WEBVTT
00:02.560 --> 00:05.040
Hi! My name is Jan, and I'll be talking
00:05.040 --> 00:07.680
about using Emacs for technical writing.
00:07.680 --> 00:09.519
Let's first define what we mean by
00:09.519 --> 00:12.080
technical writing.
00:12.080 --> 00:13.679
At least, I mean with that, any kind of
00:13.679 --> 00:15.759
writing that involves computer systems.
00:15.759 --> 00:19.700
So, maybe a developer guide for a system,
00:19.700 --> 00:21.680
or a library you've been creating,
00:21.680 --> 00:23.433
maybe reference documentation
00:23.433 --> 00:25.833
or a user guide for a REST API
00:25.833 --> 00:27.934
that you offer as a cloud service,
00:27.934 --> 00:29.767
or doing a technical presentation
00:29.767 --> 00:30.700
exactly like this one
00:30.700 --> 00:32.239
that may actually include some live
00:32.239 --> 00:34.000
coding as well that you may want to do
00:34.000 --> 00:36.000
while you're showing the presentation
00:36.000 --> 00:39.040
without too much context switching.
00:39.040 --> 00:40.399
I've been doing a variety of these
00:40.399 --> 00:43.034
things in my professional life for a while now,
00:43.034 --> 00:43.840
and I found Emacs to be a
00:43.840 --> 00:46.879
really nice tool to help out with that,
00:46.879 --> 00:50.719
since it actually pulls in different languages.
00:50.719 --> 00:52.800
The ones I work with is Scala, Java, C++,
00:52.800 --> 00:54.480
and things like that, and everything
00:54.480 --> 00:56.160
works in the same way within Emacs,
00:56.160 --> 00:58.300
so you don't have to learn different tools
00:58.400 --> 00:59.840
to do the same thing.
00:59.840 --> 01:02.079
Doing all of this against Java looks the
01:02.079 --> 01:04.720
same as it would but with C++ except
01:04.720 --> 01:07.119
the language is different.
01:07.119 --> 01:08.640
A little refresher for people that might
01:08.640 --> 01:10.666
be viewing this out of context.
01:10.666 --> 01:13.280
Emacs is a very customizable text editor
01:13.280 --> 01:15.600
environment, and Org mode is a
01:15.600 --> 01:17.360
part of Emacs that allows you to deal
01:17.360 --> 01:18.734
with structured text.
01:18.734 --> 01:21.920
So, a plain text file containing headings,
01:21.920 --> 01:25.439
lists, tables, and even code blocks
01:25.439 --> 01:27.360
formatted in a particular way, so Org
01:27.360 --> 01:29.866
mode can help out with that.
01:29.866 --> 01:32.560
And Org babel is the particular part of Org mode
01:32.560 --> 01:34.400
that deals with executing those code
01:34.400 --> 01:37.000
blocks and actually interacting with,
01:37.000 --> 01:38.720
say, a Java or a Python environment
01:38.720 --> 01:40.720
underneath, and showing the results of
01:40.720 --> 01:43.840
that right inside the same Org file.
01:43.840 --> 01:44.966
Let's look at
01:44.966 --> 01:47.167
what are a couple of scenarios
01:47.167 --> 01:49.400
using this might actually look like.
01:49.400 --> 01:52.533
Let's start with imagining that
01:52.533 --> 01:55.000
we are writing a developer guide
01:55.000 --> 01:59.439
for a service or a library,
01:59.439 --> 02:02.560
or a computer program that we might be writing.
02:02.560 --> 02:04.560
And, imagine that we have some
02:04.560 --> 02:07.119
dependencies that the program requires
02:07.119 --> 02:09.520
that are configured using docker-compose,
02:09.520 --> 02:11.767
for those who don't know Docker, docker-compose,
02:11.767 --> 02:15.599
it's a way to quickly describe some Linux
02:15.599 --> 02:17.920
programs that can be immediately run
02:17.920 --> 02:21.280
without installing too much dependencies.
02:21.280 --> 02:23.040
You define these using a YAML file
02:23.040 --> 02:25.040
called the docker-compose file.
02:25.040 --> 02:26.959
Now, here inside Emacs we have a block
02:26.959 --> 02:29.280
that defines a YAML file, and we're
02:29.280 --> 02:30.900
actually saying this is called
02:30.900 --> 02:33.840
docker-compose.yaml
02:33.840 --> 02:36.400
with some content here, and you can see
02:36.400 --> 02:38.200
that even though we are in Org mode,
02:38.200 --> 02:40.959
Org mode knows that it can highlight this
02:40.959 --> 02:43.360
according to YAML and Org mode doesn't
02:43.360 --> 02:45.200
directly know about YAML, we just said hey
02:45.200 --> 02:47.360
this block has to do with YAML.
02:47.360 --> 02:51.467
Because there's a yaml-mode in Emacs,
02:51.467 --> 02:53.280
it will borrow from that mode to actually
02:53.280 --> 02:55.920
highlight this block.
02:55.920 --> 02:57.680
Now, the fun thing is that there's a
02:57.680 --> 03:00.080
feature in Org called tangling that
03:00.080 --> 03:02.159
allows you to take these kinds of blocks
03:02.159 --> 03:04.800
and actually export them to separate files.
03:04.800 --> 03:06.959
So, if we look at the
03:06.959 --> 03:08.720
directory that we're in right now, we see
03:08.720 --> 03:10.434
that we just got the presentation,
03:10.434 --> 03:12.239
there is no docker-compose file yet.
03:12.239 --> 03:16.000
If I say Control c Control v t (C-c C-v t)
03:16.000 --> 03:18.080
and I go back and refresh this directory,
03:18.080 --> 03:20.200
now we have a docker-compose file as well,
03:20.200 --> 03:22.000
which has the content in it that we
03:22.000 --> 03:23.334
just created here.
03:23.334 --> 03:25.200
That's very nice because
03:25.200 --> 03:26.560
conceptually we don't actually need to
03:26.560 --> 03:28.080
leave Org mode, we can say something
03:28.080 --> 03:29.760
about this file and have the contents of
03:29.760 --> 03:32.480
the file in the same descriptive document
03:32.480 --> 03:34.966
while also having some actual side effect
03:34.966 --> 03:36.159
of the file existing on disk and
03:36.159 --> 03:38.000
us being able to interact with it.
03:38.000 --> 03:40.000
For example, we could…, now that the file is
03:40.000 --> 03:42.319
there, invoke docker-compose and actually
03:42.319 --> 03:44.400
create the nginx web server that we're
03:44.400 --> 03:46.700
defining here. Let's do that.
03:46.700 --> 03:47.120
We have a little block
03:47.120 --> 03:49.599
here that runs the shell script if I
03:49.599 --> 03:51.920
invoke that from Org mode, we get the
03:51.920 --> 03:53.439
results here, we see that now we have a
03:53.439 --> 03:55.867
web server running on port 8080.
03:55.867 --> 03:56.767
That's, by the way,
03:56.767 --> 03:58.319
serving up the contents of
03:58.319 --> 04:00.799
the directory that we're in here
04:00.799 --> 04:02.799
on port 8080.
04:02.799 --> 04:06.000
So, that's already quite nice.
04:06.000 --> 04:08.959
Let's look at another scenario where we
04:08.959 --> 04:11.760
may be documenting a REST API.
04:11.760 --> 04:14.720
REST APIs use a lot of HTTP interactions
04:14.720 --> 04:17.199
typically describing an XML or JSON
04:17.199 --> 04:20.000
structure and which HTTP verb GET or PUT
04:20.000 --> 04:22.320
to use with that and the URL.
04:22.320 --> 04:25.919
There's actually a nice extension to
04:25.919 --> 04:28.240
Org babel called rest client that you
04:28.240 --> 04:30.000
can install, that allows you to describe
04:30.000 --> 04:33.360
these kind of requests right inside Emacs.
04:33.360 --> 04:35.360
First, let's make sure that our HTTP
04:35.360 --> 04:36.720
server has something to respond with,
04:36.720 --> 04:38.080
that's a little interesting, for example,
04:38.080 --> 04:40.433
an XML file. We already know how to do that.
04:40.433 --> 04:42.533
So, let's create a code block type xml
04:42.533 --> 04:43.600
that we can tangle to file called
04:43.600 --> 04:46.960
test.xml, Control c Control v t (C-c C-v t).
04:46.960 --> 04:52.067
Now, if we look at the directory again,
04:52.067 --> 04:55.120
we have a test.xml file.
04:55.120 --> 04:57.520
And, now we can have a new type of block
04:57.520 --> 04:59.600
called the restclient, which will invoke
04:59.600 --> 05:01.199
REST client, and anything you type into
05:01.199 --> 05:04.160
here will be sent as an HTTP request to
05:04.160 --> 05:05.600
the server that you specify.
05:05.600 --> 05:08.880
Right now it goes to localhost on 8080 and
05:08.880 --> 05:10.720
let's see if we can get our test.xml
05:10.720 --> 05:11.433
file back.
05:11.433 --> 05:13.600
I've just invoked this, and you can see
05:13.600 --> 05:16.479
we got the spec and the content type of
05:16.479 --> 05:17.680
the server, if we scroll down a little
05:17.680 --> 05:19.199
bit I think we see the headers here, yeah,
05:19.199 --> 05:22.080
so the server said it's text/xml and
05:22.080 --> 05:23.759
restclient is smart enough to actually
05:23.759 --> 05:27.966
invoke Emacs's sgml-mode to highlight it.
05:27.966 --> 05:28.639
I'm not exactly sure
05:28.639 --> 05:31.039
what's the difference is between sxml
05:31.039 --> 05:33.680
and xml-mode and there's a nxml-mode,
05:33.680 --> 05:35.600
they all pretty much know how to deal
05:35.600 --> 05:38.800
with XML. In this case sgml was
05:38.800 --> 05:41.600
chosen, which is fine.
05:41.600 --> 05:42.960
But you can see we just served up that
05:42.960 --> 05:45.680
test.xml file, and
05:45.680 --> 05:46.880
we can have some actual text here
05:46.880 --> 05:48.639
describing "Hey, if you do this request
05:48.639 --> 05:50.734
you might get a response like that,"
05:50.734 --> 05:53.199
and the server will actually serve that up
05:53.199 --> 05:56.233
and insert it right into the Org mode document.
05:56.233 --> 05:57.759
By the way, we're looking at
05:57.759 --> 06:00.720
this now inside Emacs rendered somewhat
06:00.720 --> 06:02.479
interestingly, but obviously you can
06:02.479 --> 06:05.280
export this to a PDF, or HTML, or in all
06:05.280 --> 06:06.880
sorts of nice and different ways as well
06:06.880 --> 06:09.759
depending on what your particular needs are.
06:09.759 --> 06:11.520
Of course, we can't just send GET
06:11.520 --> 06:14.080
requests, we can send PUT requests as
06:14.080 --> 06:16.400
well, and just like in plain HTTP you
06:16.400 --> 06:19.120
have the PUT method on the first line then
06:19.120 --> 06:20.600
your headers, and a blank line,
06:20.600 --> 06:22.000
and then the body.
06:22.000 --> 06:24.720
If we try and invoke this then
06:24.720 --> 06:27.440
nginx will say "405 Not Allowed"
06:27.440 --> 06:29.199
because, obviously, just running a plain
06:29.199 --> 06:30.319
web server will not allow you to
06:30.319 --> 06:32.080
actually upload any files,
06:32.080 --> 06:33.440
but this of course could have been any
06:33.440 --> 06:36.800
other response as well.
06:36.800 --> 06:39.759
Now, let's look at doing
06:39.759 --> 06:41.600
presentations themselves, like the one
06:41.600 --> 06:42.867
you're looking at.
06:42.867 --> 06:45.766
There's a package that I like to use a lot,
06:45.766 --> 06:47.520
which is called org-tree-slide.
06:47.520 --> 06:49.759
That's the one that's active right now,
06:49.759 --> 06:52.080
which takes an Org document and allows
06:52.080 --> 06:54.600
you to show one heading at a time.
06:54.600 --> 06:55.599
It doesn't matter whether it's the first
06:55.599 --> 06:57.280
level, second level, third level heading,
06:57.280 --> 07:00.319
they sort of fold into nice
07:00.319 --> 07:02.720
things at the top,
07:02.720 --> 07:03.919
where you can
07:03.919 --> 07:05.366
sort of go through a document
07:05.366 --> 07:07.680
one piece at a time.
07:07.680 --> 07:10.367
I actually do like to use
07:10.367 --> 07:12.319
Org babel at the same time to
07:12.319 --> 07:14.479
do some live coding in it as well.
07:14.479 --> 07:16.800
Actually there are two ways to go to a PDF,
07:16.800 --> 07:20.720
you can just use the normal Org export
07:20.720 --> 07:22.733
option to go to a PDF, which is
07:22.733 --> 07:25.120
Control c Control e, and then l p (C-c C-e l p),
07:25.120 --> 07:27.520
but if you use restclient, the
07:27.520 --> 07:30.960
LaTeX file underneath sometimes gets
07:30.960 --> 07:33.280
a little wonky because those things
07:33.280 --> 07:34.866
don't directly work together.
07:34.866 --> 07:36.166
I wrote a little bit of Lisp
07:36.166 --> 07:37.039
to help out with that,
07:37.039 --> 07:38.880
which you can look at if you check
07:38.880 --> 07:40.960
out my presentation later.
07:40.960 --> 07:45.919
There's another package for Org babel called
07:45.919 --> 07:48.800
beamer, or ox-beamer it's called,
07:48.800 --> 07:51.680
which uses a LaTeX style called beamer
07:51.680 --> 07:53.360
to create a PDF,
07:53.360 --> 07:57.400
and that one looks sort of…,
07:57.400 --> 07:58.000
that one tries to actually
07:58.000 --> 07:59.840
create one page per slide which you
07:59.840 --> 08:01.039
would actually have a PDF with the
08:01.039 --> 08:03.280
slides, but that one is a lot more picky
08:03.280 --> 08:06.160
on what your Org file is
08:06.160 --> 08:07.440
structured like, so you need to have all
08:07.440 --> 08:08.879
your leaf headings at the same level,
08:08.879 --> 08:11.360
which I typically don't do.
08:11.360 --> 08:12.800
So, I can show you what this one
08:12.800 --> 08:16.639
looks like.
08:16.639 --> 08:18.240
For this presentation you get a nice
08:18.240 --> 08:20.067
title slide, and then you get…,
08:20.067 --> 08:21.167
it tries to make an outline,
08:21.167 --> 08:23.360
which is the one level above.
08:23.360 --> 08:26.319
The slides sort of look okay, but as
08:26.319 --> 08:28.479
you go further they sort of start
08:28.479 --> 08:31.680
to run into, you know,
08:31.680 --> 08:34.633
things not flowing as they should.
08:34.633 --> 08:36.800
I'm sure with a lot more LaTeX
08:36.800 --> 08:37.919
knowledge you could make this
08:37.919 --> 08:40.640
look a lot nicer, but personally I tend
08:40.640 --> 08:44.080
to just create a normal PDF document
08:44.080 --> 08:46.399
that's just, you know, text
08:46.399 --> 08:48.560
with all the actual content of the
08:48.560 --> 08:50.560
document. Inside the text you can see the
08:50.560 --> 08:52.880
highlighting of especially restclient
08:52.880 --> 08:55.920
stuff that works just fine, and
08:55.920 --> 08:57.400
it's enough for my needs,
08:57.400 --> 09:00.959
so I just tend to make plain PDFs.
09:00.959 --> 09:02.959
Since we only have 10 minutes, I will
09:02.959 --> 09:05.200
not go into the detailed configuration,
09:05.200 --> 09:06.800
you can check out the presentation
09:06.800 --> 09:09.440
online to see how all these packages are
09:09.440 --> 09:13.440
configured and how I use them,
09:13.440 --> 09:18.000
but for now that's all I have.
09:18.000 --> 09:20.000
I do recommend you try this out yourself.
09:20.000 --> 09:22.240
If you have any kind of documentation
09:22.240 --> 09:24.399
or textual things to do,
09:24.399 --> 09:26.320
just pick one of these packages at a
09:26.320 --> 09:27.519
time, integrate them into your
09:27.519 --> 09:29.200
configuration if you haven't already.
09:29.200 --> 09:31.040
That's really the best way to go
09:31.040 --> 09:32.959
about this, and you know, Google is your
09:32.959 --> 09:34.240
friend, if you think "Hey how I would do
09:34.240 --> 09:35.467
this with these packages,"
09:35.567 --> 09:37.839
definitely do that.
09:37.839 --> 09:41.760
More things I will be looking at is
09:41.760 --> 09:44.000
using this concept to write unit or
09:44.000 --> 09:45.360
integration tests, you can imagine if you
09:45.360 --> 09:47.600
have a documentation in Org mode that
09:47.600 --> 09:50.800
describes your service as a
09:50.800 --> 09:53.360
function of its REST API, you may want to
09:53.360 --> 09:55.040
actually run all those commands as part
09:55.040 --> 09:56.480
of your build and check if all the
09:56.480 --> 09:58.399
documentation is still in order.
09:58.399 --> 09:59.680
I'm not doing that yet, but I'm
09:59.680 --> 10:01.033
definitely looking into that.
10:01.133 --> 10:03.667
I'm also writing some extensions
10:03.767 --> 10:06.000
to use Java and Scala
10:06.000 --> 10:08.720
in a somewhat higher level with Org mode.
10:08.720 --> 10:11.680
But that's not entirely working yet,
10:11.680 --> 10:12.959
and we don't have time to go into that
10:12.959 --> 10:14.240
today.
10:14.240 --> 10:16.666
That's it. Thanks a lot for your attention,
10:16.766 --> 10:21.880
and I'll be there for questions later.
