summaryrefslogblamecommitdiffstats
path: root/2021/captions/emacsconf-2021-tech--creating-technical-documentation-and-presentations-using-org-babel-restclient-and-org-treeslide--jan-ypma--main.vtt
blob: 8e5b49fb541e1f76c76073919ff94f71bc5718b9 (plain) (tree)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
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.