# HG changeset patch # User Richard Westhaver # Date 1723402075 14400 # Node ID d119ae1ce0d52f91fe201bc55ae26b289a6ba48a # Parent e8da1c55dcbe884d4c55d561000c919bfc325d61 ulang diff -r e8da1c55dcbe -r d119ae1ce0d5 pitch.org --- a/pitch.org Sun Aug 11 10:09:31 2024 -0400 +++ b/pitch.org Sun Aug 11 14:47:55 2024 -0400 @@ -2,6 +2,9 @@ #+author: Richard Westhaver #+setupfile: ../../clean.theme * Get Off of My Cloud +:PROPERTIES: +:ID: 6dbb0064-1421-41bb-b2df-36f694efce0a +:END: - industry has moved away from client-side, distributed compute in favor of centralized server-side compute resources behind API gateways. @@ -17,6 +20,9 @@ can collect and profit from * Death of the Programmer +:PROPERTIES: +:ID: 138f4a50-1d52-4e13-bf67-f225ef9f6747 +:END: - The role of the programmer is changing - programmers are no longer required to understand how computers work to have a successful career diff -r e8da1c55dcbe -r d119ae1ce0d5 readme.org --- a/readme.org Sun Aug 11 10:09:31 2024 -0400 +++ b/readme.org Sun Aug 11 14:47:55 2024 -0400 @@ -5,8 +5,26 @@ #+EXPORT_FILE_NAME: index #+setupfile: ../../clean.theme * [[file:ulang.org][ulang]] +:PROPERTIES: +:ID: 0ecd9330-de4d-4adf-bb7f-75d12f973a0a +:END: * [[file:style.org][style]] +:PROPERTIES: +:ID: f07097d7-afd7-4671-8bbb-386acbf6048f +:END: * [[file:tech.org][tech]] +:PROPERTIES: +:ID: fe8dbc96-ebc2-4461-a6fa-8a90f60a8df9 +:END: * [[file:business.org][business]] +:PROPERTIES: +:ID: b46cae62-6f62-4a54-a9aa-f5cbacbf000e +:END: * [[file:mindset.org][mindset]] +:PROPERTIES: +:ID: 7a338797-f0bb-46ee-8bc0-81b9c874b7bb +:END: * [[file:workflows.org][workflows]] +:PROPERTIES: +:ID: c7dc2ecf-7655-4ce6-b6e7-52674364e8fc +:END: diff -r e8da1c55dcbe -r d119ae1ce0d5 style.org --- a/style.org Sun Aug 11 10:09:31 2024 -0400 +++ b/style.org Sun Aug 11 14:47:55 2024 -0400 @@ -13,6 +13,9 @@ [fn:1] https://google.github.io/styleguide/ * General Programming +:PROPERTIES: +:ID: 5cee979a-3732-45ed-87f5-cadf591cac42 +:END: - indent-offset = 2 - max-line-width = 80 - page-length ~ 32 @@ -28,6 +31,9 @@ - =main= functions belong at the bottom of a file - use LSP wherever possible (eglot, slime) * Common Lisp +:PROPERTIES: +:ID: d4c25810-ce35-411e-a371-67ab7e814260 +:END: - prefer symbol docs to comments - use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]] - always prefer =core= libraries over vendored dependencies @@ -38,11 +44,17 @@ polished - don't be afraid of macros ** Systems +:PROPERTIES: +:ID: 2a323c4c-362c-429f-9849-587e2a7311f5 +:END: - define systems using keyword symbols - use slash instead of dash for path separation in system names: =:foo/bar= - define your test system in the same file with a name of: =:foo/tests= - where possible, avoid collisions with systems in Quicklisp ** Packages +:PROPERTIES: +:ID: f735b4b5-4818-408b-a244-e2fb506c7ded +:END: - declare packages in a file named =pkg.lisp= - when multiple packages are being declared, consider a wrapper package @@ -51,8 +63,14 @@ system name as their root path. - use ~:NICKNAMES~ to declare alternative names for your package ** CLOS +:PROPERTIES: +:ID: 5068e164-764a-4843-be8f-126754938ef9 +:END: - prefer =:default-initargs= over =:initform=. * Rust +:PROPERTIES: +:ID: 8e414073-36b6-45d4-9a11-e6de8a0a65e9 +:END: - always prefer =core= libraries to vendored dependencies - don't make =mod.rs= files - use the =foo.rs=, =foo/*= pattern instead @@ -61,6 +79,18 @@ - derive default methods for =Default=, =Hash=, =Copy=, etc where possible - use generics where appropriate: =foo>(path:P){p.as_ref();}= * Emacs Lisp +:PROPERTIES: +:ID: 8b17f8a3-74f2-44cd-a5ce-7df540e2544c +:END: * Org-mode +:PROPERTIES: +:ID: ea4fa698-7a46-46d6-a7a0-5b497119edf2 +:END: * Shell +:PROPERTIES: +:ID: 10904e36-e4ac-4841-b602-d4dc68a54c71 +:END: * Python +:PROPERTIES: +:ID: 5b402ced-2329-4a16-b512-76859157a9d6 +:END: diff -r e8da1c55dcbe -r d119ae1ce0d5 tech.org --- a/tech.org Sun Aug 11 10:09:31 2024 -0400 +++ b/tech.org Sun Aug 11 14:47:55 2024 -0400 @@ -5,26 +5,74 @@ #+setupfile: ../../clean.theme * OS +:PROPERTIES: +:ID: 0c3a8097-e0bb-4c8a-9de2-907cffddbb8f +:END: We primarily support [[https://unix.org][Unix-based]] Operating Systems. Check project-specific docs for officially supported targets. Development and CI is ran on [[https://archlinux.org/][Arch Linux]] (btw). * Core +:PROPERTIES: +:ID: f6d8cc58-e6ec-4482-b6b8-3977e771a578 +:END: ** [[https://lisp-lang.org/][Lisp]] +:PROPERTIES: +:ID: 765d7aea-1f04-47ac-b59a-b5e83ce05194 +:END: ** [[https://www.rust-lang.org/][Rust]] +:PROPERTIES: +:ID: e4fce1b9-dc0f-4bd9-b26e-3b41e583e901 +:END: ** [[https://www.gnu.org/software/emacs/][Emacs]] +:PROPERTIES: +:ID: da8b7be1-28c9-44cb-b013-9e6edf2f0581 +:END: * Libs +:PROPERTIES: +:ID: e0db5df8-5e99-4199-a042-5bfab74f3711 +:END: ** [[https://rocksdb.org/][rocksdb]] +:PROPERTIES: +:ID: e363bbaa-57ad-4e73-af2b-7fe487f67c7c +:END: ** [[https://archlinux.org/pacman/][pacman]] +:PROPERTIES: +:ID: e2ce47d2-2a6d-4f7b-acd7-3835463072a8 +:END: ** [[https://docs.kernel.org/filesystems/btrfs.html][btrfs]] +:PROPERTIES: +:ID: 4e99345f-9e2b-4edb-9f97-5daf6fb66c14 +:END: ** [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]] +:PROPERTIES: +:ID: b13a05bd-cc78-4d9b-84db-873f2714f32c +:END: ** [[https://kernel.dk/io_uring.pdf][uring]] +:PROPERTIES: +:ID: 016e1ebc-56b0-47f6-a610-1f8761bf69dd +:END: ** [[https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf][blake3]] +:PROPERTIES: +:ID: a0898683-d3ce-4d44-aaf7-b989cc5418d8 +:END: * Extras +:PROPERTIES: +:ID: e1bf8a4c-a9d6-478a-879d-49d6b5a2a72b +:END: ** [[https://ngn.codeberg.page/k][k]] +:PROPERTIES: +:ID: 0f4175ad-656b-4348-9328-5e409379b3fd +:END: ** [[https://mlochbaum.github.io/BQN/][BQN]] +:PROPERTIES: +:ID: 3cc89f3d-20a5-420f-bc7e-0731254e5040 +:END: * Our Software +:PROPERTIES: +:ID: 06de34a3-60b4-4f48-bcab-eabeb3fe41c3 +:END: The software provided by /The Compiler Company/ is a powerful but opinionated programming environment. It consists of a GNU/Linux kernel, some vendored programs and libraries, and a suite of custom @@ -43,6 +91,9 @@ DSLs, and unmatched hackability ** Langs +:PROPERTIES: +:ID: f5411514-19d6-4fb0-bdbe-48c4b5581e5c +:END: /The Compiler Company/ is above all, a =Lisp Company=. The most powerful software requires the most powerful code. @@ -54,6 +105,9 @@ nightly Rust compiler toolchain. ** OS +:PROPERTIES: +:ID: 1ae69e1e-1e01-4e48-b205-e28fb0fd0b1e +:END: /The Compiler Company/ is a =Linux Company=. There may be minimal support for Darwin-based systems, but Microsoft Windows systems will never be officially supported. diff -r e8da1c55dcbe -r d119ae1ce0d5 ulang.org --- a/ulang.org Sun Aug 11 10:09:31 2024 -0400 +++ b/ulang.org Sun Aug 11 14:47:55 2024 -0400 @@ -1,12 +1,14 @@ -#+title: Universal Languages +#+title: Universal Language #+author: Richard Westhaver #+email: ellis@rwest.io -#+OPTIONS: toc:t -#+setupfile: ../../clean.theme - +#+setupfile: ../clean.theme +#+infojs_opt: toc:nil home:https://compiler.company up:./ view:showall +* 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 @@ -30,22 +32,14 @@ English is our primary form of communication for example. The line you are reading currently is a sentence which is part of a paragraph. -There are some non-obvious questions which deserve inquiry though. - -- *Who is this for?* \\ - This document is for authors and readers alike. It is a loose +- This document is for authors and curious readers. It is a loose specification, but also serves as introductory material into our communication and design philosophy. - -- *What is this for?* \\ - The purpose of this document is to provide a /standard of - communication/. - - All sources we write attempt to conform to this standard but this is +- 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 +** Org Mode :PROPERTIES: :ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1 :END: @@ -64,21 +58,61 @@ Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are not concerned about /Org-mode/ the application in this document. +For the remainder of this document, we assume basic knowledge of Org +Mode. + * ulang :PROPERTIES: -:ID: ulang +: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 or property of our ulang. +** Emphasis +:PROPERTIES: +:ID: 88bf1177-b5b7-4945-8bdc-5229803e617e :END: -As the title suggest we refer to our *U-Language* as *ulang*. Each -section of this document describes a feature. -** Outlines +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. +** 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 @@ -88,17 +122,37 @@ (print "H1") #+end_src +#+name: rust-headings +#+begin_src rust + /// foo + println!("H1"); + //// bar + println!("H2"); + /// baz + println!("H1"); +#+end_src + +** Outlines +:PROPERTIES: +:ID: 7b4d3229-d85f-4464-b9d0-6beccb1f7b2e +:END: A collection of /headings/ is what we call an *Outline* - which is also the name of the major-mode utilized for this feature and of course - what Org itself is derived from. - ** Keywords :PROPERTIES: :ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba :END: -The following keywords indicate the state of an element. They often -appear as the first word in a heading to indicate a [[*Tasks][Task]]. +In Org, TODO keywords are used to key track of the state of a [[https://orgmode.org/manual/TODO-Items.html][TODO +Item]]. + +In ulang, they are used for this purpose and [[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a +variety of stateful item types beyond just tasks - for example =NOTE= +and =PROJECT=. + +The following keywords indicate the state of a heading element. They +often appear as the first word in a heading. - TBD :: A task to be done at a later date. - TODO :: A task yet to be done. @@ -112,9 +166,20 @@ - NOTE :: Designates a note item. - DRAFT :: Designates a draft item. - COMMENT :: A 'commented' item. -** Tasks +- PROJECT :: Designates a project item containing a sequence of tasks. + +#+begin_src org + ,* PROJECT project + ,** DONE foo + ,** TODO bar +#+end_src + +** COMMENT Tasks +:PROPERTIES: +:ID: 0f4c0afd-a774-4b98-900b-1ab44f9fd2ef +:END: Tasks as they are known in Org, usually consist of a heading that -starts with a [[#2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and +starts with a [[id:2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and metadata which are present in our collection of tasks. Our task management system is roughly a hybrid of two more @@ -130,34 +195,61 @@ Our /Agile/ workflow consists of roadmaps, features (epics/ARTs), issues (user stories), and of course, tasks. -** IDs +** Properties +:PROPERTIES: +:ID: 174a993b-a5dc-4324-b4f8-dda8101a55b7 +:END: +*** IDs +: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 +- UUID :: =ID= property +- User-defined :: =CUSTOM_ID= property -Most of the time these Ids don't add any information for the reader - +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 but are rarely necessary given the many ways of identifying a headline. -** Macros +** Tags :PROPERTIES: -:ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e +:ID: a7ae1b2a-559e-46e9-8cab-33e39a218288 :END: -Several *global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed -here for convenience. +[[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. -#+name: ulang-macros -#+begin_src emacs-lisp :exports both :results replace pp - org-export-global-macros -#+end_src - -#+RESULTS: ulang-macros -: (("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 use some Org-Mode functions (org-export) -with our docs. - +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). +*** Tag Types +:PROPERTIES: +:ID: b686dbc5-3505-49d7-b66a-0772bcf1a726 +:END: +Tags may be prefixed with one of the following characters, indicating +a special tag type: +- =@= :: 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= +*** Tag Lists +:PROPERTIES: +:ID: 805862be-ba2b-4288-a2e3-791c0aa3802f +:END: +** Links +:PROPERTIES: +:ID: 7ecaec5d-c656-44e1-8fad-185915655cee +:END: +*** Link Types +:PROPERTIES: +:ID: 6aedc026-36d0-4763-adc8-8ae1a79f1b3e +:END: diff -r e8da1c55dcbe -r d119ae1ce0d5 workflows.org --- a/workflows.org Sun Aug 11 10:09:31 2024 -0400 +++ b/workflows.org Sun Aug 11 14:47:55 2024 -0400 @@ -3,15 +3,34 @@ #+email: ellis@rwest.io #+description: Meta Workflows #+setupfile: ../../clean.theme +* Roadmap +:PROPERTIES: +:ID: be90c808-6c3b-4381-a032-af07d54f5907 +:END: * Task Management - +:PROPERTIES: +:ID: 66333c80-aa6f-43d7-a305-44e218dde045 +:END: * Project Management - -* Roadmap - +:PROPERTIES: +:ID: 560f4094-e077-4389-9e09-dba1e0d4004e +:END: * Source Code Management +:PROPERTIES: +:ID: 81da5e76-2619-42c3-8a2a-dea2b815b261 +:END: * Data Management +:PROPERTIES: +:ID: e5c4702e-581d-41b7-a484-76730435f056 +:END: -* Resource Management +* Attachments +:PROPERTIES: +:ID: c179c71d-3ad6-480b-bb52-76307b4a6316 +:END: +* Archive +:PROPERTIES: +:ID: ca0dcc07-0517-4d04-86f0-905537cb7801 +:END: