22
|
1
|
#+title: Universal Languages |
|
2
|
#+author: Richard Westhaver |
|
3
|
#+email: ellis@rwest.io |
8
|
4
|
#+OPTIONS: toc:t |
28
|
5
|
#+setupfile: ../../clean.theme |
5
|
6
|
|
2
|
7
|
This document describes a *U-Language* as described by the late great |
8
|
8
|
[[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]: |
1
|
9
|
|
|
10
|
#+begin_quote |
|
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. |
|
19
|
#+end_quote |
|
20
|
|
8
|
21
|
In this document, we will be calling attention to our own language - |
|
22
|
examining it, and describing how it works. |
|
23
|
|
|
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. |
|
27
|
|
|
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. |
|
32
|
|
|
33
|
There are some non-obvious questions which deserve inquiry though. |
2
|
34
|
|
8
|
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. |
|
39
|
|
|
40
|
- *What is this for?* \\ |
|
41
|
The purpose of this document is to provide a /standard of |
|
42
|
communication/. |
2
|
43
|
|
8
|
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. |
2
|
47
|
|
8
|
48
|
* Org Mode |
4
|
49
|
:PROPERTIES: |
25
|
50
|
:ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1 |
4
|
51
|
:END: |
8
|
52
|
[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word |
|
53
|
processor. |
2
|
54
|
|
8
|
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. |
2
|
57
|
|
5
|
58
|
If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't |
8
|
59
|
be getting too deep into tribal hacker knowledge of Emacs. |
2
|
60
|
|
8
|
61
|
What's important to know is this: There is /Org Syntax/ and |
|
62
|
/Org-mode/ - these are different things. |
|
63
|
|
|
64
|
Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are |
|
65
|
not concerned about /Org-mode/ the application in this document. |
5
|
66
|
|
8
|
67
|
* ulang |
|
68
|
:PROPERTIES: |
|
69
|
:ID: ulang |
|
70
|
:END: |
|
71
|
As the title suggest we refer to our *U-Language* as *ulang*. Each |
|
72
|
section of this document describes a feature. |
|
73
|
** Outlines |
|
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: |
|
76
|
=** H2=. |
6
|
77
|
|
8
|
78
|
This is a useful pattern which we apply outside of Org - most commonly |
|
79
|
in our code comments. |
6
|
80
|
|
8
|
81
|
In our source code, we use the comment character instead of a star: |
|
82
|
#+begin_src lisp |
|
83
|
;;; foo |
|
84
|
(print "H1") ;; just an inline comment |
|
85
|
;;;; bar |
|
86
|
(print "H2") |
|
87
|
;;; baz |
|
88
|
(print "H1") |
|
89
|
#+end_src |
6
|
90
|
|
8
|
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. |
5
|
94
|
|
8
|
95
|
** Keywords |
4
|
96
|
:PROPERTIES: |
25
|
97
|
:ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba |
4
|
98
|
:END: |
2
|
99
|
|
8
|
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]]. |
2
|
102
|
|
8
|
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. |
|
115
|
** Tasks |
|
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. |
1
|
119
|
|
8
|
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. |
2
|
124
|
|
8
|
125
|
- *GTD* \\ |
|
126
|
- *Agile* \\ |
|
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. |
2
|
130
|
|
8
|
131
|
Our /Agile/ workflow consists of roadmaps, features (epics/ARTs), |
|
132
|
issues (user stories), and of course, tasks. |
25
|
133
|
** IDs |
8
|
134
|
We reference two different types of identifiers in documentation: |
25
|
135
|
- UUID :: ID property |
|
136
|
- User-defined :: CUSTOM_ID property |
2
|
137
|
|
8
|
138
|
Most of the time these Ids don't add any information for the reader - |
25
|
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. |
8
|
142
|
** Macros |
5
|
143
|
:PROPERTIES: |
25
|
144
|
:ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e |
5
|
145
|
:END: |
|
146
|
Several *global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed |
|
147
|
here for convenience. |
|
148
|
|
|
149
|
#+name: ulang-macros |
6
|
150
|
#+begin_src emacs-lisp :exports both :results replace pp |
5
|
151
|
org-export-global-macros |
|
152
|
#+end_src |
|
153
|
|
|
154
|
#+RESULTS: ulang-macros |
6
|
155
|
: (("header" . |
|
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")) |
5
|
158
|
|
|
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 |
8
|
161
|
(in =ulang.el=) in order to use some Org-Mode functions (org-export) |
|
162
|
with our docs. |
5
|
163
|
|