path: root/2021/captions/emacsconf-2021-tech--creating-technical-documentation-and-presentations-using-org-babel-restclient-and-org-treeslide--jan-ypma--main.vtt

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.