1 #+title: Universal Languages
2 #+author: Richard Westhaver
3 #+email: ellis@rwest.io
5 #+setupfile: ../../clean.theme
7 This document describes a
*U-Language* as described by the late great
8 [[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:
11 Every investigation, including the present one, has to be communicated
12 from one person to another by means of language. It is expedient to
13 begin our study by calling attention to this obvious fact, by giving a
14 name to the language being used, and by being explicit about a few of
15 its features. We shall call the language being used the
16 U-Language. [...] There would be no point in calling attention to it,
17 if it were not for the fact that language is more intimately related
18 to our job than of most others.
21 In this document, we will be calling attention to our own language -
22 examining it, and describing how it works.
24 Our job is to solve problems. Hard problems preferred. So we ought to
25 pay close attention to the language we use because it brings the
26 reader and writer
/closer/ to the problem at hand.
28 For starters, we are primarily concerned with
/written languages/ like
29 the one you're reading now. We will skip past the obvious details -
30 English is our primary form of communication for example. The line you
31 are reading currently is a sentence which is part of a paragraph.
33 There are some non-obvious questions which deserve inquiry though.
35 - *Who is this for?* \\ 36 This document is for authors and readers alike. It is a loose
37 specification, but also serves as introductory material into our
38 communication and design philosophy.
40 - *What is this for?* \\ 41 The purpose of this document is to provide a
/standard of 44 All sources we write attempt to conform to this standard but this is
45 not strictly enforced. If there is a reason to not comply with a
46 rule, it is already broken.
50 :ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1 52 [[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally
[[https://orgmode.org/][Org Mode]] is our word
55 If you are already familiar with Emacs and Org-Mode, I recommend
56 opening the source of this document in Emacs and following along.
58 If not, I recommend browsing through the
[[https://orgmode.org/worg/][Worg resources]], but we won't
59 be getting too deep into tribal hacker knowledge of Emacs.
61 What's important to know is this: There is
/Org Syntax/ and
62 /Org-mode/ - these are different things.
64 Our
=ulang= is almost
/exclusively/ based on
/Org Syntax/ and we are
65 not concerned about
/Org-mode/ the application in this document.
71 As the title suggest we refer to our
*U-Language* as
*ulang*. Each
72 section of this document describes a feature.
74 In Org, headings can be summarize as any line starting with a star:
=* 75 H1=. Headings can be nested or 'demoted' by prepending another star:
78 This is a useful pattern which we apply outside of Org - most commonly
81 In our source code, we use the comment character instead of a star:
84 (print "H1") ;; just an inline comment
91 A collection of
/headings/ is what we call an
*Outline* - which is
92 also the name of the major-mode utilized for this feature and of
93 course - what Org itself is derived from.
97 :ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba 100 The following keywords indicate the state of an element. They often
101 appear as the first word in a heading to indicate a
[[*Tasks][Task]].
103 - TBD :: A task to be done at a later date.
104 - TODO :: A task yet to be done.
105 - FIXME :: Item that needs fixing.
106 - WIP :: Work In Progress task.
107 - WAIT :: A suspended task.
108 - DEAD :: Item that will not be completed.
109 - DONE :: Completed task.
110 - BUG :: Designate a bug item.
111 - IDEA :: Designate an idea item.
112 - NOTE :: Designates a note item.
113 - DRAFT :: Designates a draft item.
114 - COMMENT :: A 'commented' item.
116 Tasks as they are known in Org, usually consist of a heading that
117 starts with a
[[#2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and
118 metadata which are present in our collection of tasks.
120 Our task management system is roughly a hybrid of two more
121 conventional methods: GTD and Agile. For convenience I will describe
122 these styles and how I use them separately, but the concepts may be
123 spliced differently in real tasks.
127 It's a dirty word in some tech circles - the dreaded PIs, daily
128 standups, and still nobody knows what's going on, Oh my! Do not
129 worry. For the most part we just borrow the vocabulary.
131 Our
/Agile/ workflow consists of roadmaps, features (epics/ARTs),
132 issues (user stories), and of course, tasks.
134 We reference two different types of identifiers in documentation:
135 - UUID :: ID property
136 - User-defined :: CUSTOM_ID property
138 Most of the time these Ids don't add any information for the reader -
139 the UUIDs are used to index and graph documents, CUSTOM_IDs are for
140 convenience but are rarely necessary given the many ways of
141 identifying a headline.
144 :ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e 146 Several
*global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed
147 here for convenience.
150 #+begin_src emacs-lisp :exports both :results replace pp 151 org-export-global-macros
154 #+RESULTS: ulang-macros
156 : "#+TITLE: $1\n#+AUTHOR: $2\n#+EMAIL: $3\n#+DESCRIPTION: $4\n#+SUBTITLE: $4\n#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil\n#+HTML_HEAD:
<link rel=\"stylesheet\" href=\"https://fonts.xz.style/serve/inter.css\"/>\n#+HTML_HEAD:
<link rel=\"stylesheet\" type=\"text/css\" href=\"https://cdn.compiler.company/css/new.min.css\"/>\n#+HTML_HEAD:
<link rel=\"stylesheet\" type=\"text/css\" href=\"https://cdn.compiler.company/css/night.css\"/>\n")
157 : ("opts" . "#+OPTIONS: $1\n"))
159 Macros
/are not expanded/ in source files - you will see them in the
160 form
={{{NAME(ARGS)}}}=. You will need the relevant macro definition
161 (in
=ulang.el=) in order to use some Org-Mode functions (org-export)