Hi! My name is Eduardo Ochs...
I'm the author of an Emacs package called
eev, and the title of this video is
"Org for non-users". Let me explain what
I mean by this.
To make a long story short, or
actually to make two long stories short...
in 2021 I finally understood why I've
always found Org mode so hard to learn.
And it turns out that the documentation
of Org is written for "users",
and I realized that I'm a very bad "user".
I'm going to define this thing soon.
I'm a "non-user" in a sense that I'm
also going to define soon.
i also found that i can use eev -
my package - to write the documentation for
Org that I need...
and the technique
that i'm going to explain here _may_ be
useful to other non-users like me.
I also found something that I found
really weird...
let me let me explain. The main intent
of eev is to let you "take executable
notes of everything that you do"
and "taking executable notes" has one
part that everyone understands, which is
to "save all commands that you send to
external programs" - usually REPLs -
and it has a part that is much harder to
learn, which is to
"save elisp hyperlinks to everything
interesting that you find"...
and I discovered that this part is
much harder than than I thought...
it was totally natural for me when I
started using Emacs, I started doing that
immediately...
but I discovered that most people can't
even imagine how is the workflow of
someone who works
like this, and so i'm working on a way to
make this easier to understand...
I'm writing a tutorial about this - it's
called `(find-saving-links-intro)' -
let me show just the initial page
of this tutorial... it starts
with a section named
"Reading diagrams aloud", but
this is not important to us now...
so now let me explain what are "users"
and "non-users",
and let me use one feature of
Org mode, called "code blocks",
or "source blocks", as an example.
If a "user" wants to learn how to use code
blocks in Org then the "user" is probably
going to need to learn what are the key
sequences, what are the main examples -
or some examples - and the "user"
does not want to see the source code...
and a "non-user" is going to think in a
way that is very different. A "non-user"
needs to have a clear mental image of
what is going on behind the scenes...
so a "non-user" is going to ask questions
like: how does Org handle code blocks
_internally_?
What are the data structures that it
uses?
What is the source code like? What are
the functions? How is it structured?
And a "non-user" is also going to need
repeatable tests, that can be
executed either unchanged or with little
changes, to check what is going on.
So let me start with an example...
this thing here...
no, let me use a smaller font here...
this thing here is a source block
containing shell code. Actually it
contains lots of comments and
just this line here of non-trivial shell
code... and we can run a code block by
putting the cursor - the point - inside
the code block and typing `C-c C-c'.
If I do that
what happens is that Org creates
a second block here called "results"
with the result of this command here
formatted in a certain way, as columns...
Let me undo this.
It turns out that typing `C-c C-c'
executes this function here,
`org-babel-execute-src-block'...
so executing this sexp is equivalent to
typing `C-c C-c'...
(undo again)
and I can learn more about `C-c C-c'
in Org mode by running this key sequence
here: `M-h M-k', which is
a key sequence for help on keys on eev...
and if I run this
I get this temporary buffer with lots of
elisp hyperlinks...
and in these notes here I've selected
some of these elisp hyperlinks -
these two -
and I've just indented them a bit.
So I took these two hyperlinks here...
and copied to my notes and
indented them.
This one
shows the description of this function,
which is this...
the description is quite long because
the effects of this function depends on
the context...
one of these things here -
the last one - says: if the cursor is on a
code block, evaluate it.
And blah blah blah blah blah blah...
I had to set this thing here to nil
to make Org
stop asking me every time if I want
to evaluate this thing or not...
and Org also has a key sequence for
removing the results block
this key sequence is `C-c C-v k'.
I can get a lot of help about...
sorry, lots of elisp hyperlinks about
this key sequence by running this sexp
here... and I've also
selected these ones...
sorry, these ones here -
and copied them to the other buffer, and
indented them a bit...
so this sexp here
shows a description of this function
and this sexp here shows the source code
of this function - it is here.
So by executing this I can
see what are the names of the functions
that do most of the work - because this
function is quite simple, so it
essentially calls other functions to do
practically everything.
And I also wanted to understand
what the data structures associated
to a code block, because I knew that
when Org did use the code block
it had to be done in two parts...
one part was parsing
the code block and
representing it internally in a certain
way,
that I imagined that would include
information about this,
information about the beginning and
the end of the
of the code block in this buffer,
and so on...
so I asked on IRC what is the function
that does this parsing, and people
pointed me to a function called
`org-element-context',
and if I execute it here
I get a result that is too big - it
doesn't fit very well in the echo area.
So let me use one of my favorite
pretty-printing functions
to take a look at this...
it's not very pretty.
So... I can see
that the important part is here,
so I have to discard this
initial part...
if I take the cadr of
the result of this I get the part that is
most interesting - this one here...
and I can use this variant
of my favorite pretty printing function
to print it in a better way.
So, if I execute this I can see
the keywords and their values...
and, for example, suppose that I want to
understand what are these numbers here...
one thing that I can do is that I can...
well, let me take the result of this and
and put it in a variable called p...
and p now holds a property list
and I can use plist-get to
get the value of the field :begin,
and this other plist-get here to get
the value of the field :end...
and I can use the function of eev
that does these highlightings
to highlight what is the region between
the value of the field :begin
and the value of the field :end,
and when I run this I see something
funny...
this region includes these blank
lines here.
So:
I can use this thing here to understand
the data structures, and
then I can find some
non-trivial information here...
I'm just going to show another thing
that can be done with source blocks,
and what I discovered
about the source code, which is...
we can create a source block
by hand, by typing this #+BEGIN thing
and this #+END thing by hand,
but there's
a way to type that more quickly.
It is described in this node of the
Org manual, called "Structure Templates",
and it explains that
if I type `C-c C-,'
and then one of these letters here
I get these blocks...
so `s' is the one that I want,
and if I type `C-c C-,'...
there's some help here -
so I can type `s',
and I get a source block.
Here i can put "shell" or "python"
or wherever, any supported language...
and
of course I want to know how this is
implemented, how this can be extended to
other languages, and so on...
so the first thing that I did was that I
used my key sequence for
getting help on key sequences,
which is `M-h M-k',
I used it to get help on `C-c C-,'...
let me try it here... `M-h M-k C-c C-,'
I get this thing here -
and I selected
these two sexps, and copied them to
my notes - I got these ones here...
and so this one points to...
the target of this sexp here is the
description of this function,
which is this thing here...
"Insert a block structure of the
type blah blah blah
#+begin_foo/#+end_foo"...
and then it
says some more technical things here...
and I can use this sexp here to go
straight to its source code...
I mean, I can use this, and I can
click in this button here, but I prefer
to have a link that points straight to
the source code, and it's this one...
and so I can read these things here to
understand what is going on,
which variables it uses, and so on...
and it turns out that this thing uses a
variable called
`org-structure-template-alist',
and if I...
I can get help on this variable
by typing `M-h M-v' - I get a buffer
with elisp hyperlinks, like this...
and what I did was that I generated a
buffer like this, and selected some of
the most interesting hyperlinks, and
copied them to my notes... here -
so one of them is this `find-evardescr',
that
opens the description of this variable...
just let me show that
it appears here... usually people
would use `describe-variable',
but when we execute it as a sexp
it returns a big return value, here, that
messes up my screen... so I prefer to use
this variant here - `find-evardescr'.
So, yeah -
with this I can get a description of this
variable
that's a bit more technical than the
description in the
manual of Org...
and here it shows the current value of
this variable.
I can use...
actually when I was looking at this I
discovered that
there was something interesting here, and
I can could point to this something
interesting by refining this hyperlink
and making it search for this string
in the description...
so this link
opens this description of the variable
and searches for the first occurrence of
the string "src"...
and
I can also run this sexp here to go to
the place in the source code
in which this variable is defined... it's
defined with a `defcustom'... here
is its
initial value,
here is its description, here's how it
can be customized, and so on...
and
this is just a reminder that I can create
source blocks by typing something
like this... I think that I've used that
before -
if I type `C-c C-, s'
I get a
source block that can I edit by hand, and
this is an example of a source block
created in that way, with some
non-trivial shell commands here, inside...
Yeah, that's it - that's what I
wanted to show. Oh, no, no - just one thing
more...
by default when I type `M-e' on
a sexp the `M-e' opens the target
of the sexp in the same window...
so if I execute this
I open the description of this
function in the same window, but if I
execute it... if execute `M-e' with
the prefix 3, I mean, if I type `M-3 M-e',
or `M-2 M-e', I display
the target in the right window,
and this is practical because then I can
show all these targets
very quickly - here.
Yeah! So, that's it...
that's what I wanted to show in this
video. Bye! =)