1.1--- a/style.org	Tue Nov 28 21:45:46 2023 -0500
     1.2+++ b/style.org	Thu Nov 30 20:55:41 2023 -0500
     1.3@@ -29,19 +29,15 @@
     1.4 
     1.5 * Common Lisp
     1.6 
     1.7-- prefer symbol docs to comment docs
     1.8+- prefer symbol docs to comments
     1.9+- use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]]
    1.10+- prefer =core= libraries over vendored
    1.11 
    1.12 ** File templates
    1.13 * Rust
    1.14-
    1.15 - don't make =mod.rs= files
    1.16   - use the =foo.rs=, =foo/*= pattern instead
    1.17-** File templates
    1.18 * Emacs Lisp
    1.19-** File templates
    1.20 * Org-mode
    1.21-** File templates
    1.22 * Shell
    1.23-** File templates
    1.24 * Python
    1.25-** File templates

     2.1--- a/ulang.org	Tue Nov 28 21:45:46 2023 -0500
     2.2+++ b/ulang.org	Thu Nov 30 20:55:41 2023 -0500
     2.3@@ -2,9 +2,10 @@
     2.4 Richard Westhaver,
     2.5 ellis@rwest.io,
     2.6 The Universal Language)}}}
     2.7+#+OPTIONS: toc:t
     2.8 
     2.9 This document describes a *U-Language* as described by the late great
    2.10-Haskell Curry:
    2.11+[[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:
    2.12 
    2.13 #+begin_quote
    2.14 Every investigation, including the present one, has to be communicated
    2.15@@ -17,156 +18,131 @@
    2.16 to our job than of most others.
    2.17 #+end_quote
    2.18 
    2.19-* ulang
    2.20-:PROPERTIES:
    2.21-:CUSTOM_ID: ulang
    2.22-:END:
    2.23-As the title suggest we refer to our *U-Language* as
    2.24-ulang. When I say something along the lines of "Please refer to
    2.25-[[*Hyperlinks][ulang.Hyperlinks]]", I am referencing the section named /Links/ of this
    2.26-document.
    2.27+In this document, we will be calling attention to our own language -
    2.28+examining it, and describing how it works.
    2.29+
    2.30+Our job is to solve problems. Hard problems preferred. So we ought to
    2.31+pay close attention to the language we use because it brings the
    2.32+reader and writer /closer/ to the problem at hand.
    2.33+
    2.34+For starters, we are primarily concerned with /written languages/ like
    2.35+the one you're reading now. We will skip past the obvious details -
    2.36+English is our primary form of communication for example. The line you
    2.37+are reading currently is a sentence which is part of a paragraph.
    2.38+
    2.39+There are some non-obvious questions which deserve inquiry though.
    2.40 
    2.41-Each section of this document describes an element of the ulang. It is
    2.42-recommended to skim through the top-level sections ([[Org-mode][Org-mode]] and
    2.43-[[Elements][Elements]]) and review the element sub-headings as needed.
    2.44+- *Who is this for?* \\
    2.45+  This document is for authors and readers alike. It is a loose
    2.46+  specification, but also serves as introductory material into our
    2.47+  communication and design philosophy.
    2.48+  
    2.49+- *What is this for?* \\
    2.50+  The purpose of this document is to provide a /standard of
    2.51+  communication/.
    2.52 
    2.53-#+TOC: headlines 3
    2.54+  All sources we write attempt to conform to this standard but this is
    2.55+  not strictly enforced. If there is a reason to not comply with a
    2.56+  rule, it is already broken.
    2.57 
    2.58-** Org-mode
    2.59+* Org Mode
    2.60 :PROPERTIES:
    2.61 :CUSTOM_ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1
    2.62 :END:
    2.63-[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our
    2.64-documentation engine. 
    2.65+[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word
    2.66+processor.
    2.67 
    2.68-If you are already familiar with Emacs and org-mode, I recommend
    2.69-opening the source file of this document in Emacs and following along.
    2.70+If you are already familiar with Emacs and Org-Mode, I recommend
    2.71+opening the source of this document in Emacs and following along.
    2.72 
    2.73 If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't
    2.74-be getting too deep into tribal hacker knowledge of Emacs. The choice
    2.75-of Org is arbitrary and the concepts here would apply to other formats
    2.76-(LaTeX, Markdown, etc).
    2.77+be getting too deep into tribal hacker knowledge of Emacs.
    2.78 
    2.79-*** TODO organ
    2.80-:PROPERTIES:
    2.81-:CUSTOM_ID: 22474039-5c18-4179-82aa-a6731e6313a2
    2.82-:END:
    2.83-- State "TODO"       from              [2023-11-05 Sun 19:21]
    2.84+What's important to know is this: There is /Org Syntax/ and
    2.85+/Org-mode/ - these are different things.
    2.86+
    2.87+Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are
    2.88+not concerned about /Org-mode/ the application in this document.
    2.89 
    2.90-=Org-mode= the application depends on Emacs (it's written in Emacs
    2.91-Lisp) but that doesn't mean we need to. To solve the issue of
    2.92-interoperability between different systems, we are developing a tool
    2.93-called [[https://lab.rwest.io/comp/core/-/tree/branch/default/lisp/lib/organ][organ]]. The purpose of =organ= is to provide an external API for
    2.94-Org documents that doesn't depend on GNU Emacs.
    2.95-
    2.96-If we were designing a /personal/ note-taking system, I would argue
    2.97-that we don't need this tool. The problem is it's /not/ personal - we
    2.98-have a much wider intended audience and need to present information in
    2.99-many different ways. This means thinking about hundreds to thousands
   2.100-of documents instead of tens, about processing those documents into a
   2.101-full-text search database, and reducing cost along the way.
   2.102-
   2.103-Emacs can do all of these things, but do you really want it to?
   2.104+* ulang
   2.105+:PROPERTIES:
   2.106+:ID: ulang
   2.107+:END:
   2.108+As the title suggest we refer to our *U-Language* as *ulang*. Each
   2.109+section of this document describes a feature.
   2.110+** Outlines
   2.111+In Org, headings can be summarize as any line starting with a star: =*
   2.112+H1=. Headings can be nested or 'demoted' by prepending another star:
   2.113+=** H2=.
   2.114 
   2.115-** Syntax
   2.116-Let us first consider /Org the syntax/.
   2.117-
   2.118-Org syntax is much less popular than Markdown and lacks parsing
   2.119-utilities in popular programming languages[fn:1]. Regardless, we are
   2.120-committed to it as a foundation because it is the most hackable
   2.121-documentation engine available. With enough experience you can morph
   2.122-Org into whatever documentation system that is needed.
   2.123-
   2.124-
   2.125-As such, all documentation we write is done using =Org syntax=. When
   2.126-we refer to Org syntax we are referring to the vanilla syntax which
   2.127-comes built-in with Emacs.
   2.128+This is a useful pattern which we apply outside of Org - most commonly
   2.129+in our code comments.
   2.130 
   2.131-=Ulang syntax= is an extension of =Org syntax=. If some feature of the
   2.132-=Ulang= is undocumented, refer to =Org syntax= for guidance.
   2.133-
   2.134-[fn:1] The ecosystem is changing though, thanks to the dedication of
   2.135-some excellent hackers: [[https://github.com/karlicoss/orgparse][python]], [[https://github.com/tecosaur/Org.jl][julia]]
   2.136+In our source code, we use the comment character instead of a star:
   2.137+#+begin_src lisp
   2.138+;;; foo
   2.139+(print "H1") ;; just an inline comment
   2.140+;;;; bar
   2.141+(print "H2")
   2.142+;;; baz
   2.143+(print "H1")
   2.144+#+end_src
   2.145 
   2.146-** Elements
   2.147-:PROPERTIES:
   2.148-:CUSTOM_ID: 4aa3ec2a-b360-43ae-b2d8-f9735f211290
   2.149-:END:
   2.150-This section documents the /extensions/ made to =Org syntax=. Each
   2.151-sub-heading focuses on a pre-existing =Org= element and describes
   2.152-=Ulang= functionality included with =ulang.el=.
   2.153+A collection of /headings/ is what we call an *Outline* - which is
   2.154+also the name of the major-mode utilized for this feature and of
   2.155+course - what Org itself is derived from.
   2.156 
   2.157-*** Keywords
   2.158+** Keywords
   2.159 :PROPERTIES:
   2.160 :CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
   2.161 :END:
   2.162-The ulang *Keywords* are a superset of those defined by [[https://datatracker.ietf.org/doc/html/rfc2119][RFC-2119]].
   2.163 
   2.164-#+begin_quote
   2.165-In many standards track documents several words are used to signify
   2.166-the requirements in the specification.  These words are often
   2.167-capitalized.  This document defines these words as they should be
   2.168-interpreted in IETF documents.  Authors who follow these guidelines
   2.169-should incorporate this phrase near the beginning of their document:
   2.170-
   2.171-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
   2.172-NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
   2.173-"OPTIONAL" in this document are to be interpreted as described in
   2.174-RFC 2119.
   2.175-#+end_quote
   2.176+The following keywords indicate the state of an element. They often
   2.177+appear as the first word in a heading to indicate a [[*Tasks][Task]].
   2.178 
   2.179-#+begin_quote
   2.180-1. MUST   This word, or the terms "REQUIRED" or "SHALL", mean that the
   2.181-   definition is an absolute requirement of the specification.
   2.182-
   2.183-2. MUST NOT   This phrase, or the phrase "SHALL NOT", mean that the
   2.184-   definition is an absolute prohibition of the specification.
   2.185-
   2.186-3. SHOULD   This word, or the adjective "RECOMMENDED", mean that there
   2.187-   may exist valid reasons in particular circumstances to ignore a
   2.188-   particular item, but the full implications must be understood and
   2.189-   carefully weighed before choosing a different course.
   2.190-
   2.191-4. SHOULD NOT   This phrase, or the phrase "NOT RECOMMENDED" mean that
   2.192-   there may exist valid reasons in particular circumstances when the
   2.193-   particular behavior is acceptable or even useful, but the full
   2.194-   implications should be understood and the case carefully weighed
   2.195-   before implementing any behavior described with this label.
   2.196+- TBD :: A task to be done at a later date.
   2.197+- TODO :: A task yet to be done.
   2.198+- FIXME :: Item that needs fixing.
   2.199+- WIP :: Work In Progress task.
   2.200+- WAIT :: A suspended task.
   2.201+- DEAD :: Item that will not be completed.
   2.202+- DONE :: Completed task.
   2.203+- BUG :: Designate a bug item.
   2.204+- IDEA :: Designate an idea item.
   2.205+- NOTE :: Designates a note item.
   2.206+- DRAFT :: Designates a draft item.
   2.207+- COMMENT :: A 'commented' item.
   2.208+** Tasks
   2.209+Tasks as they are known in Org, usually consist of a heading that
   2.210+starts with a [[#2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and
   2.211+metadata which are present in our collection of tasks.
   2.212 
   2.213-5. MAY   This word, or the adjective "OPTIONAL", mean that an item is
   2.214-   truly optional.  One vendor may choose to include the item because a
   2.215-   particular marketplace requires it or because the vendor feels that
   2.216-   it enhances the product while another vendor may omit the same item.
   2.217-   An implementation which does not include a particular option MUST be
   2.218-   prepared to interoperate with another implementation which does
   2.219-   include the option, though perhaps with reduced functionality. In the
   2.220-   same vein an implementation which does include a particular option
   2.221-   MUST be prepared to interoperate with another implementation which
   2.222-   does not include the option (except, of course, for the feature the
   2.223-   option provides.)
   2.224-#+end_quote
   2.225+Our task management system is roughly a hybrid of two more
   2.226+conventional methods: GTD and Agile. For convenience I will describe
   2.227+these styles and how I use them separately, but the concepts may be
   2.228+spliced differently in real tasks.
   2.229 
   2.230-One of the important features of keywords is that we use them as Org
   2.231-[[https://orgmode.org/manual/Workflow-states.html][Workflow states]]. You may use any of the keywords above or below as the
   2.232-first word in a heading to signify a requirement or a workflow state:
   2.233+- *GTD* \\
   2.234+- *Agile* \\
   2.235+  It's a dirty word in some tech circles - the dreaded PIs, daily
   2.236+  standups, and still nobody knows what's going on, Oh my! Do not
   2.237+  worry. For the most part we just borrow the vocabulary.
   2.238 
   2.239-6. TBD   A task to be done at a later date.
   2.240-
   2.241-7. TODO   A task yet to be done.
   2.242-
   2.243-8. WIP   Work In Progress task.
   2.244-
   2.245-9. NOTE   Designates a note item.
   2.246+  Our /Agile/ workflow consists of roadmaps, features (epics/ARTs),
   2.247+  issues (user stories), and of course, tasks.
   2.248+** Ids
   2.249+We reference two different types of identifiers in documentation:
   2.250+- UUID :: CUSTOM_ID property
   2.251+- User-defined :: ID property
   2.252 
   2.253-10. DRAFT   Designates a draft item.
   2.254-
   2.255-11. DEAD   Item that will not be completed.
   2.256+UUIDs on =CUSTOM_ID= property is admittedly a kludge. This is done for
   2.257+reasons of portability. We may at some point rename this property
   2.258+=UUID= (TBD).
   2.259 
   2.260-12. DONE   Completed task.
   2.261-
   2.262-13. COMMENT A 'commented' item.
   2.263-
   2.264-*** Macros
   2.265+Most of the time these Ids don't add any information for the reader -
   2.266+the UUIDs are used to index and graph documents, IDs are for
   2.267+convenience.
   2.268+** Macros
   2.269 :PROPERTIES:
   2.270 :CUSTOM_ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e
   2.271 :END:
   2.272@@ -185,96 +161,6 @@
   2.273 
   2.274 Macros /are not expanded/ in source files - you will see them in the
   2.275 form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition
   2.276-(in =ulang.el=) in order to export ulang docs with the macros
   2.277-expanded.
   2.278-
   2.279-*** Hyperlinks
   2.280-The Org-mode [[https://orgmode.org/manual/Link-Format.html][Link Format]] is used throughout the Ulang and needs little
   2.281-introduction.
   2.282-**** Types
   2.283-#+begin_src emacs-lisp :results replace pp :exports both
   2.284-(org-link-types)
   2.285-#+end_src
   2.286-
   2.287-#+RESULTS:
   2.288-: ("notmuch-tree" "notmuch-search" "notmuch" "man" "eww" "rmail" "mhe"
   2.289-:  "irc" "info" "gnus" "docview" "bibtex" "bbdb" "w3m" "doi" "id"
   2.290-:  "elfeed" "file+sys" "file+emacs" "shell" "news" "mailto" "https"
   2.291-:  "http" "ftp" "help" "file" "elisp")
   2.292-
   2.293-**** Abbrevs
   2.294-For ease of use we have defined some special link handling abbrevs:
   2.295-
   2.296-#+begin_src emacs-lisp :results replace pp :exports both
   2.297-  org-link-abbrev-alist
   2.298-#+end_src
   2.299-
   2.300-#+RESULTS:
   2.301-: (("vc" . "https://vc.compiler.company/%s")
   2.302-:  ("comp" . "https://compiler.company/%s")
   2.303-:  ("cdn" . "https://cdn.compiler.company/%s")
   2.304-:  ("packy" . "https://packy.compiler.company/%s")
   2.305-:  ("yt" . "https://youtube.com/watch?v=%s"))
   2.306-
   2.307-*** Dynamic Blocks
   2.308-[[https://orgmode.org/manual/Blocks.html][Blocks]] are a feature of vanilla Org-mode which are described in the
   2.309-manual. We extend this functionality with [[https://orgmode.org/manual/Dynamic-Blocks.html][Dynamic Blocks]]. The
   2.310-important feature of these blocks is that their contents are updated
   2.311-/dynamically/ by a user within an Org-mode document.
   2.312-
   2.313-For example, typing ~C-c C-c~ on the block below dynamically generates
   2.314-the standard clocktable for the current file.
   2.315-
   2.316-To update all dynamic blocks in a document, use the
   2.317-=org-dblock-update= ~C-c C-x C-u~ function.
   2.318+(in =ulang.el=) in order to use some Org-Mode functions (org-export)
   2.319+with our docs.
   2.320 
   2.321-#+BEGIN: clocktable
   2.322-#+CAPTION: Clock summary at [2023-11-25 Sat 15:26]
   2.323-| Headline     | Time   |
   2.324-|--------------+--------|
   2.325-| *Total time* | *0:00* |
   2.326-#+END:
   2.327-
   2.328-#+begin_src emacs-lisp :results replace pp :exports both
   2.329-  org-dynamic-block-alist
   2.330-#+end_src
   2.331-
   2.332-#+RESULTS:
   2.333-: (("files" . ulang-dblock-insert-files)
   2.334-:  ("links" . ulang-dblock-insert-links)
   2.335-:  ("columnview" . org-columns-insert-dblock)
   2.336-:  ("clocktable" . org-clock-report))
   2.337-
   2.338-*** Tables
   2.339-:PROPERTIES:
   2.340-:CUSTOM_ID: ulang-tables
   2.341-:END:
   2.342-
   2.343-Org [[https://orgmode.org/manual/Tables.html][Tables]] are powerful but require many extensions to really /feel/
   2.344-powerful. As they come in vanilla Emacs, they don't feel as good as
   2.345-commercial spreadsheet-based software. The Ulang Table extensions add
   2.346-some sane defaults and additional data-processing utilities to work
   2.347-with tables in any text, not just Org docs.
   2.348-
   2.349-A vanilla Org Table may look like this:
   2.350-
   2.351-| x |  y |  z |
   2.352-|---+----+----|
   2.353-| 1 |  2 |  3 |
   2.354-| 8 |  9 | 10 |
   2.355-| 9 | 10 | 11 |
   2.356-| 3 |  4 |  5 |
   2.357-| 7 |  8 |  9 |
   2.358-| 2 |  3 |  4 |
   2.359-#+TBLFM: $2=$1+1::$3=$2+1
   2.360-
   2.361-Just like in Excel, we can define a table outline like the one above
   2.362-and use code to fill in the values with a formula: =$2=$1+1::$3=$2+1=.
   2.363-
   2.364-Unlike Excel, these tables can appear pretty much anywhere - including
   2.365-in source code.
   2.366-
   2.367-Usually we prefer to use lisp to prepare our data and
   2.368-populate complex tables, or no-nonsense keyboard commands for short
   2.369-tables. This is done with a few functions in Org docs and the =orgtbl=
   2.370-minor-mode everywhere else.