Mercurial > org > docs / ulang.org

 {{{header(ulang,
 Richard Westhaver,
 ellis@rwest.io,
 The Universal Language)}}}
 
 This document describes a *U-Language* as described by the late great
 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
 
 * ulang
 :PROPERTIES:
 :CUSTOM_ID: 8447a560-7f77-45c7-bd14-2a2af6ad2abc
 :END:
 As the title suggest we refer to our *U-Language* as
 ulang. When I say something along the lines of "Please refer to
 [[Links][ulang:links]]", I am referencing the section named /Links/ of this
 document.
 
 Each section of this document describes an element of the ulang. It is
 recommended to skim through the top-level sections ([[Org-mode][Org-mode]] and
 [[Elements][Elements]]) and review the element sub-headings as needed.
 
 #+TOC: headlines 3
 
 ** Org-mode
 :PROPERTIES:
 :CUSTOM_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
 documentation engine. 
 
 If you are already familiar with Emacs and org-mode, I recommend
 opening the source file 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. The choice
 of Org is arbitrary and the concepts here would apply to other formats
 (LaTeX, Markdown, etc).
 
 Let us first consider /Org the syntax/.
 
 Org syntax is much less popular than Markdown and lacks parsing
 utilities in popular programming languages[fn:1]. Regardless, we are
 committed to it as a foundation because it is the most hackable
 documentation engine available. With enough experience you can morph
 Org into whatever documentation system that is needed.
 
 [fn:1] The ecosystem is changing though, thanks to the dedication of
 some excellent hackers: [[https://github.com/karlicoss/orgparse][python]], [[https://github.com/tecosaur/Org.jl][julia]]
 
 *** TODO organ
 :PROPERTIES:
 :CUSTOM_ID: 22474039-5c18-4179-82aa-a6731e6313a2
 :END:
 - State "TODO"       from              [2023-11-05 Sun 19:21]
 
 =Org-mode= the application depends on Emacs (it's written in Emacs
 Lisp) but that doesn't mean we need to. To solve the issue of
 interoperability between different systems, we are developing a tool
 called [[https://lab.rwest.io/comp/core/-/tree/branch/default/lisp/lib/organ][organ]]. The purpose of =organ= is to provide an external API for
 Org documents that doesn't depend on GNU Emacs.
 
 If we were designing a /personal/ note-taking system, I would argue
 that we don't need this tool. The problem is it's /not/ personal - we
 have a much wider intended audience and need to present information in
 many different ways. This means thinking about hundreds to thousands
 of documents instead of tens, about processing those documents into a
 full-text search database, and reducing cost along the way.
 
 Emacs can do all of these things, but do you really want it to?
 ** Elements
 :PROPERTIES:
 :CUSTOM_ID: 4aa3ec2a-b360-43ae-b2d8-f9735f211290
 :END:
 
 *** Keywords
 :PROPERTIES:
 :CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
 :END:
 The ulang *Keywords* are a superset of those defined by [[https://datatracker.ietf.org/doc/html/rfc2119][RFC-2119]]. The
 definition of a keyword from the original spec is ultimately
 unchanged:
 
 #+begin_quote
 In many standards track documents several words are used to signify
 the requirements in the specification.  These words are often
 capitalized.  This document defines these words as they should be
 interpreted in IETF documents.  Authors who follow these guidelines
 should incorporate this phrase near the beginning of their document:
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
 "OPTIONAL" in this document are to be interpreted as described in
 RFC 2119.
 #+end_quote
 
 We can't be bothered to include these with every document, so here
 they are - don't forget!
 
 #+begin_quote
 1. MUST   This word, or the terms "REQUIRED" or "SHALL", mean that the
    definition is an absolute requirement of the specification.
 
 2. MUST NOT   This phrase, or the phrase "SHALL NOT", mean that the
    definition is an absolute prohibition of the specification.
 
 3. SHOULD   This word, or the adjective "RECOMMENDED", mean that there
    may exist valid reasons in particular circumstances to ignore a
    particular item, but the full implications must be understood and
    carefully weighed before choosing a different course.
 
 4. SHOULD NOT   This phrase, or the phrase "NOT RECOMMENDED" mean that
    there may exist valid reasons in particular circumstances when the
    particular behavior is acceptable or even useful, but the full
    implications should be understood and the case carefully weighed
    before implementing any behavior described with this label.
 
 5. MAY   This word, or the adjective "OPTIONAL", mean that an item is
    truly optional.  One vendor may choose to include the item because a
    particular marketplace requires it or because the vendor feels that
    it enhances the product while another vendor may omit the same item.
    An implementation which does not include a particular option MUST be
    prepared to interoperate with another implementation which does
    include the option, though perhaps with reduced functionality. In the
    same vein an implementation which does include a particular option
    MUST be prepared to interoperate with another implementation which
    does not include the option (except, of course, for the feature the
    option provides.)
 #+end_quote
 
 One of the important features of keywords is that we use them as Org
 [[https://orgmode.org/manual/Workflow-states.html][Workflow states]]. You may use any of the keywords above or below as the
 first word in a heading to signify a requirement or a workflow state:
 
 6. TBD   A task to be done at a later date.
 
 7. TODO   A task yet to be done.
 
 8. WIP   Work In Progress task.
 
 9. NOTE   Designates a note item.
 
 10. DRAFT   Designates a draft item.
 
 11. DEAD   Item that will not be completed.
 
 12. DONE   Completed task.
 
 13. COMMENT A 'commented' item.
 
 *** Macros
 :PROPERTIES:
 :CUSTOM_ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e
 :END:
 Several *global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed
 here for convenience.
 
 #+name: ulang-macros
 #+begin_src emacs-lisp :exports both :results pp
   org-export-global-macros
 #+end_src
 
 #+RESULTS: ulang-macros
 : (("opts" . "#+OPTIONS: $1\n")
 :  ("header" .
 :   "#+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"))
 
 Macros /are not expanded/ in source files - you will see them in the
 form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition
 (in =ulang.el=) in order to export ulang docs with the macros
 expanded.
 
 *** Abbrevs
 :PROPERTIES:
 :CUSTOM_ID: b4c326ba-f74c-4409-9314-8d32df61fc5e
 :END:
 There are several 'abbrev' types made available via =ulang.el=. They
 are intended for flexible templating and ease-of-use for the author.
 
 We try to align our abbrevs following categories:
 - uri
 - term
 - phrase
 - block
 
 Abbrevs may take arguments explicitly or inherit from their
 environment, but usually /are expanded/ in source files.
 
 *** Links
 
 *** Timestamps