:PROPERTIES:
:ID:       b804fe54-d7f4-4809-be9e-50779b4b9314
:ANKI_DECK: Emacs
:END:
#+title: Anki: Org mode
#+date: "2021-05-05 22:49:10 +08:00"
#+date_modified: "2021-05-12 11:07:56 +08:00"
#+language: en

* org-babel
:PROPERTIES:
:ANKI_NOTE_TYPE: Styled cards
:ANKI_NOTE_ID: 1620236488535
:END:
** Front
What makes Org mode popular for reproducible research?
** Back
org-babel, the library that enables superpowers for Org mode source code blocks.

Among the list of features, org-babel makes the following things easier for creating lab notebooks.

- Execute the source code block and print results.
- Create files from source code blocks, making it possible to create an entire computational report with a single Org mode document.
- Metaprogramming with [[https://orgmode.org/manual/Noweb-Reference-Syntax.html][noweb-inspired system]] making dynamic content possible.
- Individual control over source code blocks with sessions, export options, and variables.
- Pass values between different source code blocks even in different programming languages.

* org-babel modes
:PROPERTIES:
:ANKI_NOTE_TYPE: Styled cards
:ANKI_NOTE_ID: 1620236489830
:END:
** Front
How to make org-babel pass values between different source code blocks?
** Back
:PROPERTIES:
:ID:       5c959c6a-04fb-4154-becc-86eeb15b20ad
:END:
First, configure org-babel to work in functional mode (i.e., ~:results value~) in a source code block.
With functional mode, it will return values which will be handled by org-babel.

#+begin_src org
,#+name: num
,#+begin_src python  :results value
return 53
,#+end_src
#+end_src

The value cannot be passed unless it has a name that others can reference yet so add a name property to the source code block (i.e., ~#+name: ${NAME}~).

Now here's a different source code block written in a different language.
To pass a value, you have to configure with ~:var ${VARNAME}=${NAME}~.

#+begin_src org
,#+begin_src ruby  :var num=num  :results output
print(num)
,#+end_src
#+end_src

* Creating files with Org mode
:PROPERTIES:
:ANKI_NOTE_TYPE: Styled cards
:ANKI_NOTE_ID: 1620236490049
:END:
** Front
How to create files with Org mode source code blocks?
** Back
The ~:tangle~ option enables extracting code blocks into files.
Accepted values include =yes=, =no=, or a relative path to the Org document where the file will be written.

* Dynamic content with Org mode
:PROPERTIES:
:ANKI_NOTE_TYPE: Styled cards
:ANKI_NOTE_ID: 1620236491388
:END:
** Front
Is creating dynamic content possible?
If so, how?
** Back
Yes!

With source code blocks and the [[https://orgmode.org/manual/Noweb-Reference-Syntax.html][noweb]] option enabled, you can make meta-programming in Org.
You can declare a function by assigning a name on the code block (i.e., ~#+name: ${FUNC_NAME}~).

Here's an example of a source code block with a default argument.

#+begin_src org
,#+name: greeting
,#+header:  :var name="World"
,#+begin_src sh
echo "Hello ${name}"
,#+end_src
#+end_src

You can then call the function in different ways:

- For calling it inline, ~call_${FUNC_NAME}()~.
- For creating a block, ~#+call: ${FUNC_NAME}()~.
- For invoking inside a code block, ~<<${FUNC_NAME}()>>~, but you have to enable noweb (e.g., ~:noweb yes~).

You can then pass header arguments by appending in square brackets (=[]=) before invoking it — e.g., ~call_greeting[:results replaces]()~, ~#+call: greeting[:results replace]()~, ~<<greeting[:results replace]()>>~.

* Asciidoctor-styled callouts
:PROPERTIES:
:ANKI_NOTE_TYPE: Styled cards
:ANKI_NOTE_ID: 1620236492755
:END:
** Front
Are callouts possible?
If so, how?
** Back
Surprisingly, yes!
It is just hidden on the documentation.
Specifically, on the [[https://orgmode.org/manual/Literal-Examples.html][Literal examples]] section of the Org mode manual.

Here's an example to do it.

#+begin_src org
,#+begin_src python
print("Hello world") # (ref:hello)
print(2 + 5)         # (ref:num)
,#+end_src

In [[(hello)][line 1]], we have printed the traditional "Hello world" program.
In [[(num)][the second line]], we've done a simple arithmetic and printed it into the console.
#+end_src

To create Asciidoctor-styled callouts, create a reference inside of the code block and refer to it (i.e., ~(${ref})~).

* Timestamps and durations
:PROPERTIES:
:ANKI_NOTE_TYPE: Styled cards
:ANKI_NOTE_ID: 1620386886707
:END:
** Front
How to denote timestamps and durations in Org mode?
** Back
#+begin_src org
# A timestamp looks like this.
<2021-05-07 Fri>

# To make a duration, just put two dashes between two timestamps.
<2021-05-07 Fri>--<2021-05-08 Sat>
#+end_src

To make creating timestamps easier, execute ~org-time-stamp~ (or whatever keybinding you've set).

* Deadlines and schedules
:PROPERTIES:
:ANKI_NOTE_TYPE: Styled cards
:ANKI_NOTE_ID: 1620607177893
:END:
** Front
How to make deadlines and schedules?
** Back
Just prepend the keywords =DEADLINE= and =SCHEDULED=, respectively.

#+begin_src org
DEADLINE: <2021-06-30 Wed>
SCHEDULED: <2021-06-29 Tue>
#+end_src

* File navigation
:PROPERTIES:
:ANKI_NOTE_TYPE: Styled cards
:ANKI_NOTE_ID: 1620607179217
:END:
** Front
Give some ways how to navigate Org mode documents quickly.
** Back
- I don't need to explain what ~org-babel-next-src-block~ and ~org-babel-previous-src-block~ does.

- ~org-backward-heading-same-level~ is the same as ~org-forward-heading-same-level~ but moves one headline backwards.

- ~org-forward-heading-same-level~ moves one headline forward in the same level.
  Useful for navigating sections and subsections.

- ~org-goto~ creates an interface for showing the outline and it is a great navigation function.
  Highly recommend to use it with a completion interface (e.g., ~counsel-org-goto~, ~counsel-org-imenu~).

- ~org-num-mode~ adds a (non-persistent) counter to the document.
  Very helpful in navigating larger files.

- ~org-sort~ will sort the entries into your preferred criteria.
  It also works on a list of items which is very useful if one of the list items has more than one line.

* Editing source code blocks
:PROPERTIES:
:ANKI_NOTE_TYPE: Styled cards
:END:
** Front
What function creates a buffer for certain elements in org-mode but it is especially useful for editing source code blocks where it will open with the correct major mode?
** Back
~org-edit-special~