summaryrefslogtreecommitdiffstats
path: root/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard.vtt
blob: 72962cf13b7581ae4a84c7c83e35ffcb4e77312e (plain) (blame)
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
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
WEBVTT

00:00:03.600 --> 00:00:04.400
Adam: Hello!

00:00:04.400 --> 00:00:06.560
Welcome to Readme Driven Design in Emacs

00:00:06.560 --> 00:00:08.400
by Adam Aard.

00:00:08.400 --> 00:00:10.800
If you're a programmer, you're accustomed

00:00:10.800 --> 00:00:12.559
to putting a README file at the root of

00:00:12.559 --> 00:00:13.759
your project.

00:00:13.759 --> 00:00:15.845
It's usually a Markdown file

00:00:15.845 --> 00:00:20.579
But if you use an Org Mode file instead,

00:00:20.579 --> 00:00:22.560
you can take advantage of the
great features

00:00:22.560 --> 00:00:24.400
that Org Mode provides, including

00:00:24.400 --> 00:00:25.920
literate programming,

00:00:25.920 --> 00:00:28.000
which lets you generate your source code

00:00:28.000 --> 00:00:31.840
and Markdown documentation dynamically.

00:00:31.840 --> 00:00:34.719
I want to walk you through a little bit

00:00:34.719 --> 00:00:37.120
of what this looks like.

00:00:37.120 --> 00:00:39.440
When you start a project, especially if

00:00:39.440 --> 00:00:41.280
if you use something like Github you

00:00:41.280 --> 00:00:43.320
begin with an automatically generated

00:00:43.320 --> 00:00:47.039
README.md file. So just delete that

00:00:47.039 --> 00:00:50.239
and instead create a README.org file.

00:00:50.239 --> 00:00:51.712
Starting with an empty Org file,

00:00:51.712 --> 00:00:54.800
like you see here, you can begin

00:00:54.800 --> 00:00:56.559
by recording important information about

00:00:56.559 --> 00:00:59.440
your project goals. You can add diagrams,

00:00:59.440 --> 00:01:01.920
code snippets, to-do lists, time tracking

00:01:01.920 --> 00:01:03.520
and much more.

00:01:03.520 --> 00:01:05.360
I'm going to drop in some documentation

00:01:05.360 --> 00:01:07.760
that that I've written about

00:01:07.760 --> 00:01:12.240
about my project here, so you can see

00:01:12.240 --> 00:01:15.280
what this would look like.

00:01:15.280 --> 00:01:17.119
As you can see, I have a title, and a

00:01:17.119 --> 00:01:20.320
description, and then a subsection

00:01:20.320 --> 00:01:23.840
as well as some code snippets.

00:01:23.840 --> 00:01:25.520
You can see that Org Mode does a great

00:01:25.520 --> 00:01:28.240
job of formatting lists,

00:01:28.240 --> 00:01:31.280
code sections, diagrams, and so forth.

00:01:31.280 --> 00:01:35.040
It's as good or better than Markdown,

00:01:35.040 --> 00:01:37.179
but when you use it in Emacs

00:01:37.179 --> 00:01:38.880
you can do a lot more.

00:01:38.880 --> 00:01:40.479
For example, you can dynamically create

00:01:40.479 --> 00:01:43.360
diagrams using Graphviz

00:01:43.360 --> 00:01:45.200
from a text description. If you go to

00:01:45.200 --> 00:01:46.560
this source block here

00:01:46.560 --> 00:01:49.439
and hit C-c C-c, you'll see

00:01:49.439 --> 00:01:52.979
that we generate a diagram dynamically

00:01:55.439 --> 00:01:59.200
You can run these code snippets in

00:01:59.200 --> 00:02:00.799
place and get the results

00:02:00.799 --> 00:02:03.040
to show up inside of your file,

00:02:03.040 --> 00:02:08.000
which is a really powerful paradigm.

00:02:08.000 --> 00:02:10.640
But most importantly, for

00:02:10.640 --> 00:02:14.800
my purposes here,

00:02:14.800 --> 00:02:17.200
Org Mode provides you the ability to do

00:02:17.200 --> 00:02:19.520
literate programming.

00:02:19.520 --> 00:02:21.440
So take a quick look at this diagram

00:02:21.440 --> 00:02:23.200
that I generated here.

00:02:23.200 --> 00:02:25.312
It gives you a quick overview of what

00:02:25.312 --> 00:02:27.520
I mean by literate programming

00:02:27.520 --> 00:02:31.200
and how I'm using it. You can see

00:02:31.200 --> 00:02:34.720
that we start with a README.org file
on top.

00:02:34.720 --> 00:02:37.920
At this point, we can do one of two
things:

00:02:37.920 --> 00:02:41.280
tangle or weave. Tangle is used to

00:02:41.280 --> 00:02:42.720
describe the process of

00:02:42.720 --> 00:02:46.319
generating source code, while weave

00:02:46.319 --> 00:02:47.599
is the process of generating

00:02:47.599 --> 00:02:49.840
documentation. These are terms that

00:02:49.840 --> 00:02:51.920
Donald Knuth used.

00:02:51.920 --> 00:02:53.840
He's the one that came up with the

00:02:53.840 --> 00:02:55.519
idea of literate programming

00:02:55.519 --> 00:02:59.920
in the early 1980s.

00:02:59.920 --> 00:03:01.945
But this is really all that there is to
it.

00:03:01.945 --> 00:03:05.412
You just... You are simply

00:03:05.412 --> 00:03:07.840
using a literate source file,

00:03:07.840 --> 00:03:10.319
in this case the README.org, to generate

00:03:11.680 --> 00:03:17.120
the rest of the project files, basically.

00:03:17.120 --> 00:03:22.640
So let's dig in to the details of how
this works.

00:03:22.640 --> 00:03:24.560
I hope you... Hopefully you'll see how

00:03:24.560 --> 00:03:26.159
cool this is.

00:03:26.159 --> 00:03:27.545
So returning to the file here.

00:03:27.545 --> 00:03:31.120
Let's assume we have enough
documentation now,

00:03:31.120 --> 00:03:32.679
that we want to get started
coding.

00:03:32.679 --> 00:03:34.159
So maybe we'll just start with

00:03:34.159 --> 00:03:35.845
like a Hello World app,

00:03:35.845 --> 00:03:38.159
just so we can make sure that our

00:03:38.159 --> 00:03:41.519
environment is set up correctly.

00:03:41.519 --> 00:03:47.120
Let's get started with a code block.

00:03:47.120 --> 00:03:49.519
So I created a little snippet to help me

00:03:49.519 --> 00:03:51.612
add a source block for

00:03:51.612 --> 00:03:53.599
literate programming quickly.

00:03:53.599 --> 00:03:56.959
There's not much to it,

00:03:56.959 --> 00:03:59.479
but there are some important annotations
here.

00:04:01.599 --> 00:04:04.080
Excuse me. There's a property

00:04:04.080 --> 00:04:05.200
called :tangle

00:04:05.200 --> 00:04:09.360
and that takes a value of a file name.

00:04:09.360 --> 00:04:13.280
Then there's also a :noweb property

00:04:13.280 --> 00:04:18.880
called no-export.

00:04:23.759 --> 00:04:26.800
Basically, the noexport--we'll explain

00:04:26.800 --> 00:04:29.645
that a little bit more later

00:04:29.645 --> 00:04:32.080
It has to do with how

00:04:32.080 --> 00:04:36.845
the tangling is done in the tangle
step

00:04:36.845 --> 00:04:38.479
versus the weave step.

00:04:38.479 --> 00:04:40.212
I'll explain that a little bit more.

00:04:40.212 --> 00:04:45.199
But the tangle field just simply tells

00:04:45.199 --> 00:04:48.320
Emacs where it needs to generate the

00:04:48.320 --> 00:04:50.320
main.go file and where it needs to put

00:04:50.320 --> 00:04:55.360
it on the file system.

00:04:55.360 --> 00:04:57.680
You'll notice that we we're

00:04:57.680 --> 00:04:59.040
going to use Go.

00:04:59.040 --> 00:05:01.440
That's just the language that I've been

00:05:01.440 --> 00:05:03.379
using the most lately,

00:05:03.379 --> 00:05:06.845
but this programming strategy

00:05:06.845 --> 00:05:08.400
is language-agnostic.

00:05:08.400 --> 00:05:11.279
You could use any language

00:05:11.279 --> 00:05:13.145
or any mix of languages.

00:05:13.145 --> 00:05:14.720
You could create some files

00:05:14.720 --> 00:05:16.560
in Python, some files in Go,

00:05:16.560 --> 00:05:19.179
some files in Lisp,

00:05:19.179 --> 00:05:21.520
or whatever you want.

00:05:24.720 --> 00:05:29.440
Let's create just a little
Hello World.

00:05:29.440 --> 00:05:31.379
Let's use another snippet here

00:05:31.379 --> 00:05:36.560
to generate the basics of a Go program.

00:05:36.560 --> 00:05:40.240
I'm just going to print

00:05:40.240 --> 00:05:44.960
Hello World.

00:05:44.960 --> 00:05:48.560
So that's... And then

00:05:48.560 --> 00:05:52.779
let's make it a section in our file.

00:05:52.779 --> 00:05:55.045
So now you can see, we've got

00:05:55.045 --> 00:05:56.400
this snippet.

00:05:56.400 --> 00:05:59.600
When you have a source block in

00:05:59.600 --> 00:06:01.600
inside of Org Mode, you can easily pop

00:06:01.600 --> 00:06:04.960
into a language-specific buffer
by typing

00:06:04.960 --> 00:06:07.680
C-c ' (single quote).

00:06:07.680 --> 00:06:10.240
So you can see, now I have a

00:06:10.240 --> 00:06:12.160
buffer that's in go-mode

00:06:12.160 --> 00:06:14.240
and gives you all the ability to edit

00:06:14.240 --> 00:06:15.520
like you would

00:06:15.520 --> 00:06:19.945
normally. If you hit C-c '
(single quote)

00:06:19.945 --> 00:06:20.800
again, it goes back and

00:06:20.800 --> 00:06:25.045
any changes you make will be
updated there.

00:06:25.045 --> 00:06:26.160
But you can do quite a bit

00:06:26.160 --> 00:06:27.879
just inside of here too.

00:06:27.879 --> 00:06:29.199
There's quite a bit of

00:06:29.199 --> 00:06:34.479
language-specific functionality

00:06:34.479 --> 00:06:35.312
just in place,

00:06:35.312 --> 00:06:36.880
so you don't always have to go over to a

00:06:36.880 --> 00:06:38.080
separate buffer.

00:06:38.080 --> 00:06:42.319
It's a nice option sometimes.

00:06:42.319 --> 00:06:44.319
Now that you have the code in here,

00:06:44.319 --> 00:06:46.720
you're going to want to run it.

00:06:46.720 --> 00:06:48.179
Right now, it just lives here

00:06:48.179 --> 00:06:50.240
in this documentation.

00:06:50.240 --> 00:06:52.160
You need to get a copy of it into a

00:06:52.160 --> 00:06:53.840
separate file,

00:06:53.840 --> 00:06:57.440
and that's the tangle process that you

00:06:57.440 --> 00:07:01.360
you need to follow there. So I'm gonna

00:07:01.360 --> 00:07:03.360
drop in a little bit more doc, a little

00:07:03.360 --> 00:07:12.240
bit more documentation really quick here.

00:07:12.240 --> 00:07:19.112
Okay, all right. So just as a side note,

00:07:19.112 --> 00:07:22.845
I like to follow this process.

00:07:22.845 --> 00:07:26.639
Whenever I have an operation to perform,

00:07:26.639 --> 00:07:28.880
I'd like to document it here with a

00:07:28.880 --> 00:07:31.680
snippet that can be executed inline.

00:07:31.680 --> 00:07:33.280
Then I don't have to leave Org Mode, and

00:07:33.280 --> 00:07:34.639
I don't have to try to remember what I

00:07:34.639 --> 00:07:36.800
did later. So instead of just

00:07:36.800 --> 00:07:38.960
trying to do an operation, the first time

00:07:38.960 --> 00:07:40.319
I do something,

00:07:40.319 --> 00:07:41.680
I take the time to figure out what it is

00:07:41.680 --> 00:07:44.879
and document it, so then it's
recorded.

00:07:44.879 --> 00:07:49.120
So here we find that to do a tangle
operation,

00:07:49.120 --> 00:07:51.680
you run the command org-babel-tangle,

00:07:51.680 --> 00:07:53.779
which is an Elisp command.

00:07:53.779 --> 00:07:58.712
If you hit C-c C-c to run it in place,

00:07:58.712 --> 00:08:00.080
you get the result

00:08:00.080 --> 00:08:02.720
of main.go, which basically is

00:08:02.720 --> 00:08:03.759
telling us that

00:08:03.759 --> 00:08:07.680
we've tangled one file called main.go.

00:08:07.680 --> 00:08:11.039
You can see that's true

00:08:11.039 --> 00:08:12.879
if you go to the file system

00:08:12.879 --> 00:08:14.400
and you look.

00:08:14.400 --> 00:08:17.840
Now in our demo directory,

00:08:17.840 --> 00:08:19.712
we have a README.org,

00:08:19.712 --> 00:08:22.045
we have that PNG that we generated,

00:08:22.045 --> 00:08:23.440
but we also have a main.go.

00:08:23.440 --> 00:08:25.945
If you visit that file,

00:08:25.945 --> 00:08:27.045
you'll see that it's just

00:08:27.045 --> 00:08:28.212
the source code that was

00:08:28.212 --> 00:08:29.280
in our documentation, which is

00:08:29.280 --> 00:08:30.679
exactly what we expected

00:08:30.679 --> 00:08:32.880
and what we wanted. So that's good.

00:08:32.880 --> 00:08:41.120
So if we return to where we were at...

00:08:41.120 --> 00:08:42.959
Now we're at the point where we

00:08:42.959 --> 00:08:44.479
have a file on the file system.

00:08:45.760 --> 00:08:48.379
Now we need to build it

00:08:48.379 --> 00:08:49.612
and to run it.

00:08:49.612 --> 00:08:57.040
So let's follow the same philosophy,
where let's document

00:08:57.040 --> 00:09:00.160
these operations that we're going to
perform.

00:09:00.160 --> 00:09:04.560
I'm dropping in a

00:09:04.560 --> 00:09:07.112
a build instruction section

00:09:07.112 --> 00:09:13.360
and a run instruction section.

00:09:13.360 --> 00:09:15.279
As you can see here, we have a little

00:09:15.279 --> 00:09:17.839
a bash source block,

00:09:17.839 --> 00:09:19.245
and another bash source block.

00:09:19.245 --> 00:09:21.812
This one compiles. The go build command

00:09:21.812 --> 00:09:25.440
is what compiles a file. Then

00:09:25.440 --> 00:09:26.579
the file that gets generated

00:09:26.579 --> 00:09:30.080
should be called demo.

00:09:30.080 --> 00:09:32.412
So we just run it here.

00:09:32.412 --> 00:09:37.839
If I type C-c C-c, we get an
empty results block.

00:09:37.839 --> 00:09:38.979
When you compile things,

00:09:38.979 --> 00:09:41.360
no news is good news.

00:09:41.360 --> 00:09:43.012
It means there's no errors

00:09:43.012 --> 00:09:45.912
So presumably, we've created

00:09:45.912 --> 00:09:48.000
an executable that's called demo.

00:09:51.440 --> 00:09:53.312
Let's look again at the file system

00:09:53.312 --> 00:10:02.480
and regenerate...

00:10:02.480 --> 00:10:06.479
Yep. What we have here is a demo
executable,

00:10:06.479 --> 00:10:07.760
which is exactly what we
wanted.

00:10:07.760 --> 00:10:12.079
Let's go back.

00:10:12.079 --> 00:10:14.160
Now we should be able to run it.

00:10:14.160 --> 00:10:16.079
C-c C-c,

00:10:16.079 --> 00:10:20.399
and we get Hello World as a result,

00:10:20.399 --> 00:10:23.440
which was exactly what we were expecting.

00:10:23.440 --> 00:10:26.560
So that's already pretty cool.

00:10:26.560 --> 00:10:30.839
You can do that much.

00:10:33.040 --> 00:10:34.560
That's really just the tip of

00:10:34.560 --> 00:10:37.839
the iceberg. To really

00:10:41.040 --> 00:10:43.440
use the more impressive features of

00:10:43.440 --> 00:10:46.160
literate programming,

00:10:46.160 --> 00:10:49.920
we need to do a little bit more

00:10:53.200 --> 00:10:54.512
at least. Really,

00:10:54.512 --> 00:10:56.480
to get the full benefit of it,

00:10:56.480 --> 00:11:01.079
we need to add some sections

00:11:01.079 --> 00:11:04.412
that will cause Emacs to have to

00:11:04.412 --> 00:11:06.720
tangle or assemble

00:11:06.720 --> 00:11:09.760
this file from different pieces.

00:11:09.760 --> 00:11:13.120
Imagine that we wanted to take this file

00:11:13.120 --> 00:11:16.720
and maybe kind of templatize it.

00:11:16.720 --> 00:11:19.120
So, using literature programming syntax,

00:11:19.120 --> 00:11:21.279
this angle bracket syntax,

00:11:21.279 --> 00:11:24.399
let's say that we want to create an

00:11:24.399 --> 00:11:29.360
imports section,

00:11:29.360 --> 00:11:32.399
a functions section,

00:11:32.399 --> 00:11:35.040
and then maybe just a main section.

00:11:35.040 --> 00:11:36.240
We'll get rid of this.

00:11:36.240 --> 00:11:37.920
So now you see, we've created something

00:11:37.920 --> 00:11:39.760
that looks a little bit like a

00:11:39.760 --> 00:11:42.880
template or a scaffolding or outline

00:11:42.880 --> 00:11:45.812
for what our file is going to be.

00:11:45.812 --> 00:11:48.399
It looks a little bit like pseudocode.

00:11:48.399 --> 00:11:50.612
What we're going to have

00:11:50.612 --> 00:11:52.399
literate programming do

00:11:52.399 --> 00:11:54.800
is dynamically insert those things into

00:11:54.800 --> 00:11:56.639
those slots.

00:11:56.639 --> 00:12:00.079
So the first thing we need to do

00:12:00.079 --> 00:12:03.200
is... So let's create a section

00:12:03.200 --> 00:12:08.079
called "Say Hello."

00:12:08.079 --> 00:12:09.519
We want to add some functionality that

00:12:09.519 --> 00:12:12.720
makes our program say hello.

00:12:12.720 --> 00:12:15.680
So using a different snippet that I have

00:12:15.680 --> 00:12:17.600
for creating something

00:12:17.600 --> 00:12:20.800
that I call like a literate section,

00:12:20.800 --> 00:12:24.079
basically, we create a

00:12:24.079 --> 00:12:26.000
another source block that's almost the

00:12:26.000 --> 00:12:27.839
same as the one for the file.

00:12:27.839 --> 00:12:29.412
It just has a few differences

00:12:29.412 --> 00:12:34.079
Say we want to drop code into the import
section

00:12:34.079 --> 00:12:36.639
and we want it to be in Go.

00:12:36.639 --> 00:12:40.720
Here we use the same :noweb no-export syntax,

00:12:40.720 --> 00:12:44.560
but then we've added this :noweb-ref imports,

00:12:44.560 --> 00:12:48.240
and this ties that slot

00:12:48.240 --> 00:12:51.120
to this reference. It tells

00:12:51.120 --> 00:12:53.760
Emacs that when you tangle,

00:12:53.760 --> 00:12:55.479
we want to stick whatever's in here

00:12:55.479 --> 00:12:58.240
in that spot.

00:12:58.240 --> 00:13:02.079
You skip the tangle file name section

00:13:02.079 --> 00:13:03.279
because you're not actually creating a

00:13:03.279 --> 00:13:04.240
file name.

00:13:04.240 --> 00:13:06.160
You're putting information into an

00:13:06.160 --> 00:13:07.680
existing file.

00:13:07.680 --> 00:13:10.720
So here, we would just add the "fmt"

00:13:10.720 --> 00:13:14.399
for the imports.

00:13:14.399 --> 00:13:16.145
Let's add another section

00:13:16.145 --> 00:13:22.240
for functions.

00:13:22.240 --> 00:13:23.812
Let's just create a function

00:13:23.812 --> 00:13:28.079
called sayHello

00:13:28.079 --> 00:13:31.745
that doesn't have any arguments.

00:13:31.745 --> 00:13:34.000
No return types.

00:13:34.000 --> 00:13:35.760
All it does is pretty much the

00:13:35.760 --> 00:13:37.440
same thing as we did before:

00:13:37.440 --> 00:13:38.479
just print something.

00:13:38.479 --> 00:13:45.760
Let's just say "Hello EmacsConf"
this time.

00:13:45.760 --> 00:13:47.279
Now we have a function,

00:13:47.279 --> 00:13:50.779
and now the function won't do anything

00:13:50.779 --> 00:13:52.720
unless we invoke it. Let's do

00:13:52.720 --> 00:13:56.000
one last literate section

00:13:56.000 --> 00:13:59.920
called main. Make that Go

00:13:59.920 --> 00:14:03.519
source block. Then let's

00:14:03.519 --> 00:14:10.320
invoke that function.

00:14:10.320 --> 00:14:13.360
Now you can see that we've got

00:14:13.360 --> 00:14:15.600
our scaffolding

00:14:15.600 --> 00:14:17.199
outline, and then we have

00:14:17.199 --> 00:14:20.079
the sections that we want to get tangled

00:14:20.079 --> 00:14:21.360
or inserted.

00:14:21.360 --> 00:14:25.440
I've used this syntax.

00:14:25.440 --> 00:14:27.199
It's kinda borrowed from

00:14:27.199 --> 00:14:28.479
literate programming a little bit

00:14:28.479 --> 00:14:30.320
with a +=, so really it's just saying

00:14:30.320 --> 00:14:32.480
that I want to append

00:14:32.480 --> 00:14:35.760
this item into the import section

00:14:35.760 --> 00:14:37.600
It's really just to make a little bit

00:14:37.600 --> 00:14:39.839
more clear what's going on.

00:14:39.839 --> 00:14:41.445
When you generate documentation,

00:14:41.445 --> 00:14:43.519
you won't see these

00:14:43.519 --> 00:14:46.979
particular property annotations,

00:14:46.979 --> 00:14:50.145
and so you won't know immediately

00:14:50.145 --> 00:14:51.779
that this section goes in the

00:14:51.779 --> 00:14:53.839
imports area. So I usually put

00:14:53.839 --> 00:14:55.440
a little bit of documentation on top

00:14:55.440 --> 00:14:57.760
there, so that it's easy to see.

00:14:57.760 --> 00:15:01.120
You would, probably, if this was very

00:15:01.120 --> 00:15:03.040
complicated, you'd put some

00:15:03.040 --> 00:15:06.245
documentation above to explain

00:15:06.245 --> 00:15:07.360
what you were doing,

00:15:07.360 --> 00:15:11.519
maybe right here.

00:15:11.519 --> 00:15:13.279
You could picture yourself

00:15:13.279 --> 00:15:15.040
maybe explaining

00:15:15.040 --> 00:15:16.745
a complicated algorithm

00:15:16.745 --> 00:15:18.079
or something up here

00:15:18.079 --> 00:15:21.120
and having a nice way to document it.

00:15:21.120 --> 00:15:22.959
So now that we've got that here in the

00:15:22.959 --> 00:15:25.600
documentation, we need to figure out...

00:15:25.600 --> 00:15:27.040
We need to make sure that it's going to

00:15:27.040 --> 00:15:28.045
tangle properly.

00:15:28.045 --> 00:15:33.519
Your best friend at this point

00:15:33.519 --> 00:15:35.680
is a keyboard shortcut that lets you

00:15:35.680 --> 00:15:37.945
preview the tangled operation.

00:15:37.945 --> 00:15:42.560
If you say C-c C-v C-v,

00:15:42.560 --> 00:15:44.079
it will create a new buffer

00:15:44.079 --> 00:15:47.212
with the tangled contents

00:15:47.212 --> 00:15:49.179
and so you can see here

00:15:49.179 --> 00:15:52.345
that the fmt import went to the right
place,

00:15:52.345 --> 00:15:54.679
that function went to the right place,

00:15:54.679 --> 00:15:56.079
the function invocation went to

00:15:56.079 --> 00:15:58.480
the right place. We're feeling good.

00:15:58.480 --> 00:16:00.912
You can nest these things

00:16:00.912 --> 00:16:02.800
many layers deep.

00:16:02.800 --> 00:16:06.045
If you came into the sayHello function,

00:16:06.045 --> 00:16:10.560
you could add more sections.

00:16:10.560 --> 00:16:13.759
It'll go through and it'll

00:16:13.759 --> 00:16:15.345
keep track of all that

00:16:15.345 --> 00:16:16.212
and tangle it for you

00:16:16.212 --> 00:16:16.959
so you really get a lot of freedom

00:16:16.959 --> 00:16:18.320
and flexibility for how you want to

00:16:18.320 --> 00:16:20.479
document things by doing this.

00:16:20.479 --> 00:16:23.079
So now that we've previewed it

00:16:23.079 --> 00:16:25.839
and we feel good about it,

00:16:25.839 --> 00:16:28.639
we need to tangle so

00:16:28.639 --> 00:16:31.440
we get the file on the file system.

00:16:31.440 --> 00:16:34.979
so C-c C-c and get...

00:16:34.979 --> 00:16:37.199
just main.go comes back again.

00:16:37.199 --> 00:16:40.959
C-c C-cc and no errors come back.

00:16:40.959 --> 00:16:43.279
Then if we did this right,

00:16:43.279 --> 00:16:45.079
when we run this, we should get

00:16:45.079 --> 00:16:45.600
"Hello, EmacsConf."

00:16:45.600 --> 00:16:51.199
So C-c C-c, Hello EmacsConf.

00:16:54.800 --> 00:16:57.645
I think that's pretty, pretty cool,
actually.

00:16:57.645 --> 00:16:59.579
So we've got the breadcrumbs

00:16:59.579 --> 00:17:01.212
of the process we've gone through

00:17:01.212 --> 00:17:02.399
to get to this point,

00:17:02.399 --> 00:17:07.545
this initial document that has some
tangling in it.

00:17:07.545 --> 00:17:09.919
We have documentation for how to tangle,

00:17:09.919 --> 00:17:11.345
how to build, how to run.

00:17:11.345 --> 00:17:15.045
We've really built a nice foundation

00:17:15.045 --> 00:17:19.379
for moving forward on our project

00:17:19.379 --> 00:17:21.439
and a nice way of breaking things
out

00:17:21.439 --> 00:17:23.280
and documenting further.

00:17:23.280 --> 00:17:27.120
The last piece that we need to

00:17:27.120 --> 00:17:30.559
take care of is the weave that

00:17:30.559 --> 00:17:34.799
I showed you in the diagram above.

00:17:34.799 --> 00:17:38.640
So one more time, we'll drop in

00:17:38.640 --> 00:17:41.760
some documentation, this time on how

00:17:41.760 --> 00:17:42.400
to weave.

00:17:42.400 --> 00:17:44.400
It's really just an export function.

00:17:44.400 --> 00:17:46.245
it's not... There's not a separate

00:17:46.245 --> 00:17:49.012
weave command going on here.

00:17:49.012 --> 00:17:50.640
we're just going to export

00:17:50.640 --> 00:17:53.512
what we've got here into a Markdown
format.

00:17:53.512 --> 00:17:57.045
We're using org-gfm-export-to-markdown,

00:17:57.045 --> 00:17:59.745
which is the Github style markdown.

00:17:59.745 --> 00:18:02.160
You can use the other,

00:18:02.160 --> 00:18:03.812
more standard type as well.

00:18:03.812 --> 00:18:08.479
Hit C-c C-c. Now you see

00:18:08.479 --> 00:18:11.312
we've got a README file,

00:18:11.312 --> 00:18:16.512
and if you look in the file system,

00:18:16.512 --> 00:18:19.120
we've got that right there.

00:18:19.120 --> 00:18:23.120
If you go to something like ghostwriter

00:18:23.120 --> 00:18:31.679
and open that file,

00:18:31.679 --> 00:18:32.879
now you can see that

00:18:32.879 --> 00:18:35.520
it's generated some documentation.

00:18:35.520 --> 00:18:37.645
It puts a index at top at the top.

00:18:39.679 --> 00:18:41.145
I usually turn that off.

00:18:41.145 --> 00:18:42.379
It's easy to do that by

00:18:42.379 --> 00:18:43.179
putting a property at the

00:18:43.179 --> 00:18:46.145
top of your Org file,

00:18:46.145 --> 00:18:46.880
but some people like to

00:18:46.880 --> 00:18:48.559
have an index.

00:18:48.559 --> 00:18:50.799
Here you can see that it has generated

00:18:50.799 --> 00:18:55.200
pretty nicely and formatted
snippets well,

00:18:55.200 --> 00:18:56.880
put the diagram in there, and then

00:18:58.240 --> 00:19:02.799
it's preserved this
literate programming syntax,

00:19:02.799 --> 00:19:04.960
which is important because that's how we

00:19:04.960 --> 00:19:06.112
want to view the documentation.

00:19:06.112 --> 00:19:11.312
That's what the no-exports property

00:19:11.312 --> 00:19:13.360
was trying to maintain.

00:19:13.360 --> 00:19:15.979
no-exports means when you export,

00:19:15.979 --> 00:19:18.400
do not try to tangle.

00:19:18.400 --> 00:19:20.559
Hopefully that makes more sense now.

00:19:20.559 --> 00:19:22.240
Now you can see all the documentation.

00:19:22.240 --> 00:19:26.080
I think it demonstrates a

00:19:26.080 --> 00:19:33.520
pretty useful feature that's inside of
Emacs.

00:19:33.520 --> 00:19:34.979
Hopefully you'll have as much fun

00:19:34.979 --> 00:19:39.919
using that as I have.

00:19:39.919 --> 00:19:43.600
So thanks!