1
|
1
|
#+title: Universal Language |
0
|
2
|
#+author: Richard Westhaver |
|
3
|
#+email: ellis@rwest.io |
1
|
4
|
#+setupfile: ../clean.theme |
|
5
|
#+infojs_opt: toc:nil home:https://compiler.company up:./ view:showall |
|
6
|
* Introduction |
|
7
|
:PROPERTIES: |
|
8
|
:ID: e63d129f-9024-4cd8-9e2c-77f4bc614663 |
|
9
|
:END: |
0
|
10
|
This document describes a *U-Language* as described by the late great |
|
11
|
[[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]: |
|
12
|
#+begin_quote |
|
13
|
Every investigation, including the present one, has to be communicated |
|
14
|
from one person to another by means of language. It is expedient to |
|
15
|
begin our study by calling attention to this obvious fact, by giving a |
|
16
|
name to the language being used, and by being explicit about a few of |
|
17
|
its features. We shall call the language being used the |
|
18
|
U-Language. [...] There would be no point in calling attention to it, |
|
19
|
if it were not for the fact that language is more intimately related |
|
20
|
to our job than of most others. |
|
21
|
#+end_quote |
|
22
|
|
|
23
|
In this document, we will be calling attention to our own language - |
|
24
|
examining it, and describing how it works. |
|
25
|
|
|
26
|
Our job is to solve problems. Hard problems preferred. So we ought to |
|
27
|
pay close attention to the language we use because it brings the |
|
28
|
reader and writer /closer/ to the problem at hand. |
|
29
|
|
|
30
|
For starters, we are primarily concerned with /written languages/ like |
|
31
|
the one you're reading now. We will skip past the obvious details - |
|
32
|
English is our primary form of communication for example. The line you |
|
33
|
are reading currently is a sentence which is part of a paragraph. |
|
34
|
|
1
|
35
|
- This document is for authors and curious readers. It is a loose |
0
|
36
|
specification, but also serves as introductory material into our |
|
37
|
communication and design philosophy. |
1
|
38
|
- All sources we write attempt to comply to this standard but it is |
0
|
39
|
not strictly enforced. If there is a reason to not comply with a |
|
40
|
rule, it is already broken. |
|
41
|
|
1
|
42
|
** Org Mode |
0
|
43
|
:PROPERTIES: |
|
44
|
:ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1 |
|
45
|
:END: |
|
46
|
[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word |
|
47
|
processor. |
|
48
|
|
|
49
|
If you are already familiar with Emacs and Org-Mode, I recommend |
|
50
|
opening the source of this document in Emacs and following along. |
|
51
|
|
|
52
|
If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't |
|
53
|
be getting too deep into tribal hacker knowledge of Emacs. |
|
54
|
|
|
55
|
What's important to know is this: There is /Org Syntax/ and |
|
56
|
/Org-mode/ - these are different things. |
|
57
|
|
|
58
|
Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are |
|
59
|
not concerned about /Org-mode/ the application in this document. |
|
60
|
|
1
|
61
|
For the remainder of this document, we assume basic knowledge of Org |
|
62
|
Mode. |
|
63
|
|
0
|
64
|
* ulang |
|
65
|
:PROPERTIES: |
1
|
66
|
:CUSTOM_ID: ulang |
|
67
|
:ID: 236227a5-b30c-4548-8cad-360428d74d67 |
|
68
|
:END: |
|
69
|
Our *U-Language* is colloquially termed *ulang*. Each section of this |
|
70
|
document describes a feature or property of our ulang. |
3
|
71
|
** Glossary |
|
72
|
*** Terms |
|
73
|
*** Acronyms |
|
74
|
** Dictionary |
|
75
|
compiler.company:2628 |
1
|
76
|
** Emphasis |
|
77
|
:PROPERTIES: |
|
78
|
:ID: 88bf1177-b5b7-4945-8bdc-5229803e617e |
0
|
79
|
:END: |
1
|
80
|
We derive all text emphasis syntax for rich contents from [[https://orgmode.org/manual/Emphasis-and-Monospace.html][Org Mode]]. |
|
81
|
#+name: org-emphasis |
|
82
|
#+begin_src org |
|
83
|
- *bold* |
|
84
|
- /italic/ |
|
85
|
- _underlined_ |
|
86
|
- =verbatim= |
|
87
|
- ~code~ |
|
88
|
- +strike-through+ |
|
89
|
#+end_src |
|
90
|
- *bold* |
|
91
|
- /italic/ |
|
92
|
- _underlined_ |
|
93
|
- =verbatim= |
|
94
|
- ~code~ |
|
95
|
- +strike-through+ |
|
96
|
|
|
97
|
Text emphasis markers may be embedded in any syntax as long as it does |
|
98
|
not cause any conflicts with the host language. |
|
99
|
** Headings |
|
100
|
:PROPERTIES: |
|
101
|
:ID: ed035298-f7fa-4726-ad58-2d542323bb61 |
|
102
|
:END: |
0
|
103
|
In Org, headings can be summarize as any line starting with a star: =* |
|
104
|
H1=. Headings can be nested or 'demoted' by prepending another star: |
|
105
|
=** H2=. |
|
106
|
|
1
|
107
|
#+name: org-headings |
|
108
|
#+begin_src org |
|
109
|
,* H1 |
|
110
|
,** H2 |
|
111
|
,*** H3 |
|
112
|
,** H2 |
|
113
|
,* H1 |
|
114
|
#+end_src |
|
115
|
|
0
|
116
|
This is a useful pattern which we apply outside of Org - most commonly |
|
117
|
in our code comments. |
|
118
|
|
|
119
|
In our source code, we use the comment character instead of a star: |
1
|
120
|
#+name: lisp-headings |
0
|
121
|
#+begin_src lisp |
|
122
|
;;; foo |
|
123
|
(print "H1") ;; just an inline comment |
|
124
|
;;;; bar |
|
125
|
(print "H2") |
|
126
|
;;; baz |
|
127
|
(print "H1") |
|
128
|
#+end_src |
|
129
|
|
1
|
130
|
#+name: rust-headings |
|
131
|
#+begin_src rust |
|
132
|
/// foo |
|
133
|
println!("H1"); |
|
134
|
//// bar |
|
135
|
println!("H2"); |
|
136
|
/// baz |
|
137
|
println!("H1"); |
|
138
|
#+end_src |
|
139
|
|
|
140
|
** Outlines |
|
141
|
:PROPERTIES: |
|
142
|
:ID: 7b4d3229-d85f-4464-b9d0-6beccb1f7b2e |
|
143
|
:END: |
0
|
144
|
A collection of /headings/ is what we call an *Outline* - which is |
|
145
|
also the name of the major-mode utilized for this feature and of |
|
146
|
course - what Org itself is derived from. |
|
147
|
** Keywords |
|
148
|
:PROPERTIES: |
|
149
|
:ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba |
|
150
|
:END: |
|
151
|
|
1
|
152
|
In Org, TODO keywords are used to key track of the state of a [[https://orgmode.org/manual/TODO-Items.html][TODO |
|
153
|
Item]]. |
|
154
|
|
|
155
|
In ulang, they are used for this purpose and [[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a |
|
156
|
variety of stateful item types beyond just tasks - for example =NOTE= |
|
157
|
and =PROJECT=. |
|
158
|
|
|
159
|
The following keywords indicate the state of a heading element. They |
|
160
|
often appear as the first word in a heading. |
0
|
161
|
|
|
162
|
- TBD :: A task to be done at a later date. |
|
163
|
- TODO :: A task yet to be done. |
|
164
|
- FIXME :: Item that needs fixing. |
|
165
|
- WIP :: Work In Progress task. |
|
166
|
- WAIT :: A suspended task. |
|
167
|
- DEAD :: Item that will not be completed. |
|
168
|
- DONE :: Completed task. |
|
169
|
- BUG :: Designate a bug item. |
|
170
|
- IDEA :: Designate an idea item. |
|
171
|
- NOTE :: Designates a note item. |
|
172
|
- DRAFT :: Designates a draft item. |
|
173
|
- COMMENT :: A 'commented' item. |
1
|
174
|
- PROJECT :: Designates a project item containing a sequence of tasks. |
|
175
|
|
|
176
|
#+begin_src org |
|
177
|
,* PROJECT project |
|
178
|
,** DONE foo |
|
179
|
,** TODO bar |
|
180
|
#+end_src |
|
181
|
|
|
182
|
** COMMENT Tasks |
|
183
|
:PROPERTIES: |
|
184
|
:ID: 0f4c0afd-a774-4b98-900b-1ab44f9fd2ef |
|
185
|
:END: |
0
|
186
|
Tasks as they are known in Org, usually consist of a heading that |
1
|
187
|
starts with a [[id:2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and |
0
|
188
|
metadata which are present in our collection of tasks. |
|
189
|
|
|
190
|
Our task management system is roughly a hybrid of two more |
|
191
|
conventional methods: GTD and Agile. For convenience I will describe |
|
192
|
these styles and how I use them separately, but the concepts may be |
|
193
|
spliced differently in real tasks. |
|
194
|
|
|
195
|
- *GTD* \\ |
|
196
|
- *Agile* \\ |
|
197
|
It's a dirty word in some tech circles - the dreaded PIs, daily |
|
198
|
standups, and still nobody knows what's going on, Oh my! Do not |
|
199
|
worry. For the most part we just borrow the vocabulary. |
|
200
|
|
|
201
|
Our /Agile/ workflow consists of roadmaps, features (epics/ARTs), |
|
202
|
issues (user stories), and of course, tasks. |
1
|
203
|
** Properties |
|
204
|
:PROPERTIES: |
|
205
|
:ID: 174a993b-a5dc-4324-b4f8-dda8101a55b7 |
|
206
|
:END: |
|
207
|
*** IDs |
|
208
|
:PROPERTIES: |
|
209
|
:ID: 3944c851-e46c-4d75-b8f5-07b5c052177a |
|
210
|
:END: |
0
|
211
|
We reference two different types of identifiers in documentation: |
1
|
212
|
- UUID :: =ID= property |
|
213
|
- User-defined :: =CUSTOM_ID= property |
0
|
214
|
|
1
|
215
|
Most of the time these IDs don't add any information for the reader - |
0
|
216
|
the UUIDs are used to index and graph documents, CUSTOM_IDs are for |
|
217
|
convenience but are rarely necessary given the many ways of |
|
218
|
identifying a headline. |
1
|
219
|
** Tags |
0
|
220
|
:PROPERTIES: |
1
|
221
|
:ID: a7ae1b2a-559e-46e9-8cab-33e39a218288 |
0
|
222
|
:END: |
1
|
223
|
[[https://orgmode.org/manual/Tags.html][Tags]] are used liberally throughout our documents. They are simple |
|
224
|
strings usually following a headline as a =:=-separated list. |
0
|
225
|
|
1
|
226
|
A tag can be any text without newlines, although it is recommended to |
|
227
|
treat them as unique identifiers and usage of whitespace is |
|
228
|
discouraged (but not disallowed). |
|
229
|
*** Tag Types |
|
230
|
:PROPERTIES: |
|
231
|
:ID: b686dbc5-3505-49d7-b66a-0772bcf1a726 |
|
232
|
:END: |
|
233
|
Tags may be prefixed with one of the following characters, indicating |
|
234
|
a special tag type: |
|
235
|
- =@= :: location-tag \\ |
|
236
|
A /location tag/ refers to some context-dependent named point in |
|
237
|
space, such as a user's home address, a popular fast food |
|
238
|
restaurant, or a specific room found in most houses. |
|
239
|
- =@home=, =@taco-bell=, =@bedroom= |
|
240
|
- =!= :: timestamp-tag \\ |
|
241
|
/Timestamp tags/ refer to some point in time, often named for |
|
242
|
convenience. You may use literal [[https://orgmode.org/manual/Timestamps.html][Timestamps]] too. Timestamp tags |
|
243
|
should not /directly reference/ scheduling information, doing so is |
|
244
|
often a code-smell. |
|
245
|
- =!now=, =!christmas=, =!someday= |
|
246
|
- =#= :: anchor-tag \\ |
|
247
|
An /anchor tag/ implies a link to the object identified by some [[id:3944c851-e46c-4d75-b8f5-07b5c052177a][ID]]. |
|
248
|
- =#readme=, =#a7ae1b2a-559e-46e9-8cab-33e39a218288=, =#custom-id= |
|
249
|
*** Tag Lists |
|
250
|
:PROPERTIES: |
|
251
|
:ID: 805862be-ba2b-4288-a2e3-791c0aa3802f |
|
252
|
:END: |
|
253
|
** Links |
|
254
|
:PROPERTIES: |
|
255
|
:ID: 7ecaec5d-c656-44e1-8fad-185915655cee |
|
256
|
:END: |
|
257
|
*** Link Types |
|
258
|
:PROPERTIES: |
|
259
|
:ID: 6aedc026-36d0-4763-adc8-8ae1a79f1b3e |
|
260
|
:END: |