Mercurial > org > meta / ulang.org

 #+title: Universal Language
 #+author: Richard Westhaver
 #+email: ellis@rwest.io
 #+setupfile: ../clean.theme
 #+infojs_opt: toc:nil home:https://compiler.company up:./ view:showall
 #+print_glossary: :level 0 :consume yes :all yes :only-contents no
 #+glossary_sources: glossary.org
 * Introduction
 :PROPERTIES:
 :ID:       e63d129f-9024-4cd8-9e2c-77f4bc614663
 :END:
 This document describes a *U-Language* as described by the late great
 [[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:
 #+begin_quote
 Every investigation, including the present one, has to be communicated
 from one person to another by means of language. It is expedient to
 begin our study by calling attention to this obvious fact, by giving a
 name to the language being used, and by being explicit about a few of
 its features. We shall call the language being used the
 U-Language. [...] There would be no point in calling attention to it,
 if it were not for the fact that language is more intimately related
 to our job than of most others.
 #+end_quote
 
 In this document, we will be calling attention to our own language -
 examining it, and describing how it works.
 
 Our job is to solve problems. Hard problems preferred. So we ought to
 pay close attention to the language we use because it brings the
 reader and writer /closer/ to the problem at hand.
 
 For starters, we are primarily concerned with /written languages/ like
 the one you're reading now. We will skip past the obvious details -
 English is our primary form of communication for example. The line you
 are reading currently is a sentence which is part of a paragraph.
 
 - This document is for authors and curious readers. It is a loose
   specification, but also serves as introductory material into our
   communication and design philosophy.
 - All sources we write attempt to comply to this standard but it is
   not strictly enforced. If there is a reason to not comply with a
   rule, it is already broken.
 
 ** Org Mode
 :PROPERTIES:
 :ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1
 :END:
 [[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word
 processor.
 
 If you are already familiar with Emacs and Org-Mode, I recommend
 opening the source of this document in Emacs and following along.
 
 If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't
 be getting too deep into tribal hacker knowledge of Emacs.
 
 What's important to know is this: There is /Org Syntax/ and
 /Org-mode/ - these are different things.
 
 Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are
 not concerned about /Org-mode/ the application in this document.
 
 For the remainder of this document, we assume basic knowledge of Org
 Mode.
 
 * ulang
 :PROPERTIES:
 :CUSTOM_ID: ulang
 :ID:       236227a5-b30c-4548-8cad-360428d74d67
 :END:
 Our *U-Language* is colloquially termed *ulang*. Each section of this
 document describes a feature or property of our ulang.
 ** Glossary
 *** Terms
 *** Acronyms
 ** Dictionary
 compiler.company:2628
 ** Emphasis
 :PROPERTIES:
 :ID:       88bf1177-b5b7-4945-8bdc-5229803e617e
 :END:
 We derive all text emphasis syntax for rich contents from [[https://orgmode.org/manual/Emphasis-and-Monospace.html][Org Mode]].
 #+name: org-emphasis
 #+begin_src org
   - *bold*
   - /italic/
   - _underlined_
   - =verbatim=
   - ~code~
   - +strike-through+
 #+end_src
 - *bold*
 - /italic/
 - _underlined_
 - =verbatim=
 - ~code~
 - +strike-through+
 
 Text emphasis markers may be embedded in any syntax as long as it does
 not cause any conflicts with the host language.
 ** Headings
 :PROPERTIES:
 :ID:       ed035298-f7fa-4726-ad58-2d542323bb61
 :END:
 In Org, headings can be summarize as any line starting with a star: =*
 H1=. Headings can be nested or 'demoted' by prepending another star:
 =** H2=.
 
 #+name: org-headings
 #+begin_src org
 ,* H1
 ,** H2
 ,*** H3
 ,** H2
 ,* H1
 #+end_src
 
 This is a useful pattern which we apply outside of Org - most commonly
 in our code comments.
 
 In our source code, we use the comment character instead of a star:
 #+name: lisp-headings
 #+begin_src lisp
 ;;; foo
 (print "H1") ;; just an inline comment
 ;;;; bar
 (print "H2")
 ;;; baz
 (print "H1")
 #+end_src
 
 #+name: rust-headings
 #+begin_src rust
   /// foo
   println!("H1");
   //// bar
   println!("H2");
   /// baz
   println!("H1");
 #+end_src
 
 ** Outlines
 :PROPERTIES:
 :ID:       7b4d3229-d85f-4464-b9d0-6beccb1f7b2e
 :END:
 A collection of /headings/ is what we call an *Outline* - which is
 also the name of the major-mode utilized for this feature and of
 course - what Org itself is derived from.
 ** Keywords
 :PROPERTIES:
 :ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
 :END:
 
 In Org, TODO keywords are used to key track of the state of a [[https://orgmode.org/manual/TODO-Items.html][TODO
 Item]].
 
 In ulang, they are used for this purpose and [[https://orgmode.org/manual/TODO-Extensions.html][extended]] to support a
 variety of stateful item types beyond just tasks - for example =NOTE=
 and =PROJECT=.
 
 The following keywords indicate the state of a heading element. They
 often appear as the first word in a heading.
 
 - TBD :: A task to be done at a later date.
 - TODO :: A task yet to be done.
 - FIXME :: Item that needs fixing.
 - WIP :: Work In Progress task.
 - WAIT :: A suspended task.
 - DEAD :: Item that will not be completed.
 - DONE :: Completed task.
 - BUG :: Designate a bug item.
 - IDEA :: Designate an idea item.
 - NOTE :: Designates a note item.
 - DRAFT :: Designates a draft item.
 - COMMENT :: A 'commented' item.
 - PROJECT :: Designates a project item containing a sequence of tasks.
 
 #+begin_src org
   ,* PROJECT project
   ,** DONE foo
   ,** TODO bar
 #+end_src
 
 ** COMMENT Tasks
 :PROPERTIES:
 :ID:       0f4c0afd-a774-4b98-900b-1ab44f9fd2ef
 :END:
 Tasks as they are known in Org, usually consist of a heading that
 starts with a [[id:2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and
 metadata which are present in our collection of tasks.
 
 Our task management system is roughly a hybrid of two more
 conventional methods: GTD and Agile. For convenience I will describe
 these styles and how I use them separately, but the concepts may be
 spliced differently in real tasks.
 
 - *GTD* \\
 - *Agile* \\
   It's a dirty word in some tech circles - the dreaded PIs, daily
   standups, and still nobody knows what's going on, Oh my! Do not
   worry. For the most part we just borrow the vocabulary.
 
   Our /Agile/ workflow consists of roadmaps, features (epics/ARTs),
   issues (user stories), and of course, tasks.
 ** Properties
 :PROPERTIES:
 :ID:       174a993b-a5dc-4324-b4f8-dda8101a55b7
 :END:
 *** IDs
 :PROPERTIES:
 :ID:       3944c851-e46c-4d75-b8f5-07b5c052177a
 :END:
 We reference two different types of identifiers in documentation:
 - UUID :: =ID= property
 - User-defined :: =CUSTOM_ID= property
 
 Most of the time these IDs don't add any information for the reader -
 the UUIDs are used to index and graph documents, CUSTOM_IDs are for
 convenience but are rarely necessary given the many ways of
 identifying a headline.
 ** Tags
 :PROPERTIES:
 :ID:       a7ae1b2a-559e-46e9-8cab-33e39a218288
 :END:
 [[https://orgmode.org/manual/Tags.html][Tags]] are used liberally throughout our documents. They are simple
 strings usually following a headline as a =:=-separated list.
 
 A tag can be any text without newlines, although it is recommended to
 treat them as unique identifiers and usage of whitespace is
 discouraged (but not disallowed).
 *** Tag Types
 :PROPERTIES:
 :ID:       b686dbc5-3505-49d7-b66a-0772bcf1a726
 :END:
 Tags may be prefixed with one of the following characters, indicating
 a special tag type:
 - =@= :: location-tag \\
   A /location tag/ refers to some context-dependent named point in
   space, such as a user's home address, a popular fast food
   restaurant, or a specific room found in most houses.
   - =@home=, =@taco-bell=, =@bedroom=
 - =!= :: timestamp-tag \\
   /Timestamp tags/ refer to some point in time, often named for
   convenience. You may use literal [[https://orgmode.org/manual/Timestamps.html][Timestamps]] too. Timestamp tags
   should not /directly reference/ scheduling information, doing so is
   often a code-smell.
   - =!now=, =!christmas=, =!someday=
 - =#= :: anchor-tag \\
   An /anchor tag/ implies a link to the object identified by some [[id:3944c851-e46c-4d75-b8f5-07b5c052177a][ID]].
   - =#readme=, =#a7ae1b2a-559e-46e9-8cab-33e39a218288=, =#custom-id=
 *** Tag Lists
 :PROPERTIES:
 :ID:       805862be-ba2b-4288-a2e3-791c0aa3802f
 :END:
 ** Links
 :PROPERTIES:
 :ID:       7ecaec5d-c656-44e1-8fad-185915655cee
 :END:
 *** Link Types
 :PROPERTIES:
 :ID:       6aedc026-36d0-4763-adc8-8ae1a79f1b3e
 :END: