summaryrefslogblamecommitdiffstats
path: root/2020/subtitles/emacsconf-2020--14-readme-driven-design--adam-ard-autogen.vtt
blob: 3179635f57e650e84fb60ef0e60aa0026349870c (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
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
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426

















































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































                                        
WEBVTT

00:00:03.600 --> 00:00:04.400
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:16.400
and it's usually a markdown file but if

00:00:16.400 --> 00:00:17.600
you use an org

00:00:17.600 --> 00:00:20.720
more an org mode file instead you can

00:00:20.720 --> 00:00:22.560
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.920
starting with an empty org file like you

00:00:51.920 --> 00:00:54.800
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 I r that I've written about

00:01:07.760 --> 00:01:10.840
about my project here so you can kind of

00:01:10.840 --> 00:01:12.240
see

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

00:01:15.280 --> 00:01:17.119
so as you can see I have a title and a

00:01:17.119 --> 00:01:20.320
description and then a sub section

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

00:01:23.840 --> 00:01:25.520
and you can see that orgmo does a great

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

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

00:01:31.280 --> 00:01:33.920
it's good or it's as good or better than

00:01:33.920 --> 00:01:35.040
markdown

00:01:35.040 --> 00:01:37.520
but when you use it in the Emacs you can

00:01:37.520 --> 00:01:38.880
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 so 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 control c control c you'll see

00:01:49.439 --> 00:01:51.439
that we generate a

00:01:51.439 --> 00:01:55.439
diagram dynamically you can run

00:01:55.439 --> 00:01:59.200
so 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 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 important most importantly for

00:02:10.640 --> 00:02:11.520
the

00:02:11.520 --> 00:02:14.800
purposes my purpose is here

00:02:14.800 --> 00:02:17.200
orgmo 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.360
and gives you a quick overview of what I

00:02:25.360 --> 00:02:27.520
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:33.920
that we start with a readme.org file on

00:02:33.920 --> 00:02:34.720
top

00:02:34.720 --> 00:02:36.879
at this point we can do one of two

00:02:36.879 --> 00:02:37.920
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
and 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.519
but this is really all that there is to

00:03:01.519 --> 00:03:04.480
it you just

00:03:04.480 --> 00:03:06.400
who are simply using literate illiterate

00:03:06.400 --> 00:03:07.840
source file

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

00:03:10.319 --> 00:03:11.680
the rest of the project

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

00:03:17.120 --> 00:03:20.959
so let's dig in to the details of how

00:03:20.959 --> 00:03:22.640
this works

00:03:22.640 --> 00:03:24.560
and 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:28.959
so returning to the file here let's

00:03:28.959 --> 00:03:31.120
assume we have enough documentation now

00:03:31.120 --> 00:03:32.080
that we want to get started

00:03:32.080 --> 00:03:34.159
coding so maybe we'll just start with

00:03:34.159 --> 00:03:35.519
like a hello world

00:03:35.519 --> 00:03:38.159
app 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
so 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:50.319
add

00:03:50.319 --> 00:03:52.239
a source block for literate programming

00:03:52.239 --> 00:03:53.599
quickly

00:03:53.599 --> 00:03:56.959
and there's not much to it

00:03:56.959 --> 00:03:58.799
but there is some important annotations

00:03:58.799 --> 00:04:01.599
here so there's

00:04:01.599 --> 00:04:04.080
excuse me there's a 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
and then there's also a no web property

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

00:04:18.880 --> 00:04:23.759
and basically

00:04:23.759 --> 00:04:26.800
basically the no export will explain

00:04:26.800 --> 00:04:28.639
that a little bit

00:04:28.639 --> 00:04:32.080
more later um it has has to do with how

00:04:32.080 --> 00:04:33.919
the tangling

00:04:33.919 --> 00:04:37.600
is uh done in the tangle step versus the

00:04:37.600 --> 00:04:39.280
weave step and I'll explain that a

00:04:39.280 --> 00:04:41.199
little bit more but the tangle

00:04:41.199 --> 00:04:45.199
field just simply tells tells uh

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
uh you'll 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:02.160
using

00:05:02.160 --> 00:05:05.360
the most lately uh but

00:05:05.360 --> 00:05:07.360
this programming strategy is language

00:05:07.360 --> 00:05:08.400
agnostic

00:05:08.400 --> 00:05:12.080
you could use any language or any mix

00:05:12.080 --> 00:05:14.720
of languages you could create some files

00:05:14.720 --> 00:05:16.560
in python some files and go

00:05:16.560 --> 00:05:19.520
some files in in lisp or whatever you

00:05:19.520 --> 00:05:21.520
want

00:05:21.520 --> 00:05:24.720
and so but let's

00:05:24.720 --> 00:05:28.000
uh let's create just a little hello

00:05:28.000 --> 00:05:29.440
world

00:05:29.440 --> 00:05:32.320
let's use another snippet here to

00:05:32.320 --> 00:05:33.520
generate

00:05:33.520 --> 00:05:36.560
the basics of a go program

00:05:36.560 --> 00:05:40.240
so 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.320
let's make it a section in our

00:05:52.320 --> 00:05:55.280
file so now you can see we've got this

00:05:55.280 --> 00:05:56.400
snippet

00:05:56.400 --> 00:05:59.600
um 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:02.880
into a

00:06:02.880 --> 00:06:04.960
language specific buffer by typing

00:06:04.960 --> 00:06:07.680
control c single quote

00:06:07.680 --> 00:06:10.240
so you can see now I have a a go 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:18.800
normally if you hit ctrl c

00:06:18.800 --> 00:06:20.800
single quote again then it goes back and

00:06:20.800 --> 00:06:22.639
any changes you

00:06:22.639 --> 00:06:25.280
make would will be updated there but you

00:06:25.280 --> 00:06:26.160
can do quite a bit

00:06:26.160 --> 00:06:28.000
just inside of here too there's quite a

00:06:28.000 --> 00:06:29.199
bit of

00:06:29.199 --> 00:06:33.360
language specific

00:06:33.360 --> 00:06:35.440
functionality just in place and so you

00:06:35.440 --> 00:06:36.880
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
but it's a it's a nice option sometimes

00:06:42.319 --> 00:06:44.319
but 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.560
but right now it just lives here in this

00:06:48.560 --> 00:06:50.240
documentation

00:06:50.240 --> 00:06:52.160
so 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:05.280
bit more

00:07:05.280 --> 00:07:12.240
documentation really quick here

00:07:12.240 --> 00:07:17.360
okay all right so just kind of as a

00:07:17.360 --> 00:07:21.520
kind of as a side note I like to follow

00:07:21.520 --> 00:07:24.800
this process uh whenever having whenever

00:07:24.800 --> 00:07:26.639
I have an operation to perform I

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 in line

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 I take the

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

00:07:41.680 --> 00:07:43.440
and document it and so then it's

00:07:43.440 --> 00:07:44.879
recorded

00:07:44.879 --> 00:07:48.400
and so here we find that to do a tangle

00:07:48.400 --> 00:07:49.120
operation

00:07:49.120 --> 00:07:51.680
you run the command or babel tangled

00:07:51.680 --> 00:07:52.560
which is a

00:07:52.560 --> 00:07:55.840
e-list command so if you hit ctrl c

00:07:55.840 --> 00:07:59.199
ctrl c to run it in place you get the

00:07:59.199 --> 00:08:00.080
result

00:08:00.080 --> 00:08:02.720
of main dot 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
and you can see that that's true

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

00:08:14.000 --> 00:08:14.400
look

00:08:14.400 --> 00:08:17.840
so now in uh in our demo directory

00:08:17.840 --> 00:08:20.960
we have a readme.org we have that png

00:08:20.960 --> 00:08:22.479
that we generated but we also have a

00:08:22.479 --> 00:08:23.440
main.go

00:08:23.440 --> 00:08:26.080
and if you if you visit that file you'll

00:08:26.080 --> 00:08:27.759
see that it's just the source code that

00:08:27.759 --> 00:08:29.280
was in our documentation which is

00:08:29.280 --> 00:08:31.039
exactly what we expected and what we

00:08:31.039 --> 00:08:32.880
wanted so that's good

00:08:32.880 --> 00:08:36.560
so if we return to

00:08:36.560 --> 00:08:41.120
to where we are at

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

00:08:42.959 --> 00:08:44.640
have a file on the file system so now we

00:08:44.640 --> 00:08:45.760
need

00:08:45.760 --> 00:08:48.959
um now we need to build it and to

00:08:48.959 --> 00:08:53.600
run it so let's follow the same

00:08:53.600 --> 00:08:57.040
philosophy where let's document

00:08:57.040 --> 00:08:58.720
these operations that we're going to

00:08:58.720 --> 00:09:00.160
perform

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

00:09:04.560 --> 00:09:07.839
a build instruction section and a run

00:09:07.839 --> 00:09:13.360
instruction section

00:09:13.360 --> 00:09:15.279
so 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:20.000
and another batch source block this one

00:09:20.000 --> 00:09:22.000
compiles the go build command is what

00:09:22.000 --> 00:09:25.440
compiles a file and then

00:09:25.440 --> 00:09:26.880
the file that gets generated should be

00:09:26.880 --> 00:09:30.080
called demo

00:09:30.080 --> 00:09:32.959
and uh so we just run it here so if if I

00:09:32.959 --> 00:09:34.000
type control c

00:09:34.000 --> 00:09:37.839
control c we get an empty results block

00:09:37.839 --> 00:09:40.640
when you compile things no news is good

00:09:40.640 --> 00:09:41.360
news

00:09:41.360 --> 00:09:44.399
so it means there's no errors so

00:09:44.399 --> 00:09:46.560
presumably we've created an executable

00:09:46.560 --> 00:09:48.000
that's called demo

00:09:48.000 --> 00:09:51.440
so let's uh

00:09:51.440 --> 00:09:54.560
let's look again at the file system and

00:09:54.560 --> 00:10:02.480
regenerate

00:10:02.480 --> 00:10:05.760
yep and what we have here is a demo

00:10:05.760 --> 00:10:07.200
executable which is exactly what we

00:10:07.200 --> 00:10:07.760
wanted

00:10:07.760 --> 00:10:12.079
so let's go back

00:10:12.079 --> 00:10:14.160
so now we should be able to run it so

00:10:14.160 --> 00:10:16.079
ctrl c ctrl 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 you can do that much

00:10:30.839 --> 00:10:33.040
um but

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

00:10:34.560 --> 00:10:37.839
the iceberg to uh to really

00:10:37.839 --> 00:10:41.040
kind of um

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

00:10:43.440 --> 00:10:46.160
literate programming we need to uh

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

00:10:49.920 --> 00:10:53.200
so or at least

00:10:53.200 --> 00:10:55.519
at least really to get the full benefit

00:10:55.519 --> 00:10:56.480
of it then

00:10:56.480 --> 00:10:59.600
we need to do

00:10:59.600 --> 00:11:02.959
add some sections that will cause uh

00:11:02.959 --> 00:11:06.320
Emacs to have to to tangle or assemble

00:11:06.320 --> 00:11:06.720
this

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

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 in

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

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

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

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.000
like a template or a scaffolding or

00:11:42.000 --> 00:11:42.880
outline

00:11:42.880 --> 00:11:46.000
for what what our file is going to be it

00:11:46.000 --> 00:11:48.399
looks a little bit like pseudocode

00:11:48.399 --> 00:11:50.800
and what we're going to have literate

00:11:50.800 --> 00:11:52.399
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
maybe called say hello so we want

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
um 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 but it's

00:12:27.839 --> 00:12:31.040
it just has a few differences so say we

00:12:31.040 --> 00:12:31.680
want to

00:12:31.680 --> 00:12:34.160
drop code into the import section and we

00:12:34.160 --> 00:12:36.639
want it to be in go

00:12:36.639 --> 00:12:39.120
here we use the same noed no web no

00:12:39.120 --> 00:12:40.720
export syntax

00:12:40.720 --> 00:12:43.200
but then we've added this no web refs

00:12:43.200 --> 00:12:44.560
imports

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

00:12:48.240 --> 00:12:51.120
basically to this reference it tells

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

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

00:12:56.880 --> 00:12:58.240
that spot

00:12:58.240 --> 00:13:02.079
so 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 you're

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:18.839
so let's add another section for uh

00:13:18.839 --> 00:13:22.240
functions and let's create a

00:13:22.240 --> 00:13:25.519
let's just create a function called

00:13:25.519 --> 00:13:30.240
say hello that

00:13:30.240 --> 00:13:32.839
doesn't have any arguments no return

00:13:32.839 --> 00:13:34.000
types

00:13:34.000 --> 00:13:35.760
all it does is kind of pretty much the

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

00:13:37.440 --> 00:13:39.199
just print something but let's just say

00:13:39.199 --> 00:13:41.360
hello

00:13:41.360 --> 00:13:45.760
Emacs comp this time

00:13:45.760 --> 00:13:49.519
okay so now we have a function and now

00:13:49.519 --> 00:13:51.040
the function won't do anything unless we

00:13:51.040 --> 00:13:52.720
invoke it so 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 and then let's

00:14:03.519 --> 00:14:06.560
just invoke

00:14:06.560 --> 00:14:10.320
that that function

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

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

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
so I I've kind of used this syntax

00:14:25.440 --> 00:14:27.199
it's it's kind of borrowed from

00:14:27.199 --> 00:14:28.560
literature programming a little bit with

00:14:28.560 --> 00:14:30.320
a plus equals 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 so

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.519
when you generate documentation you

00:14:41.519 --> 00:14:43.519
won't see these

00:14:43.519 --> 00:14:46.160
these these particular property

00:14:46.160 --> 00:14:49.360
annotations and so you won't know

00:14:49.360 --> 00:14:51.440
immediately that this section goes in

00:14:51.440 --> 00:14:53.839
the imports area and 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
and 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.399
documentation above to explain what you

00:15:06.399 --> 00:15:07.360
were doing

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

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

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

00:15:15.040 --> 00:15:17.440
a complicated algorithm or something up

00:15:17.440 --> 00:15:18.079
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:29.920
tangle properly so your best friend

00:15:29.920 --> 00:15:33.519
at this point is is uh

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

00:15:35.680 --> 00:15:38.240
preview the tangled operation so if you

00:15:38.240 --> 00:15:38.959
say control

00:15:38.959 --> 00:15:42.560
c control v control v

00:15:42.560 --> 00:15:45.120
it will create a new buffer with the

00:15:45.120 --> 00:15:46.480
tangled

00:15:46.480 --> 00:15:49.360
contents and so you can see here that

00:15:49.360 --> 00:15:50.639
the fmt

00:15:50.639 --> 00:15:53.199
import went to the right place that

00:15:53.199 --> 00:15:54.720
function went to the right place the

00:15:54.720 --> 00:15:56.160
function invocation went to the right

00:15:56.160 --> 00:15:58.480
place and so we're feeling good

00:15:58.480 --> 00:16:01.279
you can nest these things many layers

00:16:01.279 --> 00:16:02.800
deep

00:16:02.800 --> 00:16:04.800
actually so like if you came into the

00:16:04.800 --> 00:16:07.199
say hello function you could add

00:16:07.199 --> 00:16:10.560
more sections

00:16:10.560 --> 00:16:12.160
you know and it gets and it'll go

00:16:12.160 --> 00:16:13.759
through and it'll

00:16:13.759 --> 00:16:15.680
keep track of all that and tangle it for

00:16:15.680 --> 00:16:16.959
you 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:19.600
document things

00:16:19.600 --> 00:16:22.320
by doing this so now that we've

00:16:22.320 --> 00:16:25.839
previewed it and we feel good about it

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

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

00:16:31.440 --> 00:16:34.480
so ctrl c ctrl c and

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

00:16:37.199 --> 00:16:37.920
control c

00:16:37.920 --> 00:16:40.959
control c and no errors come back

00:16:40.959 --> 00:16:43.839
and then if we did this right when we

00:16:43.839 --> 00:16:45.600
when we run this we should get hello

00:16:45.600 --> 00:16:47.199
Emacs comp so ctrl c

00:16:47.199 --> 00:16:51.199
ctrl c hello Emacs comp

00:16:51.199 --> 00:16:54.800
so I uh

00:16:54.800 --> 00:16:57.120
I think that's pretty pretty cool

00:16:57.120 --> 00:16:58.240
actually so we've got

00:16:58.240 --> 00:17:00.160
kind of the breadcrumbs of the process

00:17:00.160 --> 00:17:02.399
we've gone through to get to this point

00:17:02.399 --> 00:17:05.520
this initial this initial

00:17:05.520 --> 00:17:08.000
document that has some tangling in it we

00:17:08.000 --> 00:17:09.919
have documentation for how to tangle

00:17:09.919 --> 00:17:12.799
how to build how to run it's we've

00:17:12.799 --> 00:17:14.079
really built a nice

00:17:14.079 --> 00:17:17.760
foundation for

00:17:17.760 --> 00:17:20.160
moving forward on our project and a nice

00:17:20.160 --> 00:17:21.439
way of breaking things out and

00:17:21.439 --> 00:17:23.280
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 I

00:17:30.559 --> 00:17:34.799
that's 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 so this time on how

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

00:17:42.400 --> 00:17:44.400
so it's really just an export function

00:17:44.400 --> 00:17:47.520
it's not there's not a separate weave

00:17:47.520 --> 00:17:49.280
command going on here we're just going

00:17:49.280 --> 00:17:50.640
to export

00:17:50.640 --> 00:17:52.799
what we've got here into a markdown

00:17:52.799 --> 00:17:55.200
format so we're using org

00:17:55.200 --> 00:17:57.440
gfm export to markdown which is the

00:17:57.440 --> 00:17:58.880
github style

00:17:58.880 --> 00:18:02.160
markdown you can use the other just

00:18:02.160 --> 00:18:05.440
more standard type as well so hit ctrl c

00:18:05.440 --> 00:18:10.320
ctrl c now you see we've got a readme

00:18:10.320 --> 00:18:15.280
file and if you look

00:18:15.280 --> 00:18:17.440
in the file system we've got that right

00:18:17.440 --> 00:18:19.120
there and so

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:34.559
now you can see that it's generated some

00:18:34.559 --> 00:18:35.520
documentation

00:18:35.520 --> 00:18:38.320
it puts a index at top at the top I

00:18:38.320 --> 00:18:39.679
usually just

00:18:39.679 --> 00:18:42.000
I usually turn that off it's easy to do

00:18:42.000 --> 00:18:43.679
that by putting a property at the top of

00:18:43.679 --> 00:18:44.559
your

00:18:44.559 --> 00:18:46.880
your org file but some people like to

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

00:18:48.559 --> 00:18:50.799
but here you can see that it's generated

00:18:50.799 --> 00:18:52.160
pretty nicely and

00:18:52.160 --> 00:18:55.200
formatted snippets well

00:18:55.200 --> 00:18:56.880
put the diagram in there and then it's

00:18:56.880 --> 00:18:58.240
preserved

00:18:58.240 --> 00:19:01.039
it's preserved this literate programming

00:19:01.039 --> 00:19:02.799
syntax

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

00:19:04.960 --> 00:19:06.480
want to view the documentation that's

00:19:06.480 --> 00:19:07.200
what the no

00:19:07.200 --> 00:19:10.559
exports um

00:19:10.559 --> 00:19:13.360
property was was trying to maintain so

00:19:13.360 --> 00:19:14.000
that

00:19:14.000 --> 00:19:16.080
no exports means when you export do not

00:19:16.080 --> 00:19:18.400
try to tangle so that's

00:19:18.400 --> 00:19:20.559
hopefully that makes more sense now but

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

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

00:19:26.080 --> 00:19:29.919
pretty useful feature that's inside of

00:19:29.919 --> 00:19:33.520
Emacs and and hopefully

00:19:33.520 --> 00:19:35.039
hopefully you'll have as much fun using

00:19:35.039 --> 00:19:39.919
that as I have

00:19:39.919 --> 00:19:43.600
so thanks