Universal Language

1. Introduction

This document is for contributors and curious readers. It is a loose specification which describes the fundamental rules of how we write in prose, documentation, and other contexts.

All sources we write attempt to comply to this specification but it is never strictly enforced. If there is a reason to not comply with a rule, it is already broken.

Every investigation, including the present one, has to be communicated from one person to another by means of language. It is expedient to begin our study by calling attention to this obvious fact, by giving a name to the language being used, and by being explicit about a few of its features. We shall call the language being used the U-Language. […] There would be no point in calling attention to it, if it were not for the fact that language is more intimately related to our job than of most others. – Haskell Curry

In this document, we will be calling attention to our own language - examining it, and describing how it works.

Our job is to solve problems. Hard problems preferred. So we ought to pay close attention to the language we use because it brings the reader and writer closer to the problem at hand.

We are primarily concerned with written languages like the one you're reading now. We will skip past the obvious details - English is our primary form of communication for example. The line you are reading currently is a sentence which is part of a paragraph.

1.1. Org Mode

GNU Emacs is our text editor, so naturally Org Mode is our word processor.

If you are already familiar with Emacs and Org-Mode, I recommend opening the source of this document in Emacs and following along.

If not, I recommend browsing through the Worg resources, but we won't be getting too deep into tribal hacker knowledge of Emacs.

2. ulang

Our U-Language is colloquially termed ulang. Each section of this document describes an Org syntax component and how it is used in our writing.

2.1. Emphasis

Text Emphasis in Org covers the range you would expect from any other markup: 

- *bold*
- /italic/
- _underlined_
- =verbatim=
- ~code~
- +strike-through+

\

  • Text emphasis markers may appear in code comments as long as they do not cause any conflicts with the host language, although they should be restricted to the Commentary section.
  • code may sometimes be written instead with verbatim emphasis - the distinction is only important for specific export backends which support it - see this thread for details.

2.3. Headings

In Org, headings can be summarize as any line starting with a star: * H1. Headings can be nested or 'demoted' by prepending another star: ** H2. 

* H1
** H2
*** H3
** H2
* H1

This is a useful pattern which we apply outside of Org - most commonly in our code comments.

In our source code, we use the comment character instead of a star: 

;;; foo
(print "H1") ;; just an inline comment
;;;; bar
(print "H2")
;;; baz
(print "H1")

/// foo
println!("H1");
//// bar
println!("H2");
/// baz
println!("H1");

2.4. Todo Keywords

TODO keywords are often used to keep track of the state of a TODO Item, but may also be extended to support a variety of stateful item types beyond just simple tasks.

We do not specify any

The following keywords form the simple set of task states.

  • TBD
  • TODO
  • WIP
  • HOLD
  • WAIT
  • DONE
  • NOPE
* PROJECT project
** DONE foo
** TODO bar
** TBD baz
** WIP test foo

2.5. Tags

Tags are used liberally throughout our documents. They are simple strings usually following a headline as a :-separated list.

A tag can be any text without newlines, although it is recommended to treat them as unique identifiers and usage of whitespace is discouraged (but not disallowed). 

* foobar                                               :tag1:tag2:@home:!today

2.5.1. Tag Prefixes

Some of ourtags are prefixed with a character which indicates a special tag category:

@
location-tag
A location tag refers to some context-dependent named point in space, such as a user's home address, a popular fast food restaurant, or a specific room found in most houses.
  • @home, @taco-bell, @bedroom
!
timestamp-tag
Timestamp tags refer to some point in time, often named for convenience. You may use literal Timestamps too. Timestamp tags should not directly reference scheduling information, doing so is often a code-smell.
  • !now, !christmas, !someday
#
anchor-tag
An anchor tag implies a link to the object identified by some ID.
  • #readme, #a7ae1b2a-559e-46e9-8cab-33e39a218288, #custom-id

2.6. Properties

Properties are key:value pairs which are associated with a heading or file and stored in a dedicated Drawer. 

* WIP do stuff                                                         :@lab:
:PROPERTIES:
:CREATED:  <2024-08-24 Sat 19:09>
:ID:       62da3982-7a83-4b27-ab7e-55949fd3e2a3
:EFFORT: 24:00
:END:

2.6.1. ID

Org supports two built-in identifier properties:

ID
Unique, machine-generated
CUSTOM_ID
User-defined

These IDs don't add any information for the reader - the IDs are used to index and associate headings. All headings are assigned an ID automatically which should never be changed.

CUSTOM_IDs are for convenience and extensions, but are rarely necessary given the many ways of identifying a headline.

2.7. File Keywords

File keywords, also known as In-Buffer Settings are similar to properties in the sense that they are key/value pairs, but they only appear at the top of a file before any content and use a different syntax. 

#+title: some file title
#+author: some user
#+PROPERTY DESCRIPTION assigning a property via file keyword
some content
* a headline
:PROPERTIES:
:DESCRIPTION: just a property, not a file keyword
:END:

2.8. Tables

Org Tables offer some pretty advanced spreadsheet capabilities which we won't delve into here. Plain tables can be identified in documents by lines starting with the | character: 

| col1 | col2 | col3 |
|------+------+------|
|    1 | foo  | bar  |

2.9. Blocks

Org Blocks consist of a body wrapped in a pair of lines which look like File Keywords prepended with BEGIN_ and END_.

Simple blocks such as example and center only have a special meaning during publishing: 

#+begin_example
this is an example block
#+end_example

#+begin_center
this is a centered block
#+end_center

2.9.1. Code Blocks

Code Blocks are used to embed source code into a document. They always start with #+BEGIN_SRC and end with #+END_SRC: 

#+begin_src emacs-lisp
  (message "an emacs-lisp code block inside an org document")
#+end_src

You can embed virtually any type of source code in side a code block, execute it in-place, and control how both the source code and results are presented in the document. Source code blocks may also be collected in a Library of Babel and re-used across many documents.

2.9.2. Dynamic Blocks

Dynamic Blocks as the name implies are blocks with contents that are dynamically updated. These blocks always begin with #+BEGIN: followed by a space, the name of the dynamic block and any parameter values, and end with #+END:. The dynamic block name is taken from the name of a function which matches org-dblock-write:NAME. This function is called with the parameter values and replaces the body of the block.

The only built-in dynamic block is the clocktable: 

#+BEGIN: clocktable
#+CAPTION: Clock summary at [2024-09-06 Fri 15:23]
| Headline     | Time   |
|--------------+--------|
| *Total time* | *0:00* |
#+END:

Dynamic blocks are designed for user extension and are a powerful tool to programatically summarize information.