changelog shortlog graph tags branches changeset files revisions annotate raw help

Mercurial > org > docs / meta/ulang.org

changeset 22: 889970442a12
parent: 9a3d82d9072a
child: c363ae4d1aac
author: Richard Westhaver <ellis@rwest.io>
date: Mon, 27 May 2024 22:04:39 -0400
permissions: -rw-r--r--
description: docs bump 
     1 #+title: Universal Languages
     2 #+author: Richard Westhaver
     3 #+email: ellis@rwest.io
     4 #+OPTIONS: toc:t
     5 
     6 This document describes a *U-Language* as described by the late great
     7 [[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:
     8 
     9 #+begin_quote
    10 Every investigation, including the present one, has to be communicated
    11 from one person to another by means of language. It is expedient to
    12 begin our study by calling attention to this obvious fact, by giving a
    13 name to the language being used, and by being explicit about a few of
    14 its features. We shall call the language being used the
    15 U-Language. [...] There would be no point in calling attention to it,
    16 if it were not for the fact that language is more intimately related
    17 to our job than of most others.
    18 #+end_quote
    19 
    20 In this document, we will be calling attention to our own language -
    21 examining it, and describing how it works.
    22 
    23 Our job is to solve problems. Hard problems preferred. So we ought to
    24 pay close attention to the language we use because it brings the
    25 reader and writer /closer/ to the problem at hand.
    26 
    27 For starters, we are primarily concerned with /written languages/ like
    28 the one you're reading now. We will skip past the obvious details -
    29 English is our primary form of communication for example. The line you
    30 are reading currently is a sentence which is part of a paragraph.
    31 
    32 There are some non-obvious questions which deserve inquiry though.
    33 
    34 - *Who is this for?* \\
    35   This document is for authors and readers alike. It is a loose
    36   specification, but also serves as introductory material into our
    37   communication and design philosophy.
    38   
    39 - *What is this for?* \\
    40   The purpose of this document is to provide a /standard of
    41   communication/.
    42 
    43   All sources we write attempt to conform to this standard but this is
    44   not strictly enforced. If there is a reason to not comply with a
    45   rule, it is already broken.
    46 
    47 * Org Mode
    48 :PROPERTIES:
    49 :CUSTOM_ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1
    50 :END:
    51 [[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word
    52 processor.
    53 
    54 If you are already familiar with Emacs and Org-Mode, I recommend
    55 opening the source of this document in Emacs and following along.
    56 
    57 If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't
    58 be getting too deep into tribal hacker knowledge of Emacs.
    59 
    60 What's important to know is this: There is /Org Syntax/ and
    61 /Org-mode/ - these are different things.
    62 
    63 Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are
    64 not concerned about /Org-mode/ the application in this document.
    65 
    66 * ulang
    67 :PROPERTIES:
    68 :ID: ulang
    69 :END:
    70 As the title suggest we refer to our *U-Language* as *ulang*. Each
    71 section of this document describes a feature.
    72 ** Outlines
    73 In Org, headings can be summarize as any line starting with a star: =*
    74 H1=. Headings can be nested or 'demoted' by prepending another star:
    75 =** H2=.
    76 
    77 This is a useful pattern which we apply outside of Org - most commonly
    78 in our code comments.
    79 
    80 In our source code, we use the comment character instead of a star:
    81 #+begin_src lisp
    82 ;;; foo
    83 (print "H1") ;; just an inline comment
    84 ;;;; bar
    85 (print "H2")
    86 ;;; baz
    87 (print "H1")
    88 #+end_src
    89 
    90 A collection of /headings/ is what we call an *Outline* - which is
    91 also the name of the major-mode utilized for this feature and of
    92 course - what Org itself is derived from.
    93 
    94 ** Keywords
    95 :PROPERTIES:
    96 :CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
    97 :END:
    98 
    99 The following keywords indicate the state of an element. They often
   100 appear as the first word in a heading to indicate a [[*Tasks][Task]].
   101 
   102 - TBD :: A task to be done at a later date.
   103 - TODO :: A task yet to be done.
   104 - FIXME :: Item that needs fixing.
   105 - WIP :: Work In Progress task.
   106 - WAIT :: A suspended task.
   107 - DEAD :: Item that will not be completed.
   108 - DONE :: Completed task.
   109 - BUG :: Designate a bug item.
   110 - IDEA :: Designate an idea item.
   111 - NOTE :: Designates a note item.
   112 - DRAFT :: Designates a draft item.
   113 - COMMENT :: A 'commented' item.
   114 ** Tasks
   115 Tasks as they are known in Org, usually consist of a heading that
   116 starts with a [[#2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and
   117 metadata which are present in our collection of tasks.
   118 
   119 Our task management system is roughly a hybrid of two more
   120 conventional methods: GTD and Agile. For convenience I will describe
   121 these styles and how I use them separately, but the concepts may be
   122 spliced differently in real tasks.
   123 
   124 - *GTD* \\
   125 - *Agile* \\
   126   It's a dirty word in some tech circles - the dreaded PIs, daily
   127   standups, and still nobody knows what's going on, Oh my! Do not
   128   worry. For the most part we just borrow the vocabulary.
   129 
   130   Our /Agile/ workflow consists of roadmaps, features (epics/ARTs),
   131   issues (user stories), and of course, tasks.
   132 ** Ids
   133 We reference two different types of identifiers in documentation:
   134 - UUID :: CUSTOM_ID property
   135 - User-defined :: ID property
   136 
   137 UUIDs on =CUSTOM_ID= property is admittedly a kludge. This is done for
   138 reasons of portability. We may at some point rename this property
   139 =UUID= (TBD).
   140 
   141 Most of the time these Ids don't add any information for the reader -
   142 the UUIDs are used to index and graph documents, IDs are for
   143 convenience.
   144 ** Macros
   145 :PROPERTIES:
   146 :CUSTOM_ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e
   147 :END:
   148 Several *global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed
   149 here for convenience.
   150 
   151 #+name: ulang-macros
   152 #+begin_src emacs-lisp :exports both :results replace pp
   153   org-export-global-macros
   154 #+end_src
   155 
   156 #+RESULTS: ulang-macros
   157 : (("header" .
   158 :   "#+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")
   159 :  ("opts" . "#+OPTIONS: $1\n"))
   160 
   161 Macros /are not expanded/ in source files - you will see them in the
   162 form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition
   163 (in =ulang.el=) in order to use some Org-Mode functions (org-export)
   164 with our docs.
   165