changelog shortlog graph tags branches changeset files revisions annotate raw help

Mercurial > org > docs / meta/ulang.org

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