# HG changeset patch # User ellis # Date 1701127489 18000 # Node ID 713c22bdab6a9c2cfb0aff411c0e39e40779bddb # Parent bb51c61e4d4b800f08abf14a791d8ecb7fdab353 organizing diff -r bb51c61e4d4b -r 713c22bdab6a core/notes.org diff -r bb51c61e4d4b -r 713c22bdab6a core/readme.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/readme.org Mon Nov 27 18:24:49 2023 -0500 @@ -0,0 +1,4 @@ +{{{header(docs/core,Richard Westhaver,ellis@rwest.io)}}} +#+EXPORT_FILE_NAME: index + +- [[file:notes.org][Notes]] :: Internal Notes. diff -r bb51c61e4d4b -r 713c22bdab6a future.org --- a/future.org Fri Nov 24 22:39:07 2023 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,2 +0,0 @@ -#+TITLE: future -#+AUTHOR: ellis diff -r bb51c61e4d4b -r 713c22bdab6a infra/notes.org diff -r bb51c61e4d4b -r 713c22bdab6a infra/readme.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/infra/readme.org Mon Nov 27 18:24:49 2023 -0500 @@ -0,0 +1,4 @@ +{{{header(docs/infra,Richard Westhaver,ellis@rwest.io)}}} +#+EXPORT_FILE_NAME: index + +- [[file:notes.org][Notes]] :: Internal Notes. diff -r bb51c61e4d4b -r 713c22bdab6a manifesto.org --- a/manifesto.org Fri Nov 24 22:39:07 2023 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -#+TITLE: manifesto -#+AUTHOR: ellis -#+DATE: 2023-04-01 Sat -* Abstract -* Introduction diff -r bb51c61e4d4b -r 713c22bdab6a nas-t/readme.org --- a/nas-t/readme.org Fri Nov 24 22:39:07 2023 -0500 +++ b/nas-t/readme.org Mon Nov 27 18:24:49 2023 -0500 @@ -1,7 +1,4 @@ -{{{header(docs/NAS-T, -Richard Westhaver, -ellis@rwest.io, -NAS-T Documentation)}}} +{{{header(docs/NAS-T,Richard Westhaver,ellis@rwest.io,NAS-T Documentation)}}} #+EXPORT_FILE_NAME: index Welcome to the documentation home of NAS-T. Choose one of the topics below to get diff -r bb51c61e4d4b -r 713c22bdab6a readme.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/readme.org Mon Nov 27 18:24:49 2023 -0500 @@ -0,0 +1,15 @@ +{{{header( + docs, + Richard Westhaver, + ellis@rwest.io, + The Compiler Company Documentation)}}} +#+EXPORT_FILE_NAME: index + +* [[https://compiler.company/docs/ulang.html][ulang]] +* [[https://compiler.company/docs/style.html][style]] +* [[https://compiler.company/docs/tech.html][tech]] +* [[https://compiler.company/docs/core][core]] +* [[https://compiler.company/docs/infra][infra]] +* [[https://compiler.company/docs/business.html][business]] +* projects +** [[https://compiler.company/docs/nas-t][NAS-T]] diff -r bb51c61e4d4b -r 713c22bdab6a tech.org --- a/tech.org Fri Nov 24 22:39:07 2023 -0500 +++ b/tech.org Mon Nov 27 18:24:49 2023 -0500 @@ -3,38 +3,25 @@ ellis@rwest.io, The Compiler Company Core Technologies)}}} -Editors: -- Emacs - -Core PLs: -- Lisp -- Rust -- C - OS: - GNU/Linux -- MacOS -- Windows + - *Arch Linux* +Core: +- Lisp +- Rust +- Emacs -Ecosystem: -- RocksDB -- QUIC -- QEMU -- Postgres -- SQLite -- AWS -- GCP -- LLVM +Shared Libs: +- rocksdb +- alpm +- btrfs +- tree-sitter +- uring +- blake3 +- xcb + +Extra: +- K +- BQN - Python -- Node.js -- X11 -- systemd -- UEFI -- Nginx -- Wireguard -- OpenVPN -- IRC -- Matrix -- Discord -- Notion.so -- Stripe +- 2BWM diff -r bb51c61e4d4b -r 713c22bdab6a ulang.org --- a/ulang.org Fri Nov 24 22:39:07 2023 -0500 +++ b/ulang.org Mon Nov 27 18:24:49 2023 -0500 @@ -19,11 +19,11 @@ * ulang :PROPERTIES: -:CUSTOM_ID: 8447a560-7f77-45c7-bd14-2a2af6ad2abc +:CUSTOM_ID: ulang :END: As the title suggest we refer to our *U-Language* as ulang. When I say something along the lines of "Please refer to -[[Links][ulang:links]]", I am referencing the section named /Links/ of this +[[*Hyperlinks][ulang.Hyperlinks]]", I am referencing the section named /Links/ of this document. Each section of this document describes an element of the ulang. It is @@ -47,17 +47,6 @@ of Org is arbitrary and the concepts here would apply to other formats (LaTeX, Markdown, etc). -Let us first consider /Org the syntax/. - -Org syntax is much less popular than Markdown and lacks parsing -utilities in popular programming languages[fn:1]. Regardless, we are -committed to it as a foundation because it is the most hackable -documentation engine available. With enough experience you can morph -Org into whatever documentation system that is needed. - -[fn:1] The ecosystem is changing though, thanks to the dedication of -some excellent hackers: [[https://github.com/karlicoss/orgparse][python]], [[https://github.com/tecosaur/Org.jl][julia]] - *** TODO organ :PROPERTIES: :CUSTOM_ID: 22474039-5c18-4179-82aa-a6731e6313a2 @@ -78,18 +67,40 @@ full-text search database, and reducing cost along the way. Emacs can do all of these things, but do you really want it to? + +** Syntax +Let us first consider /Org the syntax/. + +Org syntax is much less popular than Markdown and lacks parsing +utilities in popular programming languages[fn:1]. Regardless, we are +committed to it as a foundation because it is the most hackable +documentation engine available. With enough experience you can morph +Org into whatever documentation system that is needed. + + +As such, all documentation we write is done using =Org syntax=. When +we refer to Org syntax we are referring to the vanilla syntax which +comes built-in with Emacs. + +=Ulang syntax= is an extension of =Org syntax=. If some feature of the +=Ulang= is undocumented, refer to =Org syntax= for guidance. + +[fn:1] The ecosystem is changing though, thanks to the dedication of +some excellent hackers: [[https://github.com/karlicoss/orgparse][python]], [[https://github.com/tecosaur/Org.jl][julia]] + ** Elements :PROPERTIES: :CUSTOM_ID: 4aa3ec2a-b360-43ae-b2d8-f9735f211290 :END: +This section documents the /extensions/ made to =Org syntax=. Each +sub-heading focuses on a pre-existing =Org= element and describes +=Ulang= functionality included with =ulang.el=. *** Keywords :PROPERTIES: :CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba :END: -The ulang *Keywords* are a superset of those defined by [[https://datatracker.ietf.org/doc/html/rfc2119][RFC-2119]]. The -definition of a keyword from the original spec is ultimately -unchanged: +The ulang *Keywords* are a superset of those defined by [[https://datatracker.ietf.org/doc/html/rfc2119][RFC-2119]]. #+begin_quote In many standards track documents several words are used to signify @@ -104,9 +115,6 @@ RFC 2119. #+end_quote -We can't be bothered to include these with every document, so here -they are - don't forget! - #+begin_quote 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification. @@ -166,36 +174,107 @@ here for convenience. #+name: ulang-macros -#+begin_src emacs-lisp :exports both :results pp +#+begin_src emacs-lisp :exports both :results replace pp org-export-global-macros #+end_src #+RESULTS: ulang-macros -: (("opts" . "#+OPTIONS: $1\n") -: ("header" . -: "#+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: \n#+HTML_HEAD: \n#+HTML_HEAD: \n")) +: (("header" . +: "#+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: \n#+HTML_HEAD: \n#+HTML_HEAD: \n") +: ("opts" . "#+OPTIONS: $1\n")) Macros /are not expanded/ in source files - you will see them in the form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition (in =ulang.el=) in order to export ulang docs with the macros expanded. -*** Abbrevs -:PROPERTIES: -:CUSTOM_ID: b4c326ba-f74c-4409-9314-8d32df61fc5e -:END: -There are several 'abbrev' types made available via =ulang.el=. They -are intended for flexible templating and ease-of-use for the author. +*** Hyperlinks +The Org-mode [[https://orgmode.org/manual/Link-Format.html][Link Format]] is used throughout the Ulang and needs little +introduction. +**** Types +#+begin_src emacs-lisp :results replace pp :exports both +(org-link-types) +#+end_src + +#+RESULTS: +: ("notmuch-tree" "notmuch-search" "notmuch" "man" "eww" "rmail" "mhe" +: "irc" "info" "gnus" "docview" "bibtex" "bbdb" "w3m" "doi" "id" +: "elfeed" "file+sys" "file+emacs" "shell" "news" "mailto" "https" +: "http" "ftp" "help" "file" "elisp") + +**** Abbrevs +For ease of use we have defined some special link handling abbrevs: + +#+begin_src emacs-lisp :results replace pp :exports both + org-link-abbrev-alist +#+end_src + +#+RESULTS: +: (("vc" . "https://vc.compiler.company/%s") +: ("comp" . "https://compiler.company/%s") +: ("cdn" . "https://cdn.compiler.company/%s") +: ("packy" . "https://packy.compiler.company/%s") +: ("yt" . "https://youtube.com/watch?v=%s")) + +*** Dynamic Blocks +[[https://orgmode.org/manual/Blocks.html][Blocks]] are a feature of vanilla Org-mode which are described in the +manual. We extend this functionality with [[https://orgmode.org/manual/Dynamic-Blocks.html][Dynamic Blocks]]. The +important feature of these blocks is that their contents are updated +/dynamically/ by a user within an Org-mode document. + +For example, typing ~C-c C-c~ on the block below dynamically generates +the standard clocktable for the current file. + +To update all dynamic blocks in a document, use the +=org-dblock-update= ~C-c C-x C-u~ function. -We try to align our abbrevs following categories: -- uri -- term -- phrase -- block +#+BEGIN: clocktable +#+CAPTION: Clock summary at [2023-11-25 Sat 15:26] +| Headline | Time | +|--------------+--------| +| *Total time* | *0:00* | +#+END: + +#+begin_src emacs-lisp :results replace pp :exports both + org-dynamic-block-alist +#+end_src + +#+RESULTS: +: (("files" . ulang-dblock-insert-files) +: ("links" . ulang-dblock-insert-links) +: ("columnview" . org-columns-insert-dblock) +: ("clocktable" . org-clock-report)) + +*** Tables +:PROPERTIES: +:CUSTOM_ID: ulang-tables +:END: -Abbrevs may take arguments explicitly or inherit from their -environment, but usually /are expanded/ in source files. +Org [[https://orgmode.org/manual/Tables.html][Tables]] are powerful but require many extensions to really /feel/ +powerful. As they come in vanilla Emacs, they don't feel as good as +commercial spreadsheet-based software. The Ulang Table extensions add +some sane defaults and additional data-processing utilities to work +with tables in any text, not just Org docs. + +A vanilla Org Table may look like this: -*** Links +| x | y | z | +|---+----+----| +| 1 | 2 | 3 | +| 8 | 9 | 10 | +| 9 | 10 | 11 | +| 3 | 4 | 5 | +| 7 | 8 | 9 | +| 2 | 3 | 4 | +#+TBLFM: $2=$1+1::$3=$2+1 -*** Timestamps +Just like in Excel, we can define a table outline like the one above +and use code to fill in the values with a formula: =$2=$1+1::$3=$2+1=. + +Unlike Excel, these tables can appear pretty much anywhere - including +in source code. + +Usually we prefer to use lisp to prepare our data and +populate complex tables, or no-nonsense keyboard commands for short +tables. This is done with a few functions in Org docs and the =orgtbl= +minor-mode everywhere else.