• Org-Mode
  • What is org?
  • As a markup language.
  • And beyond
  • Navigating and narrowing Org files
  • Why?
• Org-Babel
  • What is org-babel?
• Literate Programming
  • What is literate programming?
  • Literate README’s

Org aims to organize you. Your notes, your tasks, your planning, all is handled best in Org.

Org often gets confused with a markup langauage. In reality it is a (major) ‘mode’. To those unfamiliar with Emacs a ‘mode’ defines the interaction aspects of a buffer. Every buffer has a single major mode and then as many minor-modes as the user desires. For example, to edit Web files Web-Mode can be used as the major mode (this would give you syntax highlighting, auto-completion support, etc), if Emmet support is also wanted, Emmet-mode (a minor mode) could then be turned on as well.

While many online services like github bitbucket are supporting ‘.org’ files and displaying them correctly, this is only half the picture, the other part is the interaction environment itself.

Org has everything markdown has to offer such as:

• Unordered lists (such as this one)
• Ordered lists
• Headlines
• Links

Org offers the concept of Todo’s

• [ ] any item in a plain list can be turn into a checkbox
• [ ] these can be interacted with using C-c C-c

So these aren’t impossible to create in Markdown, but the auto-formatting and spreadsheet capabilities are next-level. Simply type ‘|’between columns and hit <TAB> upon row completetion. Let’s look at these as spreadsheets:

Words enclosed between : : on a headline are tags for that headline. For example, I have tagged ‘Todos’ and ‘Checkboxes’ with ‘task_management’.

Org supports time stamping anywhere with C-c . <2018-07-20 Fri>

Tab folds and unfolds content. C-M variants of emacs navigation commands work across headline items.

Sparse trees can be generated to narrow down to the information you need using C-c /.

Lastly, let’s discuss why you might want to use this for notes. Project planning gets to remain in a plain-text format while providing the interactivity that other software uses as far an engaging with it. Why does plain text matter? Version control. Plain and simple. Project planning evolves as much as code does yet documents that are commonly ‘google drive’ docs/sheets don’t hold their history in the same way, don’t get commit logs and versioning is often hand-documented.

Org babel allows the inclusion of source code blocks in your org file. This isn’t that same as enclosing code between 3 backticks as in Markdown, that merely displays code properly. Babel blocks are more like portals to other ‘major-modes’ that house actionable code.

function factorial (n) {
  function fact(n, acc) {
    if (n < 2) {
      return acc;
    } else {
      return fact(n-1, n * acc);
    }
  }

  return fact(n, 1)
}

console.log(factorial(5))

pressing C-c C-c in the above block actually runs and evaluates that code

‘tangling’ allows the blocks to be exported together. ‘exporting’ allows single blocks to dictate where they live (generated by org). variables can be used in each block and across block. And results from one block can be passed to one another.

Furthur discussing org-babel is better suited with context.

Literate programming is a programming paradigm introduced by Donald Knuth in which a program is given as an explanation of the program logic in a natural language, such as English, interspersed with snippets of macros and traditional source code, from which a compilable source code can be generated.

That’s the boring definition and I’d be hard-pressed to find someone who would want to wrap their entire codebase in narrative prose. Let’s take about where Org really shines, README’s for project configuration.

Many readmes include steps the developer has to take to get up and running. Lets take a look at the most common of these. How many times have you seen, clone the repo and run yarn… Now imagine the following:

Run the following command in shell by typing C-c C-c

yarn

Notice that we also get output in the document. Othertimes README’s may describe an API, or describe some endpoints. Forcing you elsewhere to actually test those endpoints.

Lets take a look at the following:

Press C-c C-c in the following block to execute the people API endpoint. Note the ID passed to ‘people’ that specifies which person (1, Luke Skywalker)

GET https://swapi.co/api/people/1

Here the results of that fetch are piped in as a variable to the next block.

console.log(JSON.parse(data.slice(data.indexOf('{'), data.lastIndexOf('}') + 1)).name);

The above block could be parsed in any babel-supported language, fed to any babel-supported language etc…

reset

set title "Putting it All Together"

set xlabel "X"
set xrange [-8:8]
set xtics -8,2,8


set ylabel "Y"
set yrange [-20:70]
set ytics -20,10,70

f(x) = x**2
g(x) = x**3
h(x) = 10*sqrt(abs(x))

plot f(x) w lp lw 1, g(x) w p lw 2, h(x) w l lw 3

this doesnt need to be evaulated, ANY language is support re: display and ‘mode’ interactions

Alice -> Bob: synchronous call
Alice ->> Bob: asynchronous call

:Up first, do this;
:Then this;

start

if (GraphViz installed?) then (yes)
 :process all\ndiagrams;
else (no)
:process only
  __sequence___and___activity___diagrams;
endif

stop

@startuml
left to right direction
skinparam packageStyle rectangle
actor customer
actor clerk
rectangle checkout {
  customer -- (checkout)
  (checkout) .> (payment) : include
  (help) .> (checkout) : extends
  (checkout) -- clerk
}
@enduml

+---------+            +-------------+
|{d}      |            | {s}         |
|  one    | -------->  |  two        |
|         |     |      |             |
+---------+     |      +-------------+
                |
                |
                |       +------------------+
                |       |   {io}           |
                +-------+  cRED            |
                        | some other stuff |
                        +------------------+