#+title: Universal Language

 #+author: Richard Westhaver

 #+email: ellis@rwest.io

 #+setupfile: ../clean.theme

 * Introduction

 :PROPERTIES:

 :ID:       e63d129f-9024-4cd8-9e2c-77f4bc614663

 :END:

 This document describes a *U-Language* as described by the late great

 [[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:

 #+begin_quote

 Every investigation, including the present one, has to be communicated

 from one person to another by means of language. It is expedient to

 begin our study by calling attention to this obvious fact, by giving a

 name to the language being used, and by being explicit about a few of

 its features. We shall call the language being used the

 U-Language. [...] There would be no point in calling attention to it,

 if it were not for the fact that language is more intimately related

 to our job than of most others.

 #+end_quote

 In this document, we will be calling attention to our own language -

 examining it, and describing how it works.

 Our job is to solve problems. Hard problems preferred. So we ought to

 pay close attention to the language we use because it brings the

 reader and writer /closer/ to the problem at hand.

 For starters, we are primarily concerned with /written languages/ like

 the one you're reading now. We will skip past the obvious details -

 English is our primary form of communication for example. The line you

 are reading currently is a sentence which is part of a paragraph.

 - This document is for authors and curious readers. It is a loose

   specification, but also serves as introductory material into our

   communication style and design philosophy.

 - All sources we write attempt to comply to this standard but it is

   not strictly enforced. If there is a reason to not comply with a

   rule, it is already broken.

 ** Org Mode

 :PROPERTIES:

 :ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1

 :END:

 [[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word

 processor.

 If you are already familiar with Emacs and Org-Mode, I recommend

 opening the source of this document in Emacs and following along.

 If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't

 be getting too deep into tribal hacker knowledge of Emacs.

 * ulang

 :PROPERTIES:

 :CUSTOM_ID: ulang

 :ID:       236227a5-b30c-4548-8cad-360428d74d67

 :END:

 Our *U-Language* is colloquially termed *ulang*. Each section of this

 document describes a feature of our ulang. 

 ** Emphasis

 :PROPERTIES:

 :ID:       88bf1177-b5b7-4945-8bdc-5229803e617e

 :END:

 We derive all text emphasis syntax for rich contents from [[https://orgmode.org/manual/Emphasis-and-Monospace.html][Org Mode]].

 #+name: org-emphasis

 #+begin_src org

   - *bold*

   - /italic/

   - _underlined_

   - =verbatim=

   - ~code~

   - +strike-through+

 #+end_src

 - *bold*

 - /italic/

 - _underlined_

 - =verbatim=

 - ~code~

 - +strike-through+

 Text emphasis markers may be embedded in any syntax as long as it does

 not cause any conflicts with the host language.

 ** Links

 :PROPERTIES:

 :ID:       7ecaec5d-c656-44e1-8fad-185915655cee

 :END:

 *** Link Types

 :PROPERTIES:

 :ID:       6aedc026-36d0-4763-adc8-8ae1a79f1b3e

 :END:

 ** Headings

 :PROPERTIES:

 :ID:       ed035298-f7fa-4726-ad58-2d542323bb61

 :END:

 In Org, headings can be summarize as any line starting with a star: =*

 H1=. Headings can be nested or 'demoted' by prepending another star:

 =** H2=.

 #+name: org-headings

 #+begin_src org

 ,* H1

 ,** H2

 ,*** H3

 ,** H2

 ,* H1

 #+end_src

 This is a useful pattern which we apply outside of Org - most commonly

 in our code comments.

 In our source code, we use the comment character instead of a star:

 #+name: lisp-headings

 #+begin_src lisp

 ;;; foo

 (print "H1") ;; just an inline comment

 ;;;; bar

 (print "H2")

 ;;; baz

 (print "H1")

 #+end_src

 #+name: rust-headings

 #+begin_src rust

   /// foo

   println!("H1");

   //// bar

   println!("H2");

   /// baz

   println!("H1");

 #+end_src

 ** Keywords

 :PROPERTIES:

 :ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba

 :END:

 TODO keywords are often used to keep track of the state of a [[https://orgmode.org/manual/TODO-Items.html][TODO

 Item]], but may also be [[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a variety of stateful item

 types beyond just simple tasks.

 The following keywords form the simple set of task states.

 - TBD

 - TODO

 - WIP

 - HOLD

 - WAIT

 - DONE

 - NOPE

 #+begin_src org

   ,* PROJECT project

   ,** DONE foo

   ,** TODO bar

   ,** TBD baz

   ,** WIP test foo

 #+end_src

 ** Tags

 :PROPERTIES:

 :ID:       a7ae1b2a-559e-46e9-8cab-33e39a218288

 :END:

 [[https://orgmode.org/manual/Tags.html][Tags]] are used liberally throughout our documents. They are simple

 strings usually following a headline as a =:=-separated list.

 A tag can be any text without newlines, although it is recommended to

 treat them as unique identifiers and usage of whitespace is

 discouraged (but not disallowed).

 #+begin_src org

   ,* foobar                                               :tag1:tag2:@home:!today

 #+end_src

 *** Tag Prefixes

 :PROPERTIES:

 :ID:       b686dbc5-3505-49d7-b66a-0772bcf1a726

 :END:

 Some of ourtags are prefixed with a character which indicates a

 special tag category:

 - =@= :: location-tag \\

   A /location tag/ refers to some context-dependent named point in

   space, such as a user's home address, a popular fast food

   restaurant, or a specific room found in most houses.

   - =@home=, =@taco-bell=, =@bedroom=

 - =!= :: timestamp-tag \\

   /Timestamp tags/ refer to some point in time, often named for

   convenience. You may use literal [[https://orgmode.org/manual/Timestamps.html][Timestamps]] too. Timestamp tags

   should not /directly reference/ scheduling information, doing so is

   often a code-smell.

   - =!now=, =!christmas=, =!someday=

 - =#= :: anchor-tag \\

   An /anchor tag/ implies a link to the object identified by some [[id:3944c851-e46c-4d75-b8f5-07b5c052177a][ID]].

   - =#readme=, =#a7ae1b2a-559e-46e9-8cab-33e39a218288=, =#custom-id=

 ** Properties

 :PROPERTIES:

 :ID:       174a993b-a5dc-4324-b4f8-dda8101a55b7

 :END:

 [[https://orgmode.org/manual/Properties-and-Columns.html][Properties]] are key:value pairs which are associated with a heading or

 file and stored in a dedicated [[https://orgmode.org/manual/Drawers.html][Drawer]].

 #+begin_src org

   ,* WIP do stuff                                                         :@lab:

   :PROPERTIES:

   :CREATED:  <2024-08-24 Sat 19:09>

   :ID:       62da3982-7a83-4b27-ab7e-55949fd3e2a3

   :EFFORT: 24:00

   :END:

 #+end_src

 *** ID

 :PROPERTIES:

 :ID:       3944c851-e46c-4d75-b8f5-07b5c052177a

 :END:

 We reference two different types of identifiers in documentation:

 - UUID :: =ID= property

 - User-defined :: =CUSTOM_ID= property

 Most of the time these IDs don't add any information for the reader -

 the UUIDs are used to index and graph documents, CUSTOM_IDs are for

 convenience and extensions, but are rarely necessary given the many

 ways of identifying a headline.

 All headings are assigned an ID automatically and are never changed.