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. 56 As the title suggest we refer to our
*Universal Language* as
57 ulang. When I say something along the lines of "Please refer to
58 [[Links][ulang:links]]", I am referencing the section named
/Links/ of this
61 This is a "living" document. In other words, it is incomplete. I may
62 include additional elements in the ulang, or modify the specification
65 Each section of this document describes an element of the ulang. It is
66 recommended to skim through the top-level sections (
[[Org-mode][Org-mode]] and
67 [[Elements][Elements]]) and review the element sub-headings as needed.
72 [[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally
[[https://orgmode.org/][Org Mode]] is our
75 If you are already familiar with Emacs and org-mode, I recommend
76 opening the source file of this document in Emacs and following along.
78 If not, I recommend browsing through the
[[https://orgmode.org/worg/][Worg resources]], but we're not
79 getting too deep into tribal hacker knowledge of Emacs. The choice of
80 Org is arbitrary and the concepts here would apply to other formats
81 (LaTeX, Markdown, etc).
83 Let us first consider
/Org the syntax/.
85 Org syntax is much less popular than Markdown and lacks parsing
86 utilities in popular programming languages
[fn:1]. Perhaps Org is not
87 suited as a
/universal/ text format because it's arguably harder to
88 parse, making it less interoperable and intimidating to adopt.
90 Regardless, we are committed to it as a foundation because it is the
91 most hackable documentation engine available. With enough experience
92 you can morph Org into whatever system you want, and that is
/exactly/ 95 [fn:1] The ecosystem is changing though, thanks to the dedication of
96 some excellent hackers:
[[https://github.com/karlicoss/orgparse][python]],
[[https://github.com/tecosaur/Org.jl][julia]] 99 - State "TODO" from [2023-11-05 Sun 19:21]
100 Org is the designated text representation of our ulang. Org-mode
101 depends on Emacs (it's written in Emacs Lisp) but that doesn't mean we
102 have to. To solve the issue of interoperability between different
103 systems, we are developing a modular tool called
[[https://lab.rwest.io/comp/core/-/tree/branch/default/lisp/lib/organ][organ]]. The purpose of
104 =organ= is to provide an external API for Org documents that doesn't
107 If we were designing a
/personal/ note-taking system, I would argue
108 that we don't need this tool. The problem is it's not personal - we
109 have a much wider intended audience - it's business. This means
110 thinking about hundreds to thousands of documents instead of tens,
111 about processing those documents into a full-text search database, and
112 reducing cost along the way.
114 Emacs can do all of these things, but do you really want it to? I
115 don't. Emacs should remain close to the developer and we can outsource
116 the tricky bits to
=organ=.
120 The ulang
*Keywords* are a superset of those defined by
[[https://datatracker.ietf.org/doc/html/rfc2119][RFC-2119]]. The
121 definition of a keyword from the original spec is ultimately
125 In many standards track documents several words are used to signify
126 the requirements in the specification. These words are often
127 capitalized. This document defines these words as they should be
128 interpreted in IETF documents. Authors who follow these guidelines
129 should incorporate this phrase near the beginning of their document:
131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
132 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
133 "OPTIONAL" in this document are to be interpreted as described in
137 We can't be bothered to include these with every document, so here
138 they are - don't forget!
141 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the
142 definition is an absolute requirement of the specification.
144 2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the
145 definition is an absolute prohibition of the specification.
147 3. SHOULD This word, or the adjective "RECOMMENDED", mean that there
148 may exist valid reasons in particular circumstances to ignore a
149 particular item, but the full implications must be understood and
150 carefully weighed before choosing a different course.
152 4. SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that
153 there may exist valid reasons in particular circumstances when the
154 particular behavior is acceptable or even useful, but the full
155 implications should be understood and the case carefully weighed
156 before implementing any behavior described with this label.
158 5. MAY This word, or the adjective "OPTIONAL", mean that an item is
159 truly optional. One vendor may choose to include the item because a
160 particular marketplace requires it or because the vendor feels that
161 it enhances the product while another vendor may omit the same item.
162 An implementation which does not include a particular option MUST be
163 prepared to interoperate with another implementation which does
164 include the option, though perhaps with reduced functionality. In the
165 same vein an implementation which does include a particular option
166 MUST be prepared to interoperate with another implementation which
167 does not include the option (except, of course, for the feature the
171 One of the important features of keywords is that we use them as Org
172 [[https://orgmode.org/manual/Workflow-states.html][Workflow states]]. You may use any of the keywords above or below as the
173 first word in a heading to signify a requirement or a workflow state:
175 6. TBD A task to be done at a later date.
177 7. TODO A task yet to be done.
179 8. WIP Work In Progress task.
181 9. NOTE Designates a note item.
183 10. DRAFT Designates a draft item.
185 11. NOPE Item that will not be completed.
187 12. DONE Completed task.
190 Abbrevs include domain-specific acronyms and slang such as
/DB/ for
191 database or
/M$/ for Microsoft. They're abbreviations, but even lazier
192 (we can't even be bothered to spell out the name). By defining them in
193 one place we can use Emacs to lookup abbrevs on the fly, and we can
194 automatically generate help text and references to abbrev definitions
