CybOrg Mode

2020-06-01

Human beings enhanced by machine parts, often called cyborgs, are a staple of the science-fiction and comic books. The, very aptly named, hero Cyborg, is a good example of this. Due to advanced mechanical modifications he not only has greatly increased strength and the ability to fly, but he is able to interface directly with computer systems to organize and plan ahead. These skills make him an important member of many superhero teams such as the Justice League and Teen Titans.

Thankfully for us, even without any of the cybernetic implants that Cyborg has, there exists some great tools to help organize, document and plan ahead. One of such tools is called Org-mode. Org-mode, also denoted as Org mode or even more simply as Org, is a system for organizing notes, plans, authoring documents and many other tasks. One of its main benefits is that although specialized tools exist to help create and edit Org documents, all Org documents are plain text files. This means that the format is very portable and can be used and edited on any platform which can edit text files. In this article we give a brief introduction to Org mode with an example based on the hero Cyborg.

Org documents can be outlined with a tree structure using headlines. Suppose that we want to describe various information about Cyborg, such as his biography, his powers, his relationships and his schedule. For each of these we can use an asterisk (*) symbol followed by some text to create a headline in the document as follows:

* Biography
* Powers
* Relationships
* Cyborg's Schedule

We can add nested headlines by increasing the number of asterisks in front of a section name. For example, if we want to create two headlines under relationships detailing Cyborgs team affiliations, as well as his villains, we can do that:

* Biography
* Powers
* Relationships
** Team Affiliations
** Villains
* Cyborg's Schedule

Of course while headlines can help us structure a document, text is an integral part of it. A simple biography can be shown as one would expect:

* Biography
Vic Stone was a high school athlete when a tragic accident nearly killed him and destroyed most of this body. His father, Dr. Silas Stone, used his scientific knowledge and advanced technology to save his life by augmenting him with machine parts.
Living now as a cyborg, a being with both organic and machine parts, he is now has super strength, increased durability and a control over advanced technology and weaponry.
Although he continues to struggle with his newfound status as both man and machine, he uses his newfound powers as a superhero.
* Powers
* Relationships
** Team Affiliations
** Villains
* Cyborg's Schedule

We can also create lists in the document. For example we can give an unordered list of Cyborg's powers such as super strength and instant weaponary by prefacing each item on a new line by a hyphen (-):

* Biography
Vic Stone was a high school athlete when a tragic accident nearly killed him and destroyed most of this body. His father, Dr. Silas Stone, used his scientific
knowledge and advanced technology to save his life by augmenting him with machine parts.
Living now as a cyborg, a being with both organic and machine parts, he is now has super strength, increased durability and a control over advanced technology and weaponry.
Although he continues to struggle with his newfound status as both man and machine, he uses his newfound powers as a superhero.
* Powers
- super strength
- advanced technology,
- instant weaponry
- genius-level intellect
- control over technology
- computer hacking
- durability
- teleportation
* Relationships
** Team Affiliations
** Villains
* Cyborg's Schedule

Note that the document is now getting larger and the parts of what we want to focus on to show here, the powers, can get lost in the other information. One of the strengths of Org-mode that even though it can be viewed and edited as plain text, there exists quite a bit of tooling to help navigate, edit and make use of the described structures. The editor emacs and its various flavours such as spacemacs that I personally use have excellent features for these tasks. However other editors such as Visual Studio Code have plugins to support Org-mode as well.

One of the basic features to help such editors provide is to fold headlines under which we do not want to see all the content in detail and unfold it for those that we do. In the following animation we show how this can be done on a portion of a more extended version of the Cyborg document:

Folding and unfolding headlines in Org document using Spacemacs

The above image shows how the spacemacs editor handles Org documents. By simply pressing tab on headlines we can fold (i.e. not show the underlying content) and unfold (i.e. showing the underlying content) them as we please and directing our attention to parts of the document we want to view and edit. It also shows how editor support uses the underlying structure for additional visualizations, such as on the level of headlines, even though the underlying document is still plaintext.

Expanding on our example we can describe the Team Affiliations and the Villains as lists as well. For the list of Team Affiliations we will use an ordered list, which can be done by using a number followed by a dot, e.g.: 1. 2. for the list indicators. Note for brevity we now only show the new/relevant portions of the full Org document in the examples as opposed to the whole.

* Relationships
** Team Affiliations
1. Justice League
2. Teen Titans
3. Doom Patrol
** Villains
- Lex Luthor
- Deathstroke

Another interesting feature in Org documents are TODO items. Any headline can be made a TODO in them by prefacing it with TODO. For example in a headline of Cyborg's schedule we can put two TODO items for things Cyborg wants to do at some point: attend a Justice League Meeting and Upgrading Equipment.

There are various ways such TODO items could be used similarly to folding or unfolding headlines. In emacs/spacemacs such actions, and many others relating to various aspects of an Org document, can be done by commands. For example the command org-show-todo-tree can take ensure that all the headlines are folded as much as possible and only the TODO headlines are unfolded. Similarly the command org-todo cycles between not marking the headline with a TODO, marking it with a TODO or marking it with DONE denoted that the item has been completed.

Toggling using the command the command `org-todo` for headlines in Org document using Spacemacs

The above image shows how the command org-todo can cycle between the TODO states of the Justice League Meeting headline. In addition, it also shows a few other features.

First is the associating a date with the TODO item, in particular when it is scheduled. By toggling the TODO to DONE, our editor uses the current time to mark when the task was finished. This allows for a nice way to create a checklist of the things that have to be done and marking them off.

Another aspect is the use of markup around 'must' and 'Lex Luthor'. Enclosing a phrase with an underscore underlines the phrase while enclosing it between asterisks (*) makes it bold. Markups for italicizing (enclosing it between slashes (/)), code fragments and others also exist.

The full list of TODO items in Cyborg's schedule is as follows.

*** TODO Justice League Meeting
    SCHEDULED: <2024-08-02>
    Something _must_ be done about *Lex Luthor*. He seems to be planning an attack on /Metropolis/ with the help of *Deathstroke*. 
*** TODO Upgrade Equipment
    SCHEDULED: <2024-06-01>
    Enhance arm cannon.

One of the most interesting features of Org mode that we will cover in this article is the ability to embed fragment of code in an Org document that can be executed in the right environment. In Cyborg's schedule one of the upcoming items is to enhance his arm cannon. In order to prepare for this, and to illustrate our code embedding, a simple Weapon Damage calculator application was written in Python:

  arm_cannon = {"name": "Arm Cannon", "power": 8}
  reinforced_door = {"name": "Reinforced Door", "armor": 3}

  def wdc(weapon, target):
    damage = weapon["power"] - target["armor"]
    if damage<0:
      return 0
    else: 
      return damage

  damage_done = wdc(arm_cannon, reinforced_door)
  print("Using the weapon " + arm_cannon["name"] + " with " + str(arm_cannon["power"]) + " power,")
  print("against the target " + reinforced_door["name"] + " with " + str(reinforced_door["armor"]) + " armor,")
  print("results in " + str(damage_done) + " damage.")

This code aims to use features of Cyborg's arm cannon to calculate damage on the target and to write these features out along with the resulting damage.

We can embed this code fragment by using the property system to give this fragment a name and denote some other attributes. This property system is essentially a key-value system in Org mode that is used for all types information represented with key-value pairs. For example the following two properties describe the title and description of the Org document:

#+title: Cyborg Agenda
#+description: An introduction to org mode by creating an org document for information on the superhero Cyborg.

For the code we want to embed we want set the properties on how we name this fragment, where the source begins and ends, what language it is and what should be done with the results. This looks as follows within the Org document:

* Weapon Damage Calculator
#+NAME: wdc
#+BEGIN_SRC python :results output
  arm_cannon = {"name": "Arm Cannon", "power": 8}
  reinforced_door = {"name": "Reinforced Door", "armor": 3}

  def wdc(weapon, target):
    damage = weapon["power"] - target["armor"]
    if damage<0:
      return 0
    else: 
      return damage

  damage_done = wdc(arm_cannon, reinforced_door)
  print("Using the weapon " + arm_cannon["name"] + " with " + str(arm_cannon["power"]) + " power,")
  print("against the target " + reinforced_door["name"] + " with " + str(reinforced_door["armor"]) + " armor,")
  print("results in " + str(damage_done) + " damage.")
#+END_SRC
#+RESULTS: wdc

This embeds the weapon damage calculator as a source fragment named wdc, while also setting up where the results will be show in the document. Now if we execute the command org-babel-execute-src-block we can see the results directly within the document:

Executing the source block to see the results directly within the Org document

That is it for this tutorial, hopefully I have given a glimpse of what Org mode can do, and gives you some idea on how it can enhance your organizing, planning and note taking. Here I have not even touched on many other great features such as authoring documents and converting to other formats, using it as a spreadsheet system and many more. For further resources on this tool take a look at the official Org mode website, as well the excellent video tutorial by GDQuest on using the Spacemacs editor with Org mode. The Org document that was built up can also be found in its entirety at a github repository along with some extra documentation.

Hopefully you have enjoyed the article and if you want to enhance yourself with one of the best note taking and planning tools around give Org mode a shot.