1 files changed, 829 insertions, 0 deletions

diff --git a/2021/captions/emacsconf-2021-tech--creating-technical-documentation-and-presentations-using-org-babel-restclient-and-org-treeslide--jan-ypma--main.vtt b/2021/captions/emacsconf-2021-tech--creating-technical-documentation-and-presentations-using-org-babel-restclient-and-org-treeslide--jan-ypma--main.vtt
new file mode 100644
index 00000000..8e5b49fb
--- /dev/null
+++ b/2021/captions/emacsconf-2021-tech--creating-technical-documentation-and-presentations-using-org-babel-restclient-and-org-treeslide--jan-ypma--main.vtt
@@ -0,0 +1,829 @@
+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.