1.1--- a/business.org Thu Nov 30 20:55:41 2023 -0500
1.2+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3@@ -1,17 +0,0 @@
1.4-{{{header(business,
1.5-Richard Westhaver,
1.6-ellis@rwest.io,
1.7-The Compiler Company Business Model)}}}
1.8-
1.9-In short, this document describes the business aspects of The Compiler
1.10-Company LLC. We are designed to be small, fast, and agile. We
1.11-infiltrate a market, apply our methodology, and develop solutions that
1.12-are simply years ahead of the competition. We treat the market like
1.13-we're the only supplier, because we can. This is in part due to our
1.14-internal research & development pursuits, but also our approach to
1.15-business. We build businesses and revenue streams the exact same way
1.16-we build software -- with a bottom up approach. This is our secret
1.17-weapon, and what gives us the ability to adapt to any environment
1.18-where our interests lie.
1.19-
1.20-#+TOC: headlines 3
2.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2+++ b/core/api/readme.org Mon Dec 04 21:09:11 2023 -0500
2.3@@ -0,0 +1,3 @@
2.4+{{{header(Core API Docs,Richard Westhaver,ellis@rwest.io)}}}
2.5+#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil
2.6+#+EXPORT_FILE_NAME: index
3.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2+++ b/core/app/readme.org Mon Dec 04 21:09:11 2023 -0500
3.3@@ -0,0 +1,3 @@
3.4+{{{header(Core App Docs,Richard Westhaver,ellis@rwest.io)}}}
3.5+#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil
3.6+#+EXPORT_FILE_NAME: index
4.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2+++ b/core/lib/readme.org Mon Dec 04 21:09:11 2023 -0500
4.3@@ -0,0 +1,3 @@
4.4+{{{header(Core Lib Docs,Richard Westhaver,ellis@rwest.io)}}}
4.5+#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil
4.6+#+EXPORT_FILE_NAME: index
5.1--- a/core/notes.org Thu Nov 30 20:55:41 2023 -0500
5.2+++ b/core/notes.org Mon Dec 04 21:09:11 2023 -0500
5.3@@ -0,0 +1,3 @@
5.4+{{{header(Core Notes,Richard Westhaver,ellis@rwest.io)}}}
5.5+#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil
5.6+
6.1--- a/core/readme.org Thu Nov 30 20:55:41 2023 -0500
6.2+++ b/core/readme.org Mon Dec 04 21:09:11 2023 -0500
6.3@@ -1,4 +1,10 @@
6.4 {{{header(docs/core,Richard Westhaver,ellis@rwest.io)}}}
6.5 #+EXPORT_FILE_NAME: index
6.6
6.7-- [[file:notes.org][Notes]] :: Internal Notes.
6.8+- [[file:notes.org][Notes]] :: Internal Notes
6.9+
6.10+- [[file:app][App Docs]] :: High-level App Documentation
6.11+
6.12+- [[file:lib][Lib Docs]] :: High-level Lib Documentation
6.13+
6.14+- [[file:api][API Docs]] :: API Reference
8.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2+++ b/meta/business.org Mon Dec 04 21:09:11 2023 -0500
8.3@@ -0,0 +1,17 @@
8.4+{{{header(business,
8.5+Richard Westhaver,
8.6+ellis@rwest.io,
8.7+The Compiler Company Business Model)}}}
8.8+
8.9+In short, this document describes the business aspects of The Compiler
8.10+Company LLC. We are designed to be small, fast, and agile. We
8.11+infiltrate a market, apply our methodology, and develop solutions that
8.12+are simply years ahead of the competition. We treat the market like
8.13+we're the only supplier, because we can. This is in part due to our
8.14+internal research & development pursuits, but also our approach to
8.15+business. We build businesses and revenue streams the exact same way
8.16+we build software -- with a bottom up approach. This is our secret
8.17+weapon, and what gives us the ability to adapt to any environment
8.18+where our interests lie.
8.19+
8.20+#+TOC: headlines 3
9.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2+++ b/meta/readme.org Mon Dec 04 21:09:11 2023 -0500
9.3@@ -0,0 +1,10 @@
9.4+{{{header(Meta Docs,Richard Westhaver,ellis@rwest.io)}}}
9.5+#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil
9.6+#+EXPORT_FILE_NAME: index
9.7+* [[file:ulang.org][ulang]]
9.8+* [[file:style.org][style]]
9.9+* [[file:tech.org][tech]]
9.10+* [[file:business.org][business]]
9.11+
9.12+
9.13+
10.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
10.2+++ b/meta/style.org Mon Dec 04 21:09:11 2023 -0500
10.3@@ -0,0 +1,43 @@
10.4+{{{header(style,
10.5+Richard Westhaver,
10.6+ellis@rwest.io,
10.7+The Compiler Company Styleguide)}}}
10.8+
10.9+As an organization we maintain a styleguide[fn:1] which lists all of
10.10+the style guidelines we use for our code. If you are contributing to
10.11+one of our projects, you should review and understand the relevant
10.12+sections below.
10.13+
10.14+You should also review the [[file:ulang.org][ulang]] document, which may shine some light
10.15+on code comments and developer docs.
10.16+
10.17+[fn:1] https://google.github.io/styleguide/
10.18+
10.19+* General Programming
10.20+- indent-offset = 2
10.21+- max-line-width = 80
10.22+- page-length ~ 32
10.23+- module-length ~ 512
10.24+- file-size ~ 1024
10.25+
10.26+- start every source-file with a header comment
10.27+- use outline headings to organize your program
10.28+- use ulang-comments as needed for referencing bugs, notes, etc.
10.29+- inline documentation should be declarative. your code explains your
10.30+ comments for you.
10.31+- variables, imports, and exports belong at the top of a file
10.32+- =main= functions belong at the bottom of a file
10.33+* Common Lisp
10.34+
10.35+- prefer symbol docs to comments
10.36+- use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]]
10.37+- always prefer =core= libraries over vendored dependencies
10.38+- use the compiler internals - if a function or class is generally
10.39+ useful, add it to the core
10.40+* Rust
10.41+- don't make =mod.rs= files
10.42+ - use the =foo.rs=, =foo/*= pattern instead
10.43+* Emacs Lisp
10.44+* Org-mode
10.45+* Shell
10.46+* Python
11.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
11.2+++ b/meta/tech.org Mon Dec 04 21:09:11 2023 -0500
11.3@@ -0,0 +1,24 @@
11.4+{{{header(tech,
11.5+Richard Westhaver,
11.6+ellis@rwest.io,
11.7+The Compiler Company Core Technologies)}}}
11.8+
11.9+* OS
11.10+We primarily support [[https://unix.org][Unix-based]] Operating Systems. Check
11.11+project-specific docs for officially supported targets.
11.12+
11.13+Development and CI is ran on [[https://archlinux.org/][Arch Linux]] (btw).
11.14+* Core
11.15+** [[https://lisp-lang.org/][Lisp]]
11.16+** [[https://www.rust-lang.org/][Rust]]
11.17+** [[https://www.gnu.org/software/emacs/][Emacs]]
11.18+* Libs
11.19+** [[https://rocksdb.org/][rocksdb]]
11.20+** [[https://archlinux.org/pacman/][pacman]]
11.21+** [[https://docs.kernel.org/filesystems/btrfs.html][btrfs]]
11.22+** [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]]
11.23+** [[https://kernel.dk/io_uring.pdf][uring]]
11.24+** [[https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf][blake3]]
11.25+* Extras
11.26+** [[https://ngn.codeberg.page/k][k]]
11.27+** [[https://mlochbaum.github.io/BQN/][BQN]]
12.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
12.2+++ b/meta/ulang.org Mon Dec 04 21:09:11 2023 -0500
12.3@@ -0,0 +1,166 @@
12.4+{{{header(ulang,
12.5+Richard Westhaver,
12.6+ellis@rwest.io,
12.7+The Universal Language)}}}
12.8+#+OPTIONS: toc:t
12.9+
12.10+This document describes a *U-Language* as described by the late great
12.11+[[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:
12.12+
12.13+#+begin_quote
12.14+Every investigation, including the present one, has to be communicated
12.15+from one person to another by means of language. It is expedient to
12.16+begin our study by calling attention to this obvious fact, by giving a
12.17+name to the language being used, and by being explicit about a few of
12.18+its features. We shall call the language being used the
12.19+U-Language. [...] There would be no point in calling attention to it,
12.20+if it were not for the fact that language is more intimately related
12.21+to our job than of most others.
12.22+#+end_quote
12.23+
12.24+In this document, we will be calling attention to our own language -
12.25+examining it, and describing how it works.
12.26+
12.27+Our job is to solve problems. Hard problems preferred. So we ought to
12.28+pay close attention to the language we use because it brings the
12.29+reader and writer /closer/ to the problem at hand.
12.30+
12.31+For starters, we are primarily concerned with /written languages/ like
12.32+the one you're reading now. We will skip past the obvious details -
12.33+English is our primary form of communication for example. The line you
12.34+are reading currently is a sentence which is part of a paragraph.
12.35+
12.36+There are some non-obvious questions which deserve inquiry though.
12.37+
12.38+- *Who is this for?* \\
12.39+ This document is for authors and readers alike. It is a loose
12.40+ specification, but also serves as introductory material into our
12.41+ communication and design philosophy.
12.42+
12.43+- *What is this for?* \\
12.44+ The purpose of this document is to provide a /standard of
12.45+ communication/.
12.46+
12.47+ All sources we write attempt to conform to this standard but this is
12.48+ not strictly enforced. If there is a reason to not comply with a
12.49+ rule, it is already broken.
12.50+
12.51+* Org Mode
12.52+:PROPERTIES:
12.53+:CUSTOM_ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1
12.54+:END:
12.55+[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word
12.56+processor.
12.57+
12.58+If you are already familiar with Emacs and Org-Mode, I recommend
12.59+opening the source of this document in Emacs and following along.
12.60+
12.61+If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't
12.62+be getting too deep into tribal hacker knowledge of Emacs.
12.63+
12.64+What's important to know is this: There is /Org Syntax/ and
12.65+/Org-mode/ - these are different things.
12.66+
12.67+Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are
12.68+not concerned about /Org-mode/ the application in this document.
12.69+
12.70+* ulang
12.71+:PROPERTIES:
12.72+:ID: ulang
12.73+:END:
12.74+As the title suggest we refer to our *U-Language* as *ulang*. Each
12.75+section of this document describes a feature.
12.76+** Outlines
12.77+In Org, headings can be summarize as any line starting with a star: =*
12.78+H1=. Headings can be nested or 'demoted' by prepending another star:
12.79+=** H2=.
12.80+
12.81+This is a useful pattern which we apply outside of Org - most commonly
12.82+in our code comments.
12.83+
12.84+In our source code, we use the comment character instead of a star:
12.85+#+begin_src lisp
12.86+;;; foo
12.87+(print "H1") ;; just an inline comment
12.88+;;;; bar
12.89+(print "H2")
12.90+;;; baz
12.91+(print "H1")
12.92+#+end_src
12.93+
12.94+A collection of /headings/ is what we call an *Outline* - which is
12.95+also the name of the major-mode utilized for this feature and of
12.96+course - what Org itself is derived from.
12.97+
12.98+** Keywords
12.99+:PROPERTIES:
12.100+:CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
12.101+:END:
12.102+
12.103+The following keywords indicate the state of an element. They often
12.104+appear as the first word in a heading to indicate a [[*Tasks][Task]].
12.105+
12.106+- TBD :: A task to be done at a later date.
12.107+- TODO :: A task yet to be done.
12.108+- FIXME :: Item that needs fixing.
12.109+- WIP :: Work In Progress task.
12.110+- WAIT :: A suspended task.
12.111+- DEAD :: Item that will not be completed.
12.112+- DONE :: Completed task.
12.113+- BUG :: Designate a bug item.
12.114+- IDEA :: Designate an idea item.
12.115+- NOTE :: Designates a note item.
12.116+- DRAFT :: Designates a draft item.
12.117+- COMMENT :: A 'commented' item.
12.118+** Tasks
12.119+Tasks as they are known in Org, usually consist of a heading that
12.120+starts with a [[#2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and
12.121+metadata which are present in our collection of tasks.
12.122+
12.123+Our task management system is roughly a hybrid of two more
12.124+conventional methods: GTD and Agile. For convenience I will describe
12.125+these styles and how I use them separately, but the concepts may be
12.126+spliced differently in real tasks.
12.127+
12.128+- *GTD* \\
12.129+- *Agile* \\
12.130+ It's a dirty word in some tech circles - the dreaded PIs, daily
12.131+ standups, and still nobody knows what's going on, Oh my! Do not
12.132+ worry. For the most part we just borrow the vocabulary.
12.133+
12.134+ Our /Agile/ workflow consists of roadmaps, features (epics/ARTs),
12.135+ issues (user stories), and of course, tasks.
12.136+** Ids
12.137+We reference two different types of identifiers in documentation:
12.138+- UUID :: CUSTOM_ID property
12.139+- User-defined :: ID property
12.140+
12.141+UUIDs on =CUSTOM_ID= property is admittedly a kludge. This is done for
12.142+reasons of portability. We may at some point rename this property
12.143+=UUID= (TBD).
12.144+
12.145+Most of the time these Ids don't add any information for the reader -
12.146+the UUIDs are used to index and graph documents, IDs are for
12.147+convenience.
12.148+** Macros
12.149+:PROPERTIES:
12.150+:CUSTOM_ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e
12.151+:END:
12.152+Several *global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed
12.153+here for convenience.
12.154+
12.155+#+name: ulang-macros
12.156+#+begin_src emacs-lisp :exports both :results replace pp
12.157+ org-export-global-macros
12.158+#+end_src
12.159+
12.160+#+RESULTS: ulang-macros
12.161+: (("header" .
12.162+: "#+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")
12.163+: ("opts" . "#+OPTIONS: $1\n"))
12.164+
12.165+Macros /are not expanded/ in source files - you will see them in the
12.166+form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition
12.167+(in =ulang.el=) in order to use some Org-Mode functions (org-export)
12.168+with our docs.
12.169+
13.1--- a/readme.org Thu Nov 30 20:55:41 2023 -0500
13.2+++ b/readme.org Mon Dec 04 21:09:11 2023 -0500
13.3@@ -5,11 +5,8 @@
13.4 The Compiler Company Documentation)}}}
13.5 #+EXPORT_FILE_NAME: index
13.6
13.7-* [[https://compiler.company/docs/ulang.html][ulang]]
13.8-* [[https://compiler.company/docs/style.html][style]]
13.9-* [[https://compiler.company/docs/tech.html][tech]]
13.10-* [[https://compiler.company/docs/core][core]]
13.11-* [[https://compiler.company/docs/infra][infra]]
13.12-* [[https://compiler.company/docs/business.html][business]]
13.13-* projects
13.14+* [[file:meta][Meta]]
13.15+* [[file:core][Core]]
13.16+* [[file:infra][Infra]]
13.17+* products
13.18 ** [[https://compiler.company/docs/nas-t][NAS-T]]
14.1--- a/style.org Thu Nov 30 20:55:41 2023 -0500
14.2+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
14.3@@ -1,43 +0,0 @@
14.4-{{{header(style,
14.5-Richard Westhaver,
14.6-ellis@rwest.io,
14.7-The Compiler Company Styleguide)}}}
14.8-
14.9-As an organization we maintain a styleguide[fn:1] which lists all of
14.10-the style guidelines we use for our code. If you are contributing to
14.11-one of our projects, you should review and understand the relevant
14.12-sections below.
14.13-
14.14-You should also review the [[file:ulang.org][ulang]] document, which may shine some light
14.15-on code comments and developer docs.
14.16-
14.17-[fn:1] https://google.github.io/styleguide/
14.18-
14.19-* General Programming
14.20-
14.21-- indent-offset = 2
14.22-- max-line-width = 80
14.23-- page-length ~ 32
14.24-- module-length ~ 512
14.25-- file-size ~ 1024
14.26-
14.27-- start every source-file with a header comment
14.28-- use outline headings to organize your program
14.29-- use ulang-comments as needed for referencing bugs, notes, etc.
14.30-- inline documentation should be declarative. your code explains your
14.31- comments for you.
14.32-
14.33-* Common Lisp
14.34-
14.35-- prefer symbol docs to comments
14.36-- use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]]
14.37-- prefer =core= libraries over vendored
14.38-
14.39-** File templates
14.40-* Rust
14.41-- don't make =mod.rs= files
14.42- - use the =foo.rs=, =foo/*= pattern instead
14.43-* Emacs Lisp
14.44-* Org-mode
14.45-* Shell
14.46-* Python
15.1--- a/tech.org Thu Nov 30 20:55:41 2023 -0500
15.2+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
15.3@@ -1,24 +0,0 @@
15.4-{{{header(tech,
15.5-Richard Westhaver,
15.6-ellis@rwest.io,
15.7-The Compiler Company Core Technologies)}}}
15.8-
15.9-* OS
15.10-We primarily support [[https://unix.org][Unix-based]] Operating Systems. Check
15.11-project-specific docs for officially supported targets.
15.12-
15.13-Development and CI is ran on [[https://archlinux.org/][Arch Linux]] (btw).
15.14-* Core
15.15-** [[https://lisp-lang.org/][Lisp]]
15.16-** [[https://www.rust-lang.org/][Rust]]
15.17-** [[https://www.gnu.org/software/emacs/][Emacs]]
15.18-* Libs
15.19-** [[https://rocksdb.org/][rocksdb]]
15.20-** [[https://archlinux.org/pacman/][pacman]]
15.21-** [[https://docs.kernel.org/filesystems/btrfs.html][btrfs]]
15.22-** [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]]
15.23-** [[https://kernel.dk/io_uring.pdf][uring]]
15.24-** [[https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf][blake3]]
15.25-* Extras
15.26-** [[https://ngn.codeberg.page/k][k]]
15.27-** [[https://mlochbaum.github.io/BQN/][BQN]]
16.1--- a/ulang.org Thu Nov 30 20:55:41 2023 -0500
16.2+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
16.3@@ -1,166 +0,0 @@
16.4-{{{header(ulang,
16.5-Richard Westhaver,
16.6-ellis@rwest.io,
16.7-The Universal Language)}}}
16.8-#+OPTIONS: toc:t
16.9-
16.10-This document describes a *U-Language* as described by the late great
16.11-[[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:
16.12-
16.13-#+begin_quote
16.14-Every investigation, including the present one, has to be communicated
16.15-from one person to another by means of language. It is expedient to
16.16-begin our study by calling attention to this obvious fact, by giving a
16.17-name to the language being used, and by being explicit about a few of
16.18-its features. We shall call the language being used the
16.19-U-Language. [...] There would be no point in calling attention to it,
16.20-if it were not for the fact that language is more intimately related
16.21-to our job than of most others.
16.22-#+end_quote
16.23-
16.24-In this document, we will be calling attention to our own language -
16.25-examining it, and describing how it works.
16.26-
16.27-Our job is to solve problems. Hard problems preferred. So we ought to
16.28-pay close attention to the language we use because it brings the
16.29-reader and writer /closer/ to the problem at hand.
16.30-
16.31-For starters, we are primarily concerned with /written languages/ like
16.32-the one you're reading now. We will skip past the obvious details -
16.33-English is our primary form of communication for example. The line you
16.34-are reading currently is a sentence which is part of a paragraph.
16.35-
16.36-There are some non-obvious questions which deserve inquiry though.
16.37-
16.38-- *Who is this for?* \\
16.39- This document is for authors and readers alike. It is a loose
16.40- specification, but also serves as introductory material into our
16.41- communication and design philosophy.
16.42-
16.43-- *What is this for?* \\
16.44- The purpose of this document is to provide a /standard of
16.45- communication/.
16.46-
16.47- All sources we write attempt to conform to this standard but this is
16.48- not strictly enforced. If there is a reason to not comply with a
16.49- rule, it is already broken.
16.50-
16.51-* Org Mode
16.52-:PROPERTIES:
16.53-:CUSTOM_ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1
16.54-:END:
16.55-[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word
16.56-processor.
16.57-
16.58-If you are already familiar with Emacs and Org-Mode, I recommend
16.59-opening the source of this document in Emacs and following along.
16.60-
16.61-If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't
16.62-be getting too deep into tribal hacker knowledge of Emacs.
16.63-
16.64-What's important to know is this: There is /Org Syntax/ and
16.65-/Org-mode/ - these are different things.
16.66-
16.67-Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are
16.68-not concerned about /Org-mode/ the application in this document.
16.69-
16.70-* ulang
16.71-:PROPERTIES:
16.72-:ID: ulang
16.73-:END:
16.74-As the title suggest we refer to our *U-Language* as *ulang*. Each
16.75-section of this document describes a feature.
16.76-** Outlines
16.77-In Org, headings can be summarize as any line starting with a star: =*
16.78-H1=. Headings can be nested or 'demoted' by prepending another star:
16.79-=** H2=.
16.80-
16.81-This is a useful pattern which we apply outside of Org - most commonly
16.82-in our code comments.
16.83-
16.84-In our source code, we use the comment character instead of a star:
16.85-#+begin_src lisp
16.86-;;; foo
16.87-(print "H1") ;; just an inline comment
16.88-;;;; bar
16.89-(print "H2")
16.90-;;; baz
16.91-(print "H1")
16.92-#+end_src
16.93-
16.94-A collection of /headings/ is what we call an *Outline* - which is
16.95-also the name of the major-mode utilized for this feature and of
16.96-course - what Org itself is derived from.
16.97-
16.98-** Keywords
16.99-:PROPERTIES:
16.100-:CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
16.101-:END:
16.102-
16.103-The following keywords indicate the state of an element. They often
16.104-appear as the first word in a heading to indicate a [[*Tasks][Task]].
16.105-
16.106-- TBD :: A task to be done at a later date.
16.107-- TODO :: A task yet to be done.
16.108-- FIXME :: Item that needs fixing.
16.109-- WIP :: Work In Progress task.
16.110-- WAIT :: A suspended task.
16.111-- DEAD :: Item that will not be completed.
16.112-- DONE :: Completed task.
16.113-- BUG :: Designate a bug item.
16.114-- IDEA :: Designate an idea item.
16.115-- NOTE :: Designates a note item.
16.116-- DRAFT :: Designates a draft item.
16.117-- COMMENT :: A 'commented' item.
16.118-** Tasks
16.119-Tasks as they are known in Org, usually consist of a heading that
16.120-starts with a [[#2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and
16.121-metadata which are present in our collection of tasks.
16.122-
16.123-Our task management system is roughly a hybrid of two more
16.124-conventional methods: GTD and Agile. For convenience I will describe
16.125-these styles and how I use them separately, but the concepts may be
16.126-spliced differently in real tasks.
16.127-
16.128-- *GTD* \\
16.129-- *Agile* \\
16.130- It's a dirty word in some tech circles - the dreaded PIs, daily
16.131- standups, and still nobody knows what's going on, Oh my! Do not
16.132- worry. For the most part we just borrow the vocabulary.
16.133-
16.134- Our /Agile/ workflow consists of roadmaps, features (epics/ARTs),
16.135- issues (user stories), and of course, tasks.
16.136-** Ids
16.137-We reference two different types of identifiers in documentation:
16.138-- UUID :: CUSTOM_ID property
16.139-- User-defined :: ID property
16.140-
16.141-UUIDs on =CUSTOM_ID= property is admittedly a kludge. This is done for
16.142-reasons of portability. We may at some point rename this property
16.143-=UUID= (TBD).
16.144-
16.145-Most of the time these Ids don't add any information for the reader -
16.146-the UUIDs are used to index and graph documents, IDs are for
16.147-convenience.
16.148-** Macros
16.149-:PROPERTIES:
16.150-:CUSTOM_ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e
16.151-:END:
16.152-Several *global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed
16.153-here for convenience.
16.154-
16.155-#+name: ulang-macros
16.156-#+begin_src emacs-lisp :exports both :results replace pp
16.157- org-export-global-macros
16.158-#+end_src
16.159-
16.160-#+RESULTS: ulang-macros
16.161-: (("header" .
16.162-: "#+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")
16.163-: ("opts" . "#+OPTIONS: $1\n"))
16.164-
16.165-Macros /are not expanded/ in source files - you will see them in the
16.166-form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition
16.167-(in =ulang.el=) in order to use some Org-Mode functions (org-export)
16.168-with our docs.
16.169-
