1 #+title: Universal Language
2 #+author: Richard Westhaver
3 #+email: ellis@rwest.io
4 #+setupfile: ../clean.theme
5 #+infojs_opt: toc:nil home:https://compiler.company up:./ view:showall
8 :ID: e63d129f-9024-4cd8-9e2c-77f4bc614663 10 This document describes a
*U-Language* as described by the late great
11 [[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:
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.
23 In this document, we will be calling attention to our own language -
24 examining it, and describing how it works.
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.
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.
35 - This document is for authors and curious readers. It is a loose
36 specification, but also serves as introductory material into our
37 communication style and design philosophy.
38 - All sources we write attempt to comply to this standard but it is
39 not strictly enforced. If there is a reason to not comply with a
40 rule, it is already broken.
44 :ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1 46 [[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally
[[https://orgmode.org/][Org Mode]] is our word
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.
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.
58 :ID: 236227a5-b30c-4548-8cad-360428d74d67 60 Our
*U-Language* is colloquially termed
*ulang*. Each section of this
61 document describes a feature of our ulang.
64 :ID: 88bf1177-b5b7-4945-8bdc-5229803e617e 66 We derive all text emphasis syntax for rich contents from
[[https://orgmode.org/manual/Emphasis-and-Monospace.html][Org Mode]].
83 Text emphasis markers may be embedded in any syntax as long as it does
84 not cause any conflicts with the host language.
87 :ID: 7ecaec5d-c656-44e1-8fad-185915655cee 91 :ID: 6aedc026-36d0-4763-adc8-8ae1a79f1b3e 96 :ID: ed035298-f7fa-4726-ad58-2d542323bb61 98 In Org, headings can be summarize as any line starting with a star:
=* 99 H1=. Headings can be nested or 'demoted' by prepending another star:
111 This is a useful pattern which we apply outside of Org - most commonly
112 in our code comments.
114 In our source code, we use the comment character instead of a star:
115 #+name: lisp-headings
118 (print "H1") ;; just an inline comment
125 #+name: rust-headings
137 :ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba 140 TODO keywords are often used to keep track of the state of a
[[https://orgmode.org/manual/TODO-Items.html][TODO 141 Item]], but may also be
[[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a variety of stateful item
142 types beyond just simple tasks.
144 The following keywords form the simple set of task states.
164 :ID: a7ae1b2a-559e-46e9-8cab-33e39a218288 166 [[https://orgmode.org/manual/Tags.html][Tags]] are used liberally throughout our documents. They are simple
167 strings usually following a headline as a
=:=-separated list.
169 A tag can be any text without newlines, although it is recommended to
170 treat them as unique identifiers and usage of whitespace is
171 discouraged (but not disallowed).
174 ,* foobar :tag1:tag2:@home:!today
178 :ID: b686dbc5-3505-49d7-b66a-0772bcf1a726 180 Some of ourtags are prefixed with a character which indicates a
181 special tag category:
182 - =@= :: location-tag
\\ 183 A
/location tag/ refers to some context-dependent named point in
184 space, such as a user's home address, a popular fast food
185 restaurant, or a specific room found in most houses.
186 - =@home=,
=@taco-bell=,
=@bedroom= 187 - =!= :: timestamp-tag
\\ 188 /Timestamp tags/ refer to some point in time, often named for
189 convenience. You may use literal
[[https://orgmode.org/manual/Timestamps.html][Timestamps]] too. Timestamp tags
190 should not
/directly reference/ scheduling information, doing so is
192 - =!now=,
=!christmas=,
=!someday= 193 - =#= :: anchor-tag
\\ 194 An
/anchor tag/ implies a link to the object identified by some
[[id:3944c851-e46c-4d75-b8f5-07b5c052177a][ID]].
195 - =#readme=,
=#a7ae1b2a-559e-46e9-8cab-33e39a218288=,
=#custom-id= 198 :ID: 174a993b-a5dc-4324-b4f8-dda8101a55b7 200 [[https://orgmode.org/manual/Properties-and-Columns.html][Properties]] are key:value pairs which are associated with a heading or
201 file and stored in a dedicated
[[https://orgmode.org/manual/Drawers.html][Drawer]].
204 ,* WIP do stuff :@lab:
206 :CREATED: <2024-08-24 Sat 19:09>
207 :ID: 62da3982-7a83-4b27-ab7e-55949fd3e2a3
213 :ID: 3944c851-e46c-4d75-b8f5-07b5c052177a 215 We reference two different types of identifiers in documentation:
216 - UUID :: =ID= property
217 - User-defined :: =CUSTOM_ID= property
219 Most of the time these IDs don't add any information for the reader -
220 the UUIDs are used to index and graph documents, CUSTOM_IDs are for
221 convenience and extensions, but are rarely necessary given the many
222 ways of identifying a headline.
224 All headings are assigned an ID automatically and are never changed.