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