2.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2+++ b/core/readme.org Mon Nov 27 18:24:49 2023 -0500
2.3@@ -0,0 +1,4 @@
2.4+{{{header(docs/core,Richard Westhaver,ellis@rwest.io)}}}
2.5+#+EXPORT_FILE_NAME: index
2.6+
2.7+- [[file:notes.org][Notes]] :: Internal Notes.
3.1--- a/future.org Fri Nov 24 22:39:07 2023 -0500
3.2+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
3.3@@ -1,2 +0,0 @@
3.4-#+TITLE: future
3.5-#+AUTHOR: ellis
5.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2+++ b/infra/readme.org Mon Nov 27 18:24:49 2023 -0500
5.3@@ -0,0 +1,4 @@
5.4+{{{header(docs/infra,Richard Westhaver,ellis@rwest.io)}}}
5.5+#+EXPORT_FILE_NAME: index
5.6+
5.7+- [[file:notes.org][Notes]] :: Internal Notes.
6.1--- a/manifesto.org Fri Nov 24 22:39:07 2023 -0500
6.2+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
6.3@@ -1,5 +0,0 @@
6.4-#+TITLE: manifesto
6.5-#+AUTHOR: ellis
6.6-#+DATE: 2023-04-01 Sat
6.7-* Abstract
6.8-* Introduction
7.1--- a/nas-t/readme.org Fri Nov 24 22:39:07 2023 -0500
7.2+++ b/nas-t/readme.org Mon Nov 27 18:24:49 2023 -0500
7.3@@ -1,7 +1,4 @@
7.4-{{{header(docs/NAS-T,
7.5-Richard Westhaver,
7.6-ellis@rwest.io,
7.7-NAS-T Documentation)}}}
7.8+{{{header(docs/NAS-T,Richard Westhaver,ellis@rwest.io,NAS-T Documentation)}}}
7.9 #+EXPORT_FILE_NAME: index
7.10
7.11 Welcome to the documentation home of NAS-T. Choose one of the topics below to get
8.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2+++ b/readme.org Mon Nov 27 18:24:49 2023 -0500
8.3@@ -0,0 +1,15 @@
8.4+{{{header(
8.5+ docs,
8.6+ Richard Westhaver,
8.7+ ellis@rwest.io,
8.8+ The Compiler Company Documentation)}}}
8.9+#+EXPORT_FILE_NAME: index
8.10+
8.11+* [[https://compiler.company/docs/ulang.html][ulang]]
8.12+* [[https://compiler.company/docs/style.html][style]]
8.13+* [[https://compiler.company/docs/tech.html][tech]]
8.14+* [[https://compiler.company/docs/core][core]]
8.15+* [[https://compiler.company/docs/infra][infra]]
8.16+* [[https://compiler.company/docs/business.html][business]]
8.17+* projects
8.18+** [[https://compiler.company/docs/nas-t][NAS-T]]
9.1--- a/tech.org Fri Nov 24 22:39:07 2023 -0500
9.2+++ b/tech.org Mon Nov 27 18:24:49 2023 -0500
9.3@@ -3,38 +3,25 @@
9.4 ellis@rwest.io,
9.5 The Compiler Company Core Technologies)}}}
9.6
9.7-Editors:
9.8-- Emacs
9.9-
9.10-Core PLs:
9.11-- Lisp
9.12-- Rust
9.13-- C
9.14-
9.15 OS:
9.16 - GNU/Linux
9.17-- MacOS
9.18-- Windows
9.19+ - *Arch Linux*
9.20+Core:
9.21+- Lisp
9.22+- Rust
9.23+- Emacs
9.24
9.25-Ecosystem:
9.26-- RocksDB
9.27-- QUIC
9.28-- QEMU
9.29-- Postgres
9.30-- SQLite
9.31-- AWS
9.32-- GCP
9.33-- LLVM
9.34+Shared Libs:
9.35+- rocksdb
9.36+- alpm
9.37+- btrfs
9.38+- tree-sitter
9.39+- uring
9.40+- blake3
9.41+- xcb
9.42+
9.43+Extra:
9.44+- K
9.45+- BQN
9.46 - Python
9.47-- Node.js
9.48-- X11
9.49-- systemd
9.50-- UEFI
9.51-- Nginx
9.52-- Wireguard
9.53-- OpenVPN
9.54-- IRC
9.55-- Matrix
9.56-- Discord
9.57-- Notion.so
9.58-- Stripe
9.59+- 2BWM
10.1--- a/ulang.org Fri Nov 24 22:39:07 2023 -0500
10.2+++ b/ulang.org Mon Nov 27 18:24:49 2023 -0500
10.3@@ -19,11 +19,11 @@
10.4
10.5 * ulang
10.6 :PROPERTIES:
10.7-:CUSTOM_ID: 8447a560-7f77-45c7-bd14-2a2af6ad2abc
10.8+:CUSTOM_ID: ulang
10.9 :END:
10.10 As the title suggest we refer to our *U-Language* as
10.11 ulang. When I say something along the lines of "Please refer to
10.12-[[Links][ulang:links]]", I am referencing the section named /Links/ of this
10.13+[[*Hyperlinks][ulang.Hyperlinks]]", I am referencing the section named /Links/ of this
10.14 document.
10.15
10.16 Each section of this document describes an element of the ulang. It is
10.17@@ -47,17 +47,6 @@
10.18 of Org is arbitrary and the concepts here would apply to other formats
10.19 (LaTeX, Markdown, etc).
10.20
10.21-Let us first consider /Org the syntax/.
10.22-
10.23-Org syntax is much less popular than Markdown and lacks parsing
10.24-utilities in popular programming languages[fn:1]. Regardless, we are
10.25-committed to it as a foundation because it is the most hackable
10.26-documentation engine available. With enough experience you can morph
10.27-Org into whatever documentation system that is needed.
10.28-
10.29-[fn:1] The ecosystem is changing though, thanks to the dedication of
10.30-some excellent hackers: [[https://github.com/karlicoss/orgparse][python]], [[https://github.com/tecosaur/Org.jl][julia]]
10.31-
10.32 *** TODO organ
10.33 :PROPERTIES:
10.34 :CUSTOM_ID: 22474039-5c18-4179-82aa-a6731e6313a2
10.35@@ -78,18 +67,40 @@
10.36 full-text search database, and reducing cost along the way.
10.37
10.38 Emacs can do all of these things, but do you really want it to?
10.39+
10.40+** Syntax
10.41+Let us first consider /Org the syntax/.
10.42+
10.43+Org syntax is much less popular than Markdown and lacks parsing
10.44+utilities in popular programming languages[fn:1]. Regardless, we are
10.45+committed to it as a foundation because it is the most hackable
10.46+documentation engine available. With enough experience you can morph
10.47+Org into whatever documentation system that is needed.
10.48+
10.49+
10.50+As such, all documentation we write is done using =Org syntax=. When
10.51+we refer to Org syntax we are referring to the vanilla syntax which
10.52+comes built-in with Emacs.
10.53+
10.54+=Ulang syntax= is an extension of =Org syntax=. If some feature of the
10.55+=Ulang= is undocumented, refer to =Org syntax= for guidance.
10.56+
10.57+[fn:1] The ecosystem is changing though, thanks to the dedication of
10.58+some excellent hackers: [[https://github.com/karlicoss/orgparse][python]], [[https://github.com/tecosaur/Org.jl][julia]]
10.59+
10.60 ** Elements
10.61 :PROPERTIES:
10.62 :CUSTOM_ID: 4aa3ec2a-b360-43ae-b2d8-f9735f211290
10.63 :END:
10.64+This section documents the /extensions/ made to =Org syntax=. Each
10.65+sub-heading focuses on a pre-existing =Org= element and describes
10.66+=Ulang= functionality included with =ulang.el=.
10.67
10.68 *** Keywords
10.69 :PROPERTIES:
10.70 :CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
10.71 :END:
10.72-The ulang *Keywords* are a superset of those defined by [[https://datatracker.ietf.org/doc/html/rfc2119][RFC-2119]]. The
10.73-definition of a keyword from the original spec is ultimately
10.74-unchanged:
10.75+The ulang *Keywords* are a superset of those defined by [[https://datatracker.ietf.org/doc/html/rfc2119][RFC-2119]].
10.76
10.77 #+begin_quote
10.78 In many standards track documents several words are used to signify
10.79@@ -104,9 +115,6 @@
10.80 RFC 2119.
10.81 #+end_quote
10.82
10.83-We can't be bothered to include these with every document, so here
10.84-they are - don't forget!
10.85-
10.86 #+begin_quote
10.87 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the
10.88 definition is an absolute requirement of the specification.
10.89@@ -166,36 +174,107 @@
10.90 here for convenience.
10.91
10.92 #+name: ulang-macros
10.93-#+begin_src emacs-lisp :exports both :results pp
10.94+#+begin_src emacs-lisp :exports both :results replace pp
10.95 org-export-global-macros
10.96 #+end_src
10.97
10.98 #+RESULTS: ulang-macros
10.99-: (("opts" . "#+OPTIONS: $1\n")
10.100-: ("header" .
10.101-: "#+TITLE: $1\n#+AUTHOR: $2\n#+EMAIL: $3\n#+DESCRIPTION: $4\n#+SUBTITLE: $4\n#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil\n#+HTML_HEAD: <link rel=\"stylesheet\" href=\"https://fonts.xz.style/serve/inter.css\"/>\n#+HTML_HEAD: <link rel=\"stylesheet\" type=\"text/css\" href=\"https://cdn.compiler.company/css/new.min.css\"/>\n#+HTML_HEAD: <link rel=\"stylesheet\" type=\"text/css\" href=\"https://cdn.compiler.company/css/night.css\"/>\n"))
10.102+: (("header" .
10.103+: "#+TITLE: $1\n#+AUTHOR: $2\n#+EMAIL: $3\n#+DESCRIPTION: $4\n#+SUBTITLE: $4\n#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil\n#+HTML_HEAD: <link rel=\"stylesheet\" href=\"https://fonts.xz.style/serve/inter.css\"/>\n#+HTML_HEAD: <link rel=\"stylesheet\" type=\"text/css\" href=\"https://cdn.compiler.company/css/new.min.css\"/>\n#+HTML_HEAD: <link rel=\"stylesheet\" type=\"text/css\" href=\"https://cdn.compiler.company/css/night.css\"/>\n")
10.104+: ("opts" . "#+OPTIONS: $1\n"))
10.105
10.106 Macros /are not expanded/ in source files - you will see them in the
10.107 form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition
10.108 (in =ulang.el=) in order to export ulang docs with the macros
10.109 expanded.
10.110
10.111-*** Abbrevs
10.112-:PROPERTIES:
10.113-:CUSTOM_ID: b4c326ba-f74c-4409-9314-8d32df61fc5e
10.114-:END:
10.115-There are several 'abbrev' types made available via =ulang.el=. They
10.116-are intended for flexible templating and ease-of-use for the author.
10.117+*** Hyperlinks
10.118+The Org-mode [[https://orgmode.org/manual/Link-Format.html][Link Format]] is used throughout the Ulang and needs little
10.119+introduction.
10.120+**** Types
10.121+#+begin_src emacs-lisp :results replace pp :exports both
10.122+(org-link-types)
10.123+#+end_src
10.124+
10.125+#+RESULTS:
10.126+: ("notmuch-tree" "notmuch-search" "notmuch" "man" "eww" "rmail" "mhe"
10.127+: "irc" "info" "gnus" "docview" "bibtex" "bbdb" "w3m" "doi" "id"
10.128+: "elfeed" "file+sys" "file+emacs" "shell" "news" "mailto" "https"
10.129+: "http" "ftp" "help" "file" "elisp")
10.130+
10.131+**** Abbrevs
10.132+For ease of use we have defined some special link handling abbrevs:
10.133+
10.134+#+begin_src emacs-lisp :results replace pp :exports both
10.135+ org-link-abbrev-alist
10.136+#+end_src
10.137+
10.138+#+RESULTS:
10.139+: (("vc" . "https://vc.compiler.company/%s")
10.140+: ("comp" . "https://compiler.company/%s")
10.141+: ("cdn" . "https://cdn.compiler.company/%s")
10.142+: ("packy" . "https://packy.compiler.company/%s")
10.143+: ("yt" . "https://youtube.com/watch?v=%s"))
10.144+
10.145+*** Dynamic Blocks
10.146+[[https://orgmode.org/manual/Blocks.html][Blocks]] are a feature of vanilla Org-mode which are described in the
10.147+manual. We extend this functionality with [[https://orgmode.org/manual/Dynamic-Blocks.html][Dynamic Blocks]]. The
10.148+important feature of these blocks is that their contents are updated
10.149+/dynamically/ by a user within an Org-mode document.
10.150+
10.151+For example, typing ~C-c C-c~ on the block below dynamically generates
10.152+the standard clocktable for the current file.
10.153+
10.154+To update all dynamic blocks in a document, use the
10.155+=org-dblock-update= ~C-c C-x C-u~ function.
10.156
10.157-We try to align our abbrevs following categories:
10.158-- uri
10.159-- term
10.160-- phrase
10.161-- block
10.162+#+BEGIN: clocktable
10.163+#+CAPTION: Clock summary at [2023-11-25 Sat 15:26]
10.164+| Headline | Time |
10.165+|--------------+--------|
10.166+| *Total time* | *0:00* |
10.167+#+END:
10.168+
10.169+#+begin_src emacs-lisp :results replace pp :exports both
10.170+ org-dynamic-block-alist
10.171+#+end_src
10.172+
10.173+#+RESULTS:
10.174+: (("files" . ulang-dblock-insert-files)
10.175+: ("links" . ulang-dblock-insert-links)
10.176+: ("columnview" . org-columns-insert-dblock)
10.177+: ("clocktable" . org-clock-report))
10.178+
10.179+*** Tables
10.180+:PROPERTIES:
10.181+:CUSTOM_ID: ulang-tables
10.182+:END:
10.183
10.184-Abbrevs may take arguments explicitly or inherit from their
10.185-environment, but usually /are expanded/ in source files.
10.186+Org [[https://orgmode.org/manual/Tables.html][Tables]] are powerful but require many extensions to really /feel/
10.187+powerful. As they come in vanilla Emacs, they don't feel as good as
10.188+commercial spreadsheet-based software. The Ulang Table extensions add
10.189+some sane defaults and additional data-processing utilities to work
10.190+with tables in any text, not just Org docs.
10.191+
10.192+A vanilla Org Table may look like this:
10.193
10.194-*** Links
10.195+| x | y | z |
10.196+|---+----+----|
10.197+| 1 | 2 | 3 |
10.198+| 8 | 9 | 10 |
10.199+| 9 | 10 | 11 |
10.200+| 3 | 4 | 5 |
10.201+| 7 | 8 | 9 |
10.202+| 2 | 3 | 4 |
10.203+#+TBLFM: $2=$1+1::$3=$2+1
10.204
10.205-*** Timestamps
10.206+Just like in Excel, we can define a table outline like the one above
10.207+and use code to fill in the values with a formula: =$2=$1+1::$3=$2+1=.
10.208+
10.209+Unlike Excel, these tables can appear pretty much anywhere - including
10.210+in source code.
10.211+
10.212+Usually we prefer to use lisp to prepare our data and
10.213+populate complex tables, or no-nonsense keyboard commands for short
10.214+tables. This is done with a few functions in Org docs and the =orgtbl=
10.215+minor-mode everywhere else.
