1.1--- a/ulang.org Wed Sep 04 16:59:32 2024 -0400
1.2+++ b/ulang.org Sat Sep 07 22:38:02 2024 -0400
1.3@@ -6,8 +6,15 @@
1.4 :PROPERTIES:
1.5 :ID: e63d129f-9024-4cd8-9e2c-77f4bc614663
1.6 :END:
1.7-This document describes a *U-Language* as described by the late great
1.8-[[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:
1.9+
1.10+This document is for contributors and curious readers. It is a loose
1.11+specification which describes the fundamental rules of how we write in
1.12+prose, documentation, and other contexts.
1.13+
1.14+All sources we write attempt to comply to this specification but it is
1.15+never /strictly/ enforced. If there is a reason to not comply with a
1.16+rule, it is already broken.
1.17+
1.18 #+begin_quote
1.19 Every investigation, including the present one, has to be communicated
1.20 from one person to another by means of language. It is expedient to
1.21@@ -16,27 +23,20 @@
1.22 its features. We shall call the language being used the
1.23 U-Language. [...] There would be no point in calling attention to it,
1.24 if it were not for the fact that language is more intimately related
1.25-to our job than of most others.
1.26+to our job than of most others. -- [[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]
1.27 #+end_quote
1.28
1.29-In this document, we will be calling attention to our own language -
1.30-examining it, and describing how it works.
1.31+In this document, we will be calling attention to our own
1.32+language - examining it, and describing how it works.
1.33
1.34 Our job is to solve problems. Hard problems preferred. So we ought to
1.35 pay close attention to the language we use because it brings the
1.36 reader and writer /closer/ to the problem at hand.
1.37
1.38-For starters, we are primarily concerned with /written languages/ like
1.39-the one you're reading now. We will skip past the obvious details -
1.40-English is our primary form of communication for example. The line you
1.41-are reading currently is a sentence which is part of a paragraph.
1.42-
1.43-- This document is for authors and curious readers. It is a loose
1.44- specification, but also serves as introductory material into our
1.45- communication style and design philosophy.
1.46-- All sources we write attempt to comply to this standard but it is
1.47- not strictly enforced. If there is a reason to not comply with a
1.48- rule, it is already broken.
1.49+We are primarily concerned with /written languages/ like the one
1.50+you're reading now. We will skip past the obvious details - English is
1.51+our primary form of communication for example. The line you are
1.52+reading currently is a sentence which is part of a paragraph.
1.53
1.54 ** Org Mode
1.55 :PROPERTIES:
1.56@@ -57,14 +57,16 @@
1.57 :ID: 236227a5-b30c-4548-8cad-360428d74d67
1.58 :END:
1.59 Our *U-Language* is colloquially termed *ulang*. Each section of this
1.60-document describes a feature of our ulang.
1.61+document describes an Org syntax component and how it is used in our
1.62+writing.
1.63 ** Emphasis
1.64 :PROPERTIES:
1.65 :ID: 88bf1177-b5b7-4945-8bdc-5229803e617e
1.66 :END:
1.67-We derive all text emphasis syntax for rich contents from [[https://orgmode.org/manual/Emphasis-and-Monospace.html][Org Mode]].
1.68+[[https://orgmode.org/manual/Emphasis-and-Monospace.html][Text Emphasis]] in Org covers the range you would expect from any other
1.69+markup:
1.70 #+name: org-emphasis
1.71-#+begin_src org
1.72+#+begin_src org :results replace
1.73 - *bold*
1.74 - /italic/
1.75 - _underlined_
1.76@@ -72,23 +74,49 @@
1.77 - ~code~
1.78 - +strike-through+
1.79 #+end_src
1.80+
1.81+#+RESULTS: org-emphasis
1.82 - *bold*
1.83 - /italic/
1.84 - _underlined_
1.85 - =verbatim=
1.86 - ~code~
1.87 - +strike-through+
1.88-
1.89-Text emphasis markers may be embedded in any syntax as long as it does
1.90-not cause any conflicts with the host language.
1.91+\
1.92+- Text emphasis markers /may/ appear in code comments as long as they do
1.93+ not cause any conflicts with the host language, although they /should/
1.94+ be restricted to the =Commentary= section.
1.95+- ~code~ may sometimes be written instead with =verbatim= emphasis -
1.96+ the distinction is only important for specific export backends which
1.97+ support it - see [[https://emacs.stackexchange.com/a/77822][this thread]] for details.
1.98 ** Links
1.99 :PROPERTIES:
1.100 :ID: 7ecaec5d-c656-44e1-8fad-185915655cee
1.101 :END:
1.102-*** Link Types
1.103+Org [[https://orgmode.org/guide/Hyperlinks.html][Links]] are wrapped in brackets like so:
1.104+
1.105+#+name: org-links
1.106+#+begin_src org
1.107+ [[LINK][DESCRIPTION]]
1.108+ ;; or without description
1.109+ [[LINK]]
1.110+#+end_src
1.111+
1.112+- LINK is a URI like https://google.com
1.113+- DESCRIPTION is optional
1.114+
1.115+*** Internal Links
1.116+:PROPERTIES:
1.117+:ID: a867de82-8558-4277-b9d6-b5d3226f73d1
1.118+:END:
1.119+[[https://orgmode.org/manual/Internal-Links.html][Internal Links]]
1.120+*** External Links
1.121 :PROPERTIES:
1.122 :ID: 6aedc026-36d0-4763-adc8-8ae1a79f1b3e
1.123 :END:
1.124+Org has built-in support for many different types of [[https://orgmode.org/guide/Hyperlinks.html#External-Links-1][External Links]],
1.125+which are URL-like locators. We also define some custom link types
1.126+which are used throughout our documentation /and/ code.
1.127
1.128 ** Headings
1.129 :PROPERTIES:
1.130@@ -131,7 +159,7 @@
1.131 println!("H1");
1.132 #+end_src
1.133
1.134-** Keywords
1.135+** Todo Keywords
1.136 :PROPERTIES:
1.137 :ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
1.138 :END:
1.139@@ -140,6 +168,8 @@
1.140 Item]], but may also be [[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a variety of stateful item
1.141 types beyond just simple tasks.
1.142
1.143+We /do not/ specify any
1.144+
1.145 The following keywords form the simple set of task states.
1.146
1.147 - TBD
1.148@@ -211,13 +241,139 @@
1.149 :PROPERTIES:
1.150 :ID: 3944c851-e46c-4d75-b8f5-07b5c052177a
1.151 :END:
1.152-We reference two different types of identifiers in documentation:
1.153-- UUID :: =ID= property
1.154-- User-defined :: =CUSTOM_ID= property
1.155+Org supports two built-in identifier properties:
1.156+- ID :: Unique, machine-generated
1.157+- CUSTOM_ID :: User-defined
1.158+
1.159+These IDs don't add any information for the reader - the IDs are used
1.160+to index and associate headings. All headings are assigned an ID
1.161+automatically which should never be changed.
1.162+
1.163+CUSTOM_IDs are for convenience and extensions, but are rarely
1.164+necessary given the many ways of identifying a headline.
1.165+** File Keywords
1.166+:PROPERTIES:
1.167+:ID: 27141c7a-e903-4909-890f-b496716a48ba
1.168+:END:
1.169+File keywords, also known as [[https://orgmode.org/manual/In_002dbuffer-Settings.html][In-Buffer Settings]] are similar to
1.170+properties in the sense that they are key/value pairs, but they only
1.171+appear at the top of a file before any content and use a different
1.172+syntax.
1.173+
1.174+#+begin_src org
1.175+ ,#+title: some file title
1.176+ ,#+author: some user
1.177+ ,#+PROPERTY DESCRIPTION assigning a property via file keyword
1.178+ some content
1.179+ ,* a headline
1.180+ :PROPERTIES:
1.181+ :DESCRIPTION: just a property, not a file keyword
1.182+ :END:
1.183+#+end_src
1.184+
1.185+** Tables
1.186+:PROPERTIES:
1.187+:ID: be4c4c52-4353-45df-b2ab-1e72f392008d
1.188+:END:
1.189+Org [[https://orgmode.org/manual/Tables.html][Tables]] offer some pretty advanced spreadsheet capabilities which
1.190+we won't delve into here. Plain tables can be identified in documents by lines
1.191+starting with the =|= character:
1.192+#+begin_src org :results replace
1.193+ | col1 | col2 | col3 |
1.194+ |------+------+------|
1.195+ | 1 | foo | bar |
1.196+#+end_src
1.197+
1.198+#+RESULTS:
1.199+| col1 | col2 | col3 |
1.200+|------+------+------|
1.201+| 1 | foo | bar |
1.202+
1.203+** Blocks
1.204+:PROPERTIES:
1.205+:ID: d5a09bc6-07de-4812-ab2e-f5ead1e0d8a7
1.206+:END:
1.207+Org [[https://orgmode.org/manual/Blocks.html][Blocks]] consist of a body wrapped in a pair of lines which look
1.208+like [[id:27141c7a-e903-4909-890f-b496716a48ba][File Keywords]] prepended with =BEGIN_= and =END_=.
1.209+
1.210+Simple blocks such as =example= and =center= only have a special
1.211+meaning during publishing:
1.212+#+begin_src org :results replace drawer
1.213+ ,#+begin_example
1.214+ this is an example block
1.215+ ,#+end_example
1.216+
1.217+ ,#+begin_center
1.218+ this is a centered block
1.219+ ,#+end_center
1.220+#+end_src
1.221
1.222-Most of the time these IDs don't add any information for the reader -
1.223-the UUIDs are used to index and graph documents, CUSTOM_IDs are for
1.224-convenience and extensions, but are rarely necessary given the many
1.225-ways of identifying a headline.
1.226+#+RESULTS:
1.227+:results:
1.228+#+begin_example
1.229+this is an example block
1.230+#+end_example
1.231+
1.232+#+begin_center
1.233+this is a centered block
1.234+#+end_center
1.235+:end:
1.236+*** Code Blocks
1.237+:PROPERTIES:
1.238+:ID: 0784d230-95b0-4135-a52f-6be4e2d5d80a
1.239+:END:
1.240+[[https://orgmode.org/manual/Working-with-Source-Code.html][Code Blocks]] are used to embed source code into a document. They always
1.241+start with =#+BEGIN_SRC= and end with =#+END_SRC=:
1.242+
1.243+#+begin_src org :results replace drawer
1.244+ ,#+begin_src emacs-lisp
1.245+ (message "an emacs-lisp code block inside an org document")
1.246+ ,#+end_src
1.247+#+end_src
1.248+
1.249+#+RESULTS:
1.250+:results:
1.251+#+begin_src emacs-lisp
1.252+ (message "an emacs-lisp code block inside an org document")
1.253+#+end_src
1.254+:end:
1.255+
1.256+You can embed virtually any type of source code in side a code block,
1.257+execute it in-place, and control how both the source code and results
1.258+are presented in the document. Source code blocks may also be
1.259+collected in a [[file:babel.org][Library of Babel]] and re-used across many documents.
1.260
1.261-All headings are assigned an ID automatically and are never changed.
1.262+*** Dynamic Blocks
1.263+:PROPERTIES:
1.264+:ID: 8898387c-2c84-4f56-80ee-d03daebd0990
1.265+:END:
1.266+[[https://orgmode.org/manual/Dynamic-Blocks.html][Dynamic Blocks]] as the name implies are blocks with contents that are
1.267+dynamically updated. These blocks always begin with =#+BEGIN:=
1.268+followed by a space, the name of the dynamic block and any parameter
1.269+values, and end with =#+END:=. The dynamic block name is taken from
1.270+the name of a function which matches =org-dblock-write:NAME=. This
1.271+function is called with the parameter values and replaces the body of
1.272+the block.
1.273+
1.274+The only built-in dynamic block is the =clocktable=:
1.275+#+begin_src org :results replace drawer
1.276+ ,#+BEGIN: clocktable
1.277+ ,#+CAPTION: Clock summary at [2024-09-06 Fri 15:23]
1.278+ | Headline | Time |
1.279+ |--------------+--------|
1.280+ | *Total time* | *0:00* |
1.281+ ,#+END:
1.282+#+end_src
1.283+
1.284+#+RESULTS:
1.285+:results:
1.286+#+BEGIN: clocktable
1.287+#+CAPTION: Clock summary at [2024-09-06 Fri 15:23]
1.288+| Headline | Time |
1.289+|--------------+--------|
1.290+| *Total time* | *0:00* |
1.291+#+END:
1.292+:end:
1.293+
1.294+Dynamic blocks are designed for user extension and are a powerful tool
1.295+to programatically summarize information.
