1.1--- a/ulang.org Sun Aug 18 22:16:12 2024 -0400
1.2+++ b/ulang.org Sun Aug 25 00:15:40 2024 -0400
1.3@@ -3,8 +3,6 @@
1.4 #+email: ellis@rwest.io
1.5 #+setupfile: ../clean.theme
1.6 #+infojs_opt: toc:nil home:https://compiler.company up:./ view:showall
1.7-#+print_glossary: :level 0 :consume yes :all yes :only-contents no
1.8-#+glossary_sources: glossary.org
1.9 * Introduction
1.10 :PROPERTIES:
1.11 :ID: e63d129f-9024-4cd8-9e2c-77f4bc614663
1.12@@ -36,7 +34,7 @@
1.13
1.14 - This document is for authors and curious readers. It is a loose
1.15 specification, but also serves as introductory material into our
1.16- communication and design philosophy.
1.17+ communication style and design philosophy.
1.18 - All sources we write attempt to comply to this standard but it is
1.19 not strictly enforced. If there is a reason to not comply with a
1.20 rule, it is already broken.
1.21@@ -54,39 +52,13 @@
1.22 If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't
1.23 be getting too deep into tribal hacker knowledge of Emacs.
1.24
1.25-What's important to know is this: There is /Org Syntax/ and
1.26-/Org-mode/ - these are different things.
1.27-
1.28-Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are
1.29-not concerned about /Org-mode/ the application in this document.
1.30-
1.31-For the remainder of this document, we assume basic knowledge of Org
1.32-Mode.
1.33-
1.34 * ulang
1.35 :PROPERTIES:
1.36 :CUSTOM_ID: ulang
1.37 :ID: 236227a5-b30c-4548-8cad-360428d74d67
1.38 :END:
1.39 Our *U-Language* is colloquially termed *ulang*. Each section of this
1.40-document describes a feature or property of our ulang.
1.41-** Glossary
1.42-:PROPERTIES:
1.43-:ID: cf237775-6e69-4554-999d-7c9cc4445f77
1.44-:END:
1.45-*** Terms
1.46-:PROPERTIES:
1.47-:ID: e808e546-65fb-4470-a21f-27eb9a7b50ee
1.48-:END:
1.49-*** Acronyms
1.50-:PROPERTIES:
1.51-:ID: c04c4524-a3d6-495d-98be-8ca291c5db08
1.52-:END:
1.53-** Dictionary
1.54-:PROPERTIES:
1.55-:ID: 689826b6-0df4-4f0e-944a-b96fa4f8599e
1.56-:END:
1.57-compiler.company:2628
1.58+document describes a feature of our ulang.
1.59 ** Emphasis
1.60 :PROPERTIES:
1.61 :ID: 88bf1177-b5b7-4945-8bdc-5229803e617e
1.62@@ -110,6 +82,15 @@
1.63
1.64 Text emphasis markers may be embedded in any syntax as long as it does
1.65 not cause any conflicts with the host language.
1.66+** Links
1.67+:PROPERTIES:
1.68+:ID: 7ecaec5d-c656-44e1-8fad-185915655cee
1.69+:END:
1.70+*** Link Types
1.71+:PROPERTIES:
1.72+:ID: 6aedc026-36d0-4763-adc8-8ae1a79f1b3e
1.73+:END:
1.74+
1.75 ** Headings
1.76 :PROPERTIES:
1.77 :ID: ed035298-f7fa-4726-ad58-2d542323bb61
1.78@@ -151,85 +132,33 @@
1.79 println!("H1");
1.80 #+end_src
1.81
1.82-** Outlines
1.83-:PROPERTIES:
1.84-:ID: 7b4d3229-d85f-4464-b9d0-6beccb1f7b2e
1.85-:END:
1.86-A collection of /headings/ is what we call an *Outline* - which is
1.87-also the name of the major-mode utilized for this feature and of
1.88-course - what Org itself is derived from.
1.89 ** Keywords
1.90 :PROPERTIES:
1.91 :ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
1.92 :END:
1.93
1.94-In Org, TODO keywords are used to key track of the state of a [[https://orgmode.org/manual/TODO-Items.html][TODO
1.95-Item]].
1.96+TODO keywords are often used to keep track of the state of a [[https://orgmode.org/manual/TODO-Items.html][TODO
1.97+Item]], but may also be [[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a variety of stateful item
1.98+types beyond just simple tasks.
1.99
1.100-In ulang, they are used for this purpose and [[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a
1.101-variety of stateful item types beyond just tasks - for example =NOTE=
1.102-and =PROJECT=.
1.103-
1.104-The following keywords indicate the state of a heading element. They
1.105-often appear as the first word in a heading.
1.106+The following keywords form the simple set of task states.
1.107
1.108-- TBD :: A task to be done at a later date.
1.109-- TODO :: A task yet to be done.
1.110-- FIXME :: Item that needs fixing.
1.111-- WIP :: Work In Progress task.
1.112-- WAIT :: A suspended task.
1.113-- DEAD :: Item that will not be completed.
1.114-- DONE :: Completed task.
1.115-- BUG :: Designate a bug item.
1.116-- IDEA :: Designate an idea item.
1.117-- NOTE :: Designates a note item.
1.118-- DRAFT :: Designates a draft item.
1.119-- COMMENT :: A 'commented' item.
1.120-- PROJECT :: Designates a project item containing a sequence of tasks.
1.121+- TBD
1.122+- TODO
1.123+- WIP
1.124+- HOLD
1.125+- WAIT
1.126+- DONE
1.127+- NOPE
1.128
1.129 #+begin_src org
1.130 ,* PROJECT project
1.131 ,** DONE foo
1.132 ,** TODO bar
1.133+ ,** TBD baz
1.134+ ,** WIP test foo
1.135 #+end_src
1.136
1.137-** COMMENT Tasks
1.138-:PROPERTIES:
1.139-:ID: 0f4c0afd-a774-4b98-900b-1ab44f9fd2ef
1.140-:END:
1.141-Tasks as they are known in Org, usually consist of a heading that
1.142-starts with a [[id:2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and
1.143-metadata which are present in our collection of tasks.
1.144-
1.145-Our task management system is roughly a hybrid of two more
1.146-conventional methods: GTD and Agile. For convenience I will describe
1.147-these styles and how I use them separately, but the concepts may be
1.148-spliced differently in real tasks.
1.149-
1.150-- *GTD* \\
1.151-- *Agile* \\
1.152- It's a dirty word in some tech circles - the dreaded PIs, daily
1.153- standups, and still nobody knows what's going on, Oh my! Do not
1.154- worry. For the most part we just borrow the vocabulary.
1.155-
1.156- Our /Agile/ workflow consists of roadmaps, features (epics/ARTs),
1.157- issues (user stories), and of course, tasks.
1.158-** Properties
1.159-:PROPERTIES:
1.160-:ID: 174a993b-a5dc-4324-b4f8-dda8101a55b7
1.161-:END:
1.162-*** IDs
1.163-:PROPERTIES:
1.164-:ID: 3944c851-e46c-4d75-b8f5-07b5c052177a
1.165-:END:
1.166-We reference two different types of identifiers in documentation:
1.167-- UUID :: =ID= property
1.168-- User-defined :: =CUSTOM_ID= property
1.169-
1.170-Most of the time these IDs don't add any information for the reader -
1.171-the UUIDs are used to index and graph documents, CUSTOM_IDs are for
1.172-convenience but are rarely necessary given the many ways of
1.173-identifying a headline.
1.174 ** Tags
1.175 :PROPERTIES:
1.176 :ID: a7ae1b2a-559e-46e9-8cab-33e39a218288
1.177@@ -240,12 +169,16 @@
1.178 A tag can be any text without newlines, although it is recommended to
1.179 treat them as unique identifiers and usage of whitespace is
1.180 discouraged (but not disallowed).
1.181-*** Tag Types
1.182+
1.183+#+begin_src org
1.184+ ,* foobar :tag1:tag2:@home:!today
1.185+#+end_src
1.186+*** Tag Prefixes
1.187 :PROPERTIES:
1.188 :ID: b686dbc5-3505-49d7-b66a-0772bcf1a726
1.189 :END:
1.190-Tags may be prefixed with one of the following characters, indicating
1.191-a special tag type:
1.192+Some of ourtags are prefixed with a character which indicates a
1.193+special tag category:
1.194 - =@= :: location-tag \\
1.195 A /location tag/ refers to some context-dependent named point in
1.196 space, such as a user's home address, a popular fast food
1.197@@ -260,15 +193,32 @@
1.198 - =#= :: anchor-tag \\
1.199 An /anchor tag/ implies a link to the object identified by some [[id:3944c851-e46c-4d75-b8f5-07b5c052177a][ID]].
1.200 - =#readme=, =#a7ae1b2a-559e-46e9-8cab-33e39a218288=, =#custom-id=
1.201-*** Tag Lists
1.202-:PROPERTIES:
1.203-:ID: 805862be-ba2b-4288-a2e3-791c0aa3802f
1.204-:END:
1.205-** Links
1.206+** Properties
1.207 :PROPERTIES:
1.208-:ID: 7ecaec5d-c656-44e1-8fad-185915655cee
1.209+:ID: 174a993b-a5dc-4324-b4f8-dda8101a55b7
1.210 :END:
1.211-*** Link Types
1.212+[[https://orgmode.org/manual/Properties-and-Columns.html][Properties]] are key:value pairs which are associated with a heading or
1.213+file and stored in a dedicated [[https://orgmode.org/manual/Drawers.html][Drawer]].
1.214+
1.215+#+begin_src org
1.216+ ,* WIP do stuff :@lab:
1.217+ :PROPERTIES:
1.218+ :CREATED: <2024-08-24 Sat 19:09>
1.219+ :ID: 62da3982-7a83-4b27-ab7e-55949fd3e2a3
1.220+ :EFFORT: 24:00
1.221+ :END:
1.222+#+end_src
1.223+*** ID
1.224 :PROPERTIES:
1.225-:ID: 6aedc026-36d0-4763-adc8-8ae1a79f1b3e
1.226+:ID: 3944c851-e46c-4d75-b8f5-07b5c052177a
1.227 :END:
1.228+We reference two different types of identifiers in documentation:
1.229+- UUID :: =ID= property
1.230+- User-defined :: =CUSTOM_ID= property
1.231+
1.232+Most of the time these IDs don't add any information for the reader -
1.233+the UUIDs are used to index and graph documents, CUSTOM_IDs are for
1.234+convenience and extensions, but are rarely necessary given the many
1.235+ways of identifying a headline.
1.236+
1.237+All headings are assigned an ID automatically and are never changed.
