1.1--- a/ulang.org	Wed Nov 01 21:32:38 2023 -0400
     1.2+++ b/ulang.org	Sun Nov 05 21:44:43 2023 -0500
     1.3@@ -1,6 +1,6 @@
     1.4 #+TITLE: ulang
     1.5-
     1.6-This document defines a *U-Language* as described by the late great
     1.7+#+OPTIONS: toc:nil
     1.8+This document describes a *U-Language* as described by the late great
     1.9 Haskell Curry:
    1.10 
    1.11 #+begin_quote
    1.12@@ -20,34 +20,180 @@
    1.13 out there which would benefit greatly from such an investigation.
    1.14 
    1.15 I would also like to humbly clarify on our interpretation of a *job*
    1.16-as Curry puts it. We all have the same job really - to be curious, and
    1.17-to solve problems. It is the *problems* I would like to shine a light
    1.18-on, if just for a moment, because it's important. Just as Curry thinks
    1.19-of languages, we can think of problems. There exists the *problem of
    1.20-problems* which is the subject of our investigations. This *U-Problem*
    1.21-is what we are solving for at all times. In this light, we can view
    1.22-the *U-Language* as a means of bringing both the /reader/ and /writer/
    1.23-as close as possible to the *U-Problem*.
    1.24+as Curry puts it. 
    1.25+
    1.26+We all have the same job really - to be curious, and to solve
    1.27+problems. It is the *problems* I would like to shine a light on, if
    1.28+just for a moment, because it's important. 
    1.29+
    1.30+Just as Curry thinks of languages, we can think of problems. There
    1.31+exists the *problem of problems* which is the subject of our
    1.32+investigations. This *U-Problem* is what we are solving for at all
    1.33+times. In this light, we can view the *U-Language* as a means of
    1.34+bringing both the /reader/ and /writer/ as close as possible to the
    1.35+*U-Problem*.
    1.36 
    1.37 For convenience, our *U-Problem* is undecidable, but we model and
    1.38-solve for it using /computers/, or more abstractly machines. Thus, our
    1.39-*U-Language* helps bring the /reader/ and /writer/ closer to
    1.40-our /machines/ as well as expedite communications.
    1.41+solve for it using ~computers~, or more abstractly ~machines~. Thus,
    1.42+our *U-Language* helps bring the /reader/ and /writer/ closer to our
    1.43+~machines~ as well as expedite communications between reader and
    1.44+writer.
    1.45+
    1.46+:summary:
    1.47+- /Why do we need a U-Language?/ :: To bring both the /reader/ and
    1.48+  /writer/ closer to our *U-Problem*.
    1.49+
    1.50+- /What is our U-Problem?/ :: Undecidable, but we use /computers/ as a
    1.51+  model of the *U-Problem*. When we are dealing with the *U-Problem*
    1.52+  we are speaking in terms of /computation/ and the ability of a given
    1.53+  machine to /compute/.
    1.54+
    1.55+- /How do we solve our U-Problem?/ :: With /computers/, by developing
    1.56+  accurate models and finding optimal solutions.
    1.57+:end:
    1.58+
    1.59+* ulang
    1.60+As the title suggest we refer to our *Universal Language* as
    1.61+ulang. When I say something along the lines of "Please refer to
    1.62+[[Links][ulang:links]]", I am referencing the section named /Links/ of this
    1.63+document.
    1.64+
    1.65+This is a "living" document. In other words, it is incomplete. I may
    1.66+include additional elements in the ulang, or modify the specification
    1.67+of existing ones.
    1.68+
    1.69+Each section of this document describes an element of the ulang. It is
    1.70+recommended to skim through the top-level sections ([[Org-mode][Org-mode]] and
    1.71+[[Elements][Elements]]) and review the element sub-headings as needed.
    1.72+
    1.73+#+TOC: headlines 3
    1.74+
    1.75+** Org-mode
    1.76+[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our
    1.77+documentation engine. 
    1.78+
    1.79+If you are already familiar with Emacs and org-mode, I recommend
    1.80+opening the source file of this document in Emacs and following along.
    1.81+
    1.82+If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we're not
    1.83+getting too deep into tribal hacker knowledge of Emacs. The choice of
    1.84+Org is arbitrary and the concepts here would apply to other formats
    1.85+(LaTeX, Markdown, etc).
    1.86+
    1.87+Let us first consider /Org the syntax/.
    1.88+
    1.89+Org syntax is much less popular than Markdown and lacks parsing
    1.90+utilities in popular programming languages[fn:1]. Perhaps Org is not
    1.91+suited as a /universal/ text format because it's arguably harder to
    1.92+parse, making it less interoperable and intimidating to adopt.
    1.93+
    1.94+Regardless, we are committed to it as a foundation because it is the
    1.95+most hackable documentation engine available. With enough experience
    1.96+you can morph Org into whatever system you want, and that is /exactly/
    1.97+our intention.
    1.98+
    1.99+[fn:1] The ecosystem is changing though, thanks to the dedication of
   1.100+some excellent hackers: [[https://github.com/karlicoss/orgparse][python]], [[https://github.com/tecosaur/Org.jl][julia]]
   1.101+
   1.102+*** TODO organ
   1.103+- State "TODO"       from              [2023-11-05 Sun 19:21]
   1.104+Org is the designated text representation of our ulang. Org-mode
   1.105+depends on Emacs (it's written in Emacs Lisp) but that doesn't mean we
   1.106+have to. To solve the issue of interoperability between different
   1.107+systems, we are developing a modular tool called [[https://lab.rwest.io/comp/core/-/tree/branch/default/lisp/lib/organ][organ]]. The purpose of
   1.108+=organ= is to provide an external API for Org documents that doesn't
   1.109+depend on GNU Emacs.
   1.110+
   1.111+If we were designing a /personal/ note-taking system, I would argue
   1.112+that we don't need this tool. The problem is it's not personal - we
   1.113+have a much wider intended audience - it's business. This means
   1.114+thinking about hundreds to thousands of documents instead of tens,
   1.115+about processing those documents into a full-text search database, and
   1.116+reducing cost along the way.
   1.117+
   1.118+Emacs can do all of these things, but do you really want it to? I
   1.119+don't. Emacs should remain close to the developer and we can outsource
   1.120+the tricky bits to =organ=.
   1.121 
   1.122-- /Why do we need a U-Language?/ ::
   1.123-  To bring both the /reader/ and /writer/ closer to our *U-Problem*.
   1.124-- /What is our U-Problem?/ :: 
   1.125-  Undecidable, but we use /computers/ as a model of the
   1.126-  *U-Problem*.
   1.127-- /How do we solve our U-Problem?/ ::
   1.128-  With /computers/, by developing accurate models and finding optimal
   1.129-  solutions.
   1.130+** Elements
   1.131+*** Keywords
   1.132+The ulang *Keywords* are a superset of those defined by [[https://datatracker.ietf.org/doc/html/rfc2119][RFC-2119]]. The
   1.133+definition of a keyword from the original spec is ultimately
   1.134+unchanged:
   1.135+
   1.136+#+begin_quote
   1.137+In many standards track documents several words are used to signify
   1.138+the requirements in the specification.  These words are often
   1.139+capitalized.  This document defines these words as they should be
   1.140+interpreted in IETF documents.  Authors who follow these guidelines
   1.141+should incorporate this phrase near the beginning of their document:
   1.142+
   1.143+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
   1.144+NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
   1.145+"OPTIONAL" in this document are to be interpreted as described in
   1.146+RFC 2119.
   1.147+#+end_quote
   1.148+
   1.149+We can't be bothered to include these with every document, so here
   1.150+they are - don't forget!
   1.151+
   1.152+#+begin_quote
   1.153+1. MUST   This word, or the terms "REQUIRED" or "SHALL", mean that the
   1.154+   definition is an absolute requirement of the specification.
   1.155+
   1.156+2. MUST NOT   This phrase, or the phrase "SHALL NOT", mean that the
   1.157+   definition is an absolute prohibition of the specification.
   1.158+
   1.159+3. SHOULD   This word, or the adjective "RECOMMENDED", mean that there
   1.160+   may exist valid reasons in particular circumstances to ignore a
   1.161+   particular item, but the full implications must be understood and
   1.162+   carefully weighed before choosing a different course.
   1.163+
   1.164+4. SHOULD NOT   This phrase, or the phrase "NOT RECOMMENDED" mean that
   1.165+   there may exist valid reasons in particular circumstances when the
   1.166+   particular behavior is acceptable or even useful, but the full
   1.167+   implications should be understood and the case carefully weighed
   1.168+   before implementing any behavior described with this label.
   1.169 
   1.170-* Key Words
   1.171-* Abbrevs
   1.172-* Conditionals
   1.173-* Operators
   1.174-* Expressions
   1.175-* Links
   1.176-* Timestamps
   1.177-* Macros
   1.178+5. MAY   This word, or the adjective "OPTIONAL", mean that an item is
   1.179+   truly optional.  One vendor may choose to include the item because a
   1.180+   particular marketplace requires it or because the vendor feels that
   1.181+   it enhances the product while another vendor may omit the same item.
   1.182+   An implementation which does not include a particular option MUST be
   1.183+   prepared to interoperate with another implementation which does
   1.184+   include the option, though perhaps with reduced functionality. In the
   1.185+   same vein an implementation which does include a particular option
   1.186+   MUST be prepared to interoperate with another implementation which
   1.187+   does not include the option (except, of course, for the feature the
   1.188+   option provides.)
   1.189+#+end_quote
   1.190+
   1.191+One of the important features of keywords is that we use them as Org
   1.192+[[https://orgmode.org/manual/Workflow-states.html][Workflow states]]. You may use any of the keywords above or below as the
   1.193+first word in a heading to signify a requirement or a workflow state:
   1.194+
   1.195+6. TBD   A task to be done at a later date.
   1.196+
   1.197+7. TODO   A task yet to be done.
   1.198+
   1.199+8. WIP   Work In Progress task.
   1.200+
   1.201+9. NOTE   Designates a note item.
   1.202+
   1.203+10. DRAFT   Designates a draft item.
   1.204+
   1.205+11. NOPE   Item that will not be completed.
   1.206+
   1.207+12. DONE   Completed task.
   1.208+
   1.209+*** Abbrevs
   1.210+Abbrevs include domain-specific acronyms and slang such as /DB/ for
   1.211+database or /M$/ for Microsoft. They're abbreviations, but even lazier
   1.212+(we can't even be bothered to spell out the name). By defining them in
   1.213+one place we can use Emacs to lookup abbrevs on the fly, and we can
   1.214+automatically generate help text and references to abbrev definitions
   1.215+for our readers.
   1.216+*** Operators
   1.217+*** Links
   1.218+*** Timestamps
   1.219+*** Macros