path: root/2023/captions/emacsconf-2023-doc--literate-documentation-with-emacs-and-org-mode--mike-hamrick--answers.vtt

WEBVTT


00:00:03.639 --> 00:00:04.019
[Speaker 0]: Well, we have about, I think,

00:00:06.339 --> 00:00:06.839
10 or 15 minutes of on-stream Q&A time.

00:00:10.320 --> 00:00:10.559
But if there's more questions than that,

00:00:11.420 --> 00:00:11.920
people are welcome to stay.

00:00:14.200 --> 00:00:14.639
If Mike has the time to answer some more,

00:00:15.060 --> 00:00:15.560
then Awesome.

00:00:20.920 --> 00:00:21.060
[Speaker 1]: Yeah, I will be around for the rest of the

00:00:22.440 --> 00:00:22.940
conference. So I am spudpnds,

00:00:26.580 --> 00:00:27.080
which is spud upside down on IRC,

00:00:29.640 --> 00:00:30.140
if you want to hit me up on IRC.

00:00:30.860 --> 00:00:31.360
Nice.

00:00:42.800 --> 00:00:43.300
[Speaker 0]: I see we already have a question on the pad,

00:00:45.920 --> 00:00:46.080
and it is, did you develop a variant of your

00:00:46.920 --> 00:00:47.420
document for CentOS?

00:00:52.840 --> 00:00:53.239
[Speaker 1]: I did not. I have not messed with any other

00:00:56.120 --> 00:00:56.620
Red Hat distributions other than Fedora.

00:00:59.960 --> 00:01:00.460
I would like to expand the document out to

00:01:05.740 --> 00:01:05.860
Windows and to Mac OS as I think a lot of

00:01:07.720 --> 00:01:07.960
people really want to build Emacs on those

00:01:09.840 --> 00:01:10.340
platforms because it's much harder to get

00:01:13.080 --> 00:01:13.580
Emacs binaries running on those platforms.

00:01:15.860 --> 00:01:16.080
Although they're around on the internet it's

00:01:17.320 --> 00:01:17.440
not as bad as it used to be,

00:01:19.280 --> 00:01:19.760
but building Emacs is very,

00:01:21.000 --> 00:01:21.160
a very fun thing to do.

00:01:22.760 --> 00:01:23.260
And I encourage everybody to do that.

00:01:46.160 --> 00:01:46.440
[Speaker 0]: Right. We're also getting comments from folks

00:01:46.800 --> 00:01:47.300
here on BigBlueButton.

00:01:49.640 --> 00:01:49.900
EXC or Matt saying, great talk,

00:01:51.140 --> 00:01:51.640
good demonstration of what's possible.

00:01:53.940 --> 00:01:54.240
And Aaron thanking Mike,

00:01:54.760 --> 00:01:55.260
saying awesome presentation.

00:01:56.880 --> 00:01:57.040
And they missed the first few minutes and

00:01:59.540 --> 00:01:59.720
have to rewatch to get the portion that they

00:01:59.720 --> 00:02:00.220
missed.

00:02:03.400 --> 00:02:03.700
[Speaker 1]: I had a hard time cramming the entire talk

00:02:08.220 --> 00:02:08.720
into 40 minutes. So I spoke quickly.

00:02:10.639 --> 00:02:10.919
I have a feeling I may have left some folks

00:02:12.540 --> 00:02:13.040
behind who weren't paying close attention.

00:02:16.020 --> 00:02:16.520
So rewatching might help.

00:02:18.920 --> 00:02:19.420
[Speaker 0]: Oh, nice.

00:02:24.920 --> 00:02:25.340
[Speaker 1]: I noticed Matt said that he helps maintain

00:02:27.440 --> 00:02:27.700
the shell functionality or Babel and last

00:02:30.240 --> 00:02:30.580
March they added async evaluation into

00:02:32.920 --> 00:02:33.340
session code blocks. Very cool,

00:02:34.680 --> 00:02:34.840
especially when you're doing something that

00:02:36.420 --> 00:02:36.820
takes a long time. It would be nice if Emacs

00:02:38.920 --> 00:02:39.060
wasn't locked up. I will definitely have to

00:02:50.220 --> 00:02:50.460
check that out. I use this technique at work

00:02:53.220 --> 00:02:53.360
a lot, like when I write documents to how to

00:02:55.900 --> 00:02:56.400
explain things to coworkers and such.

00:03:00.060 --> 00:03:00.300
And 1 of the things I had to explain was how

00:03:05.220 --> 00:03:05.720
to build AWS MySQL databases and replicas,

00:03:07.760 --> 00:03:08.260
and how to build them with very specific

00:03:09.960 --> 00:03:10.240
parameters to work with the system called

00:03:13.060 --> 00:03:13.320
Vitesse. And when I was running that

00:03:15.660 --> 00:03:16.160
document, building these kinds of MySQL

00:03:20.280 --> 00:03:20.640
databases in AWS with lockup Emacs for 20,

00:03:22.300 --> 00:03:22.800
25 minutes at a time. So,

00:03:26.060 --> 00:03:26.540
yeah, I'm really excited about async

00:03:26.540 --> 00:03:27.040
evaluation.

00:04:03.780 --> 00:04:04.020
Totally. Oh yeah, Python mode I think has had

00:04:05.600 --> 00:04:06.100
async for shell blocks for a while.

00:04:09.220 --> 00:04:09.720
I think there's a third-party package at Elba

00:04:11.260 --> 00:04:11.760
that adds async support for that.

00:04:16.360 --> 00:04:16.620
But yeah, I explicitly wanted to make sure

00:04:18.620 --> 00:04:18.959
that it would work with super vanilla stuff.

00:04:20.060 --> 00:04:20.560
Oh, it's built in. I see.

00:04:24.140 --> 00:04:24.280
Yeah, I didn't realize it was built in for

00:04:25.920 --> 00:04:26.420
Python blocks. I'll have to check that out.

00:04:27.800 --> 00:04:28.300
There's so much Emacs.

00:04:32.080 --> 00:04:32.240
It's hard to wrap your head even around a

00:04:34.900 --> 00:04:35.400
tiny portion of it. It's such a deep topic.

00:04:47.660 --> 00:04:48.160
Looks like somebody in IRC said,

00:04:50.220 --> 00:04:50.440
I can't wait to add some of this stuff to my

00:04:52.680 --> 00:04:53.180
documents. And that really makes me happy.

00:04:55.400 --> 00:04:55.640
I hope people go out and write literate Org

00:04:57.180 --> 00:04:57.680
Mode documents that do amazing things.

00:05:25.640 --> 00:05:26.040
When's the next talk? We have like,

00:05:30.900 --> 00:05:31.080
[Speaker 0]: let's see. I think we have about 4 or 5

00:05:32.960 --> 00:05:33.460
minutes live on stream for Q&A.

00:05:35.860 --> 00:05:36.360
[Speaker 1]: Yeah, okay. Oh, here's the question.

00:05:39.160 --> 00:05:39.320
Blaine asks, are you running Emacs from the

00:05:41.420 --> 00:05:41.760
host machine? And yeah,

00:05:43.940 --> 00:05:44.180
so I'm running Emacs on the exact same

00:05:46.560 --> 00:05:47.060
machine that I'm building Emacs on.

00:05:50.580 --> 00:05:50.900
And I had first thought about doing that over

00:05:53.440 --> 00:05:53.720
Tramp. And I thought that would be a very

00:05:55.360 --> 00:05:55.560
cool demo to show how you could do that

00:05:57.980 --> 00:05:58.180
remotely on Tramp so you didn't need Emacs on

00:06:03.160 --> 00:06:03.280
the host machine. But I decided it would be a

00:06:05.640 --> 00:06:05.780
lot easier, and as I ran into a deadline to

00:06:06.360 --> 00:06:06.860
get the talk completed,

00:06:08.900 --> 00:06:09.140
I abandoned that notion for the

00:06:09.880 --> 00:06:10.380
straightforward approach.

00:06:13.260 --> 00:06:13.760
But ideally, I would spin up virtual machines

00:06:16.980 --> 00:06:17.140
and then using the Org Mode document and

00:06:18.960 --> 00:06:19.440
having Org Mode reach out to those machines

00:06:20.440 --> 00:06:20.940
via SSH and Tramp.

00:06:33.400 --> 00:06:33.540
Oh yeah, there's also a little bit of

00:06:38.200 --> 00:06:38.440
discussion on IRC about org macros and how

00:06:39.720 --> 00:06:40.160
they made their way into the document.

00:06:42.540 --> 00:06:42.900
And I remember when I first discovered org

00:06:44.480 --> 00:06:44.980
macros by reading the org mode documentation,

00:06:47.360 --> 00:06:47.500
I was really excited because I thought I

00:06:49.860 --> 00:06:50.040
could limit a lot of the boilerplate I end up

00:06:51.900 --> 00:06:52.360
typing. But as we discussed,

00:06:54.760 --> 00:06:55.260
ORD macros, I think, only work in 1 context

00:06:56.380 --> 00:06:56.780
in your ORD mode document,

00:06:58.280 --> 00:06:58.780
and I think that's in the pros section.

00:07:03.740 --> 00:07:04.080
So You can't resolve a macro inside a header

00:07:06.600 --> 00:07:07.100
arg, for example, or inside an options block.

00:07:09.560 --> 00:07:09.960
It would be awesome if macros worked

00:07:12.280 --> 00:07:12.780
everywhere, but I'm happy to have them just

00:07:13.500 --> 00:07:14.000
as they are now.

00:07:22.960 --> 00:07:23.460
[Speaker 0]: Indeed, they're very convenient.

00:07:32.020 --> 00:07:32.260
[Speaker 1]: And Blaine also says, thank you for showing

00:07:33.420 --> 00:07:33.920
what's possible with literate documentation.

00:07:35.380 --> 00:07:35.660
This is mind-blowing. Yeah,

00:07:39.400 --> 00:07:39.640
I think so too. I first saw this technique in

00:07:41.020 --> 00:07:41.520
Howard's video, Literate DevOps,

00:07:44.720 --> 00:07:44.900
and I remember I was just picking up parts of

00:07:46.720 --> 00:07:47.040
my mind after it exploded after having

00:07:49.740 --> 00:07:49.860
watched that video. So I wanted to do some of

00:07:51.820 --> 00:07:52.040
it myself, and that's where I came up with a

00:07:54.020 --> 00:07:54.520
couple different approaches to that.

00:07:57.600 --> 00:07:57.800
It's not just for, you know,

00:07:59.060 --> 00:07:59.560
making literate Emacs configurations.

00:08:04.680 --> 00:08:04.920
[Speaker 0]: For Sure. We have another remark slash

00:08:07.260 --> 00:08:07.580
question on the pad. Someone saying great

00:08:09.800 --> 00:08:10.300
presentation. The preparation is outstanding.

00:08:12.520 --> 00:08:13.020
And for someone like me that never touched

00:08:14.040 --> 00:08:14.540
the org-mux side of Emacs,

00:08:17.040 --> 00:08:17.200
What do you feel is the more complex part to

00:08:19.120 --> 00:08:19.540
tackle? You made it seem simple,

00:08:20.500 --> 00:08:21.000
but the complexity there.

00:08:25.840 --> 00:08:26.340
[Speaker 1]: Yeah. Just getting all of the configuration

00:08:30.800 --> 00:08:31.300
set up the way you want it is the hardest

00:08:34.780 --> 00:08:35.280
part. So some of the defaults are,

00:08:37.120 --> 00:08:37.280
you know, they don't look good when you

00:08:39.320 --> 00:08:39.820
render them out in LaTeX and finally PDF.

00:08:42.039 --> 00:08:42.380
And there's a lot of work to be done to tweak

00:08:45.380 --> 00:08:45.780
the LaTeX environment so it looks as pretty

00:08:48.620 --> 00:08:48.940
as you might want it. And then just Org Mode

00:08:50.800 --> 00:08:51.300
has a lot of knobs that you can tune,

00:08:53.720 --> 00:08:54.020
and they have a pretty large impact on how

00:08:55.520 --> 00:08:56.020
your document is exported.

00:09:00.360 --> 00:09:00.680
So I think the hardest part is just knowing

00:09:03.820 --> 00:09:03.960
what's possible and knowing where all the

00:09:05.200 --> 00:09:05.700
knobs are to tune and twist.

00:09:10.240 --> 00:09:10.440
[Speaker 0]: Got another question on the pad.

00:09:12.040 --> 00:09:12.180
And I think we have about a minute or so on

00:09:13.740 --> 00:09:13.920
the stream. So I'll read this question as

00:09:15.160 --> 00:09:15.660
well. But folks, you're welcome to continue

00:09:17.560 --> 00:09:18.040
on the pad or just come join here on BBB

00:09:20.200 --> 00:09:20.320
after myself and the stream move on to the

00:09:23.100 --> 00:09:23.480
next talk. Yeah, and the next question is,

00:09:24.320 --> 00:09:24.720
how do you normally debug,

00:09:26.640 --> 00:09:27.100
for example, view the logs or see failed

00:09:29.440 --> 00:09:29.720
statuses when the commands in the source

00:09:32.020 --> 00:09:32.280
blocks fail, especially if they output lots

00:09:34.640 --> 00:09:34.780
and lots of logs, and you need to see the

00:09:35.640 --> 00:09:36.140
full history of the build.

00:09:39.520 --> 00:09:40.020
[Speaker 1]: Yeah, so I see it in the messages buffer

00:09:42.080 --> 00:09:42.580
whenever I export a document.

00:09:44.540 --> 00:09:44.700
If there's a failure, that's typically where

00:09:47.460 --> 00:09:47.640
it's written to. And I will actually kill the

00:09:49.960 --> 00:09:50.440
messages buffer before I export so I know

00:09:52.840 --> 00:09:53.200
that only the messages in the buffer are for

00:09:55.800 --> 00:09:55.960
my given export and I mentioned that

00:09:58.580 --> 00:09:58.780
debugging trick where you name all of your

00:10:00.720 --> 00:10:00.960
org-mode source blocks So if there is a

00:10:02.320 --> 00:10:02.820
problem in 1 of the blocks,

00:10:06.560 --> 00:10:07.060
it'll actually tell you what the block,

00:10:09.140 --> 00:10:09.640
the name of the block the error occurred in.

00:10:13.160 --> 00:10:13.360
If you don't do that, it just gives you a

00:10:14.800 --> 00:10:15.300
position number in the buffer.

00:10:18.620 --> 00:10:18.820
And whenever I tried to convert those

00:10:21.400 --> 00:10:21.540
position numbers to actual places where the

00:10:23.600 --> 00:10:23.760
error occurred, it was never exactly where I

00:10:24.640 --> 00:10:25.020
suspected it would be.

00:10:26.680 --> 00:10:27.180
So I found that very difficult in debugging.

00:10:29.800 --> 00:10:30.040
So the only real debugging tip I have is name

00:10:32.840 --> 00:10:33.120
your source blocks, even if you don't refer

00:10:33.480 --> 00:10:33.980
to them later.

00:10:39.860 --> 00:10:40.020
[Speaker 0]: I think that's all the time we have on

00:10:41.320 --> 00:10:41.520
stream. And I also have to drop as well.

00:10:42.540 --> 00:10:42.880
But thanks again so much,

00:10:46.160 --> 00:10:46.660
Mike. And folks are welcome to come here and

00:10:47.980 --> 00:10:48.480
continue discussion here.

00:10:52.600 --> 00:10:53.100
Thanks again.

00:21:45.060 --> 00:21:45.560
[Speaker 1]: You

00:22:00.060 --> 00:22:00.560
Thank

00:22:15.060 --> 00:22:15.560
[Speaker 0]: you

00:22:28.400 --> 00:22:28.900
[Speaker 1]: for

00:22:45.060 --> 00:22:45.560
watching. You

00:23:00.260 --> 00:23:00.760
you