Org for non-users (2021)
At some point in 2021 I finally understood why I have always found Org Mode so hard to use. To make a long story short, I am a very bad user: when I try to use something and I can't make a clear mental model of what's going on my first reaction is to try to look at the data structures and at the source code - and the code that implements code blocks in Org is hard to understand.
TL;DR: I am a "non-user" and I found a way to document Org using eev that works for me and that may also work for other non-users like me, and I recorded a video explaining and demo-ing all this. If you like to watch videos with subtitles in high speed, then run the two "wget"s below to download a local copy and the "mpv" to play it (hint: use these keys):
Lots of important-ish things happened in november and december/2021:
In Org: Karl Voit gave this presentation on OrgDown at the EmacsConf2021; it was very well received at the conference and very badly received on reddit. He wrote this blog post about that. There were huge threads on emacs-orgmode about this: 1, 2. I learned a lot from these threads, and two of my favorite e-mails were this one by Russell Adams and this one by Ihor Radchenko.
In eev: I gave this presentation at the EmacsConf2021 and this workshop. I finally understood how alien one of the principles of eev - "save elisp hyperlinks to everything interesting that you find" - sounds to most people. I started to work on this tutorial on saving links. Sachac and grym helped me on #emacs with some of my main doubts about code blocks. I recorded the video below, created this page, and sent this e-mail to the Org mailing list announcing the page and the video. Samuel Banya sent this e-mail to the list mentioning Rainer König's videos and I answered him saying that 1) here is how I used eev to download and index some of Rainer König's videos, and that 2) I don't know how to do something similar to those indexes in Org yet.
TODO: write more.
To watch the video click on the thumbnail below.
The .org file that I used in the video is here.
For more info on the video - including an index in elisp - click here.
I got the photo of the Winter Moon Mask from this group: Northwest Coast Native Carvers.
The instagram page of the artist is here, and
his site is here.
Index of the video (elisp here):
0:00
0:12 To make two long stories short
0:18 In 2021 I finally understood
0:26 the documentation is written for users
0:36 I am a non-user
0:42 I can use eev to write the docs that I need
0:57 I also found something really weird
1:03 The main intent of eev ... take executable notes
1:11 one part that everyone understands
1:23 and a part that is much harder to learn
1:54 I'm working on a way to make this easier
2:04 This is the initial page of the tutorial
2:17 Let me explain what are users and non-users
2:51 a non-user
3:04 questions like: how does Org handle code blocks
3:20 repeatable tests
3:35 An example
3:49 This thing here is a source block
4:00 we can run the source block with C-c C-c
4:09 if I do that Org creates a results block
4:25 C-c C-c executes org-babel-execute-src-block
4:40 I can learn more with M-h M-k C-c C-c
4:55 I get this temporary buffer
5:04 in these notes I selected some hyperlinks
5:23 (find-efunctiondescr ...) shows the description
5:29 it's quite long
5:39 the last one says: in a code block...
5:49 (set org-confirm-babel-evaluate nil)
6:02 org-babel-remove-result-one-or-many
6:17 M-h M-k C-c C-v k
6:38 (find-efunctiondescr ...) shows the description
6:49 (find-efunction ...) shows the source code
7:13 I also wanted to understand the data structures
7:48 I asked on IRC ... (org-element-context)
7:58 if I execute it here ... the result is big
8:05 so let me use find-epp
8:18 the important part is in the cadr
8:34 and I can use find-eppp
8:43 I can see the keywords and their values
8:49 suppose that I want to undestand this :begin
8:54 (setq p (cadr (org-element-context)))
9:08 p now holds a property list
9:26 I can use the function of eev that highlights
9:40 when I run I see that the region includes
10:07 Another thing:
10:17 we can create a src block by hand
10:24 there's a way to type it more quickly
10:28 (find-orgnode \"Structure templates\")
10:35 If I type C-c C-,
10:46 `s' is the letter that I want
10:50 and if I type C-c C-, s
10:53 (there's some help here)
11:00 and I get a source block
11:12 of course I want to know how
11:20 I used M-h M-k C-c C-,
11:48 I selected these two sexps
11:59 the target of this sexp is the description
12:16 the target of this sexp is the source code
12:21 I can use find-efunctiondescr and click on
12:44 (find-evardescr 'org-structure-template-alist)
12:55 we can get help on that variable by typing M-h M-v
12:59 we get a buffer with elisp hyperlinks
13:15 so one of them just opens the description
13:30 (describe-variable '...) has a big result
13:42 so I prefer to use this variant
13:49 with this I can get a description
14:03 here it shows the current value
14:10 refine it with a \"src\"
14:26 so this link ... and searches for
14:40 to go to the defcustom
14:52 here is its initial value
15:05 this (eek \"C-c C-, s\") is a reminder
15:26 and this is an example of a source block
15:39 Just one thing more
15:45 by default when I type M-e
15:51 it opens the target in the same window
16:03 but if I type M-2 M-e or M-3 M-e
16:17 this is practical because I can show