Quick
index
main
eev
eepitch
maths
angg
blogme
dednat6
littlelangs
PURO
(C2,C3,C4,
 GA,MD,λ,
 Caepro,
 textos,
 Chapa 1)

emacs
lua
(la)tex
maxima
agda
forth
squeak
icon
tcl
tikz
fvwm
debian
irc
contact

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

# See:  http://anggtwu.net/eev-videos.html
#       http://anggtwu.net/eev-videos.html#mpv-keys
# Play: (find-2021orgfornonusersvideo "0:00")
# Info: (find-1stclassvideo-links "2021orgfornonusers")
# Subs: (find-1stclassvideolsubs  "2021orgfornonusers")

wget -nc http://anggtwu.net/eev-videos/2021-org-for-non-users.mp4
wget -N  http://anggtwu.net/eev-videos/2021-org-for-non-users.vtt
mpv --fs --osd-level=2 2021-org-for-non-users.mp4


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