(Chapa 1)


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.

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: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