3 This document describes a
*U-Language* as described by the late great
7 Every investigation, including the present one, has to be communicated
8 from one person to another by means of language. It is expedient to
9 begin our study by calling attention to this obvious fact, by giving a
10 name to the language being used, and by being explicit about a few of
11 its features. We shall call the language being used the
12 U-Language. [...] There would be no point in calling attention to it,
13 if it were not for the fact that language is more intimately related
14 to our job than of most others.
17 There is a natural reader/writer relationship that exists in countless
18 places, but is rarely examined because it is rarely necessary. However
19 there is a wide array of significantly complex code and prose projects
20 out there which would benefit greatly from such an investigation.
22 I would also like to humbly clarify on our interpretation of a
*job* 25 We all have the same job really - to be curious, and to solve
26 problems. It is the
*problems* I would like to shine a light on, if
27 just for a moment, because it's important.
29 Just as Curry thinks of languages, we can think of problems. There
30 exists the
*problem of problems* which is the subject of our
31 investigations. This
*U-Problem* is what we are solving for at all
32 times. In this light, we can view the
*U-Language* as a means of
33 bringing both the
/reader/ and
/writer/ as close as possible to the
36 For convenience, our
*U-Problem* is undecidable, but we model and
37 solve for it using
~computers~, or more abstractly
~machines~. Thus,
38 our
*U-Language* helps bring the
/reader/ and
/writer/ closer to our
39 ~machines~ as well as expedite communications between reader and
43 - /Why do we need a U-Language?/ :: To bring both the /reader/ and 44 /writer/ closer to our *U-Problem*. 46 - /What is our U-Problem?/ :: Undecidable, but we use /computers/ as a 47 model of the *U-Problem*. When we are dealing with the *U-Problem* 48 we are speaking in terms of /computation/ and the ability of a given 51 - /How do we solve our U-Problem?/ :: With /computers/, by developing 52 accurate models and finding optimal solutions. 57 :CUSTOM_ID: 8447a560-7f77-45c7-bd14-2a2af6ad2abc 59 As the title suggest we refer to our
*Universal Language* as
60 ulang. When I say something along the lines of "Please refer to
61 [[Links][ulang:links]]", I am referencing the section named
/Links/ of this
64 This is a "living" document. In other words, it is incomplete. I may
65 include additional elements in the ulang, or modify the specification
68 Each section of this document describes an element of the ulang. It is
69 recommended to skim through the top-level sections (
[[Org-mode][Org-mode]] and
70 [[Elements][Elements]]) and review the element sub-headings as needed.
76 :CUSTOM_ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1 78 [[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally
[[https://orgmode.org/][Org Mode]] is our
81 If you are already familiar with Emacs and org-mode, I recommend
82 opening the source file of this document in Emacs and following along.
84 If not, I recommend browsing through the
[[https://orgmode.org/worg/][Worg resources]], but we're not
85 getting too deep into tribal hacker knowledge of Emacs. The choice of
86 Org is arbitrary and the concepts here would apply to other formats
87 (LaTeX, Markdown, etc).
89 Let us first consider
/Org the syntax/.
91 Org syntax is much less popular than Markdown and lacks parsing
92 utilities in popular programming languages
[fn:1]. Perhaps Org is not
93 suited as a
/universal/ text format because it's arguably harder to
94 parse, making it less interoperable and intimidating to adopt.
96 Regardless, we are committed to it as a foundation because it is the
97 most hackable documentation engine available. With enough experience
98 you can morph Org into whatever system you want, and that is
/exactly/ 101 [fn:1] The ecosystem is changing though, thanks to the dedication of
102 some excellent hackers:
[[https://github.com/karlicoss/orgparse][python]],
[[https://github.com/tecosaur/Org.jl][julia]] 106 :CUSTOM_ID: 22474039-5c18-4179-82aa-a6731e6313a2 108 - State "TODO" from [2023-11-05 Sun 19:21]
109 Org is the designated text representation of our ulang. Org-mode
110 depends on Emacs (it's written in Emacs Lisp) but that doesn't mean we
111 have to. To solve the issue of interoperability between different
112 systems, we are developing a modular tool called
[[https://lab.rwest.io/comp/core/-/tree/branch/default/lisp/lib/organ][organ]]. The purpose of
113 =organ= is to provide an external API for Org documents that doesn't
116 If we were designing a
/personal/ note-taking system, I would argue
117 that we don't need this tool. The problem is it's not personal - we
118 have a much wider intended audience - it's business. This means
119 thinking about hundreds to thousands of documents instead of tens,
120 about processing those documents into a full-text search database, and
121 reducing cost along the way.
123 Emacs can do all of these things, but do you really want it to? I
124 don't. Emacs should remain close to the developer and we can outsource
125 the tricky bits to
=organ=.
129 :CUSTOM_ID: 4aa3ec2a-b360-43ae-b2d8-f9735f211290 133 :CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba 135 The ulang
*Keywords* are a superset of those defined by
[[https://datatracker.ietf.org/doc/html/rfc2119][RFC-2119]]. The
136 definition of a keyword from the original spec is ultimately
140 In many standards track documents several words are used to signify
141 the requirements in the specification. These words are often
142 capitalized. This document defines these words as they should be
143 interpreted in IETF documents. Authors who follow these guidelines
144 should incorporate this phrase near the beginning of their document:
146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
147 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
148 "OPTIONAL" in this document are to be interpreted as described in
152 We can't be bothered to include these with every document, so here
153 they are - don't forget!
156 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the
157 definition is an absolute requirement of the specification.
159 2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the
160 definition is an absolute prohibition of the specification.
162 3. SHOULD This word, or the adjective "RECOMMENDED", mean that there
163 may exist valid reasons in particular circumstances to ignore a
164 particular item, but the full implications must be understood and
165 carefully weighed before choosing a different course.
167 4. SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that
168 there may exist valid reasons in particular circumstances when the
169 particular behavior is acceptable or even useful, but the full
170 implications should be understood and the case carefully weighed
171 before implementing any behavior described with this label.
173 5. MAY This word, or the adjective "OPTIONAL", mean that an item is
174 truly optional. One vendor may choose to include the item because a
175 particular marketplace requires it or because the vendor feels that
176 it enhances the product while another vendor may omit the same item.
177 An implementation which does not include a particular option MUST be
178 prepared to interoperate with another implementation which does
179 include the option, though perhaps with reduced functionality. In the
180 same vein an implementation which does include a particular option
181 MUST be prepared to interoperate with another implementation which
182 does not include the option (except, of course, for the feature the
186 One of the important features of keywords is that we use them as Org
187 [[https://orgmode.org/manual/Workflow-states.html][Workflow states]]. You may use any of the keywords above or below as the
188 first word in a heading to signify a requirement or a workflow state:
190 6. TBD A task to be done at a later date.
192 7. TODO A task yet to be done.
194 8. WIP Work In Progress task.
196 9. NOTE Designates a note item.
198 10. DRAFT Designates a draft item.
200 11. NOPE Item that will not be completed.
202 12. DONE Completed task.
206 :CUSTOM_ID: b4c326ba-f74c-4409-9314-8d32df61fc5e 208 Abbrevs include domain-specific acronyms and slang such as
/DB/ for
209 database or
/M$/ for Microsoft. They're abbreviations, but even lazier
210 (we can't even be bothered to spell out the name). By defining them in
211 one place we can use Emacs to lookup abbrevs on the fly, and we can
212 automatically generate help text and references to abbrev definitions
216 :CUSTOM_ID: f91ca826-2c72-4d00-810c-2d61aa073658 220 :CUSTOM_ID: 7bd8eeaa-9f21-4ab4-ba6e-be118e68d36a 224 :CUSTOM_ID: 4faf913e-7c15-4937-9547-b50a6c8ba896 228 :CUSTOM_ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e
