#+PROPERTY: header-args :tangle "./.org-mode-ecm.emacs.el" :results output silent
#+OPTIONS: toc:3

Never compile this.

#+NAME: org_gcr_2017-07-21_mara_5170EF1B-2FA1-4BE2-BC63-1443252F0717
#+BEGIN_SRC emacs-lisp
;; -*- no-byte-compile: t; -*-
#+END_SRC

* Org-Mode Exemple Complet Minimal
   :PROPERTIES:
   :ID:       org_gcr_2017-05-12_mara:1035FF79-3703-49A6-8522-618B38A48F6C
   :END:

Configure EMACS to easily provide ECMs.

Sysop is likely to use this often.

Start EMACS with this command:

#+BEGIN_EXAMPLE
emacs --debug-init --no-init-file --no-splash --background-color white --foreground-color black  --vertical-scroll-bars --eval '(switch-to-buffer "*Messages*")' --name ECM-TEST --title ECM-TEST --load ~/src/help/.org-mode-ecm.emacs.el &
#+END_EXAMPLE

** Principle of Least Astonishment (POLA)
  :PROPERTIES:
  :ID:       org_gcr_2017-05-12_mara:626B5DD1-97D8-4B85-96BC-B9A96F18AF1E
  :END:
*** Time
:PROPERTIES:
:ID:       org_gcr_2018-03-16_mara:BC16A47E-FC4E-4F12-8813-583BF4C3EF5A
:END:
Standardize timestamps.

#+name: org_gcr_2018-03-16_mara_24B486D3-AF94-44E7-99F6-AEB7A53FD0E6
#+begin_src emacs-lisp
(defun help/get-timestamp ()
  "Produces a full ISO 8601 format timestamp."
  (interactive)
  (let* ((timestamp-without-timezone (format-time-string "%Y-%m-%dT%T"))
         (timezone-name-in-numeric-form (format-time-string "%z"))
         (timezone-utf-offset
          (concat (substring timezone-name-in-numeric-form 0 3)
                  ":"
                  (substring timezone-name-in-numeric-form 3 5)))
         (timestamp (concat timestamp-without-timezone
                            timezone-utf-offset)))
    timestamp))

(defun help/insert-timestamp ()
  "Inserts a full ISO 8601 format timestamp."
  (interactive)
  (insert (help/get-timestamp)))

(defun help/get-timestamp-no-colons ()
  "Produces a full ISO 8601 format timestamp with colons replaced by hyphens."
  (interactive)
  (let* ((timestamp (help/get-timestamp))
         (timestamp-no-colons (replace-regexp-in-string ":" "-" timestamp)))
    timestamp-no-colons))

(defun help/insert-timestamp-no-colons ()
  "Inserts a full ISO 8601 format timestamp with colons replaced by hyphens."
  (interactive)
  (insert (help/get-timestamp-no-colons)))

(defun help/insert-datestamp ()
  "Produces and inserts a partial ISO 8601 format timestamp."
  (interactive)
  (insert (format-time-string "%F")))
#+end_src
*** Garbage Collection
:PROPERTIES:
:ID:       org_gcr_2017-07-29_mara:5A6162AE-F0FD-491D-BC05-F288F46F6125
:END:
Clear memory and disable garbage collection or return garbage collection to
normal.

#+NAME: org_gcr_2017-07-29_mara_3F459DF6-EA6A-4D48-BB0A-3670FCB25713
#+BEGIN_SRC emacs-lisp
(setq help/default-gc-cons-threshold gc-cons-threshold)
(defun help/set-gc-cons-threshold (&optional multiplier notify)
  "Set `gc-cons-threshold' either to its default value or a
   `multiplier' thereof."
  (let* ((new-multiplier (or multiplier 1))
         (new-threshold (* help/default-gc-cons-threshold
                           new-multiplier)))
    (setq gc-cons-threshold new-threshold)
    (when notify (message "Setting `gc-cons-threshold' to %s" new-threshold))))
#+END_SRC
*** Load Behavior
   :PROPERTIES:
   :ID:       org_gcr_2017-05-12_mara:75985F03-F3B9-4DA3-8F6E-393E4C2F06E7
   :END:

EMACS can load 3 different representations of a Emacs-Lisp source file code
OOTB. The name of source code file is the value before the file extension. When
you pass ~load~ a name it searches for an acceptable representation. Representation
types are indicated by their extension name. =.el= is a human readable and
uncompiled. =.elc= is not human readable and compiled. =.gz= is Gzip compressed and
contains =.el= or =.elc= files.

The variable ~load-suffixes~ determines the order for which text and byte-code
representations are first searched by extension-name. The variable
~load-file-rep-suffixes~ determines the order for all other extension types.

OOTB, EMACS combines the productivity of REPL style of development with the
speed of compiled code by ~load~'ing byte-code first, text second, and compressed
third. This workflow gives you the fastest code at run-time and lets you
experiment with new features stored in text. When you are ready to use them
every time, you compile them. There is only one downside of this approach: when
you forget that it works this way it can be confusing.

When you forget about that style of system you end up with surprising behavior.
The surprise comes when you forget to compile code and then write new code that
depends on the now old version of that code. After the next build, your system
can break in surprising ways. This violates the Principle of Least Astonishment.

This system values predictability so it does the simplest thing possible: ~load~
searches for the newest representation of a file and uses that one. It assumes
that Sysop has total and complete control over the management of file
representations.

This is the *first* thing that /ought/ to happen in the initialization of *any*
tangled system.

#+NAME: org_gcr_2017-05-12_mara_E2EECBA9-1ECD-498B-A45B-CE21135CF080
#+BEGIN_SRC emacs-lisp
(setq load-prefer-newer t)
#+END_SRC

*** GnuTLS integration
:PROPERTIES:
:ID:       org_gcr_2019-01-26T01-36-06-06-00_cosmicality:CA487B29-55EE-4015-B340-2F1374F96959
:END:

Forbid [[https://www.gnu.org/software/emacs/manual/html_mono/emacs-gnutls.html#Help-For-Users][Emacs GnuTLS]] from [[https://gnutls.org/manual/html_node/Priority-Strings.html][using TLSv1.3]].

Changing this setting requires a restart.

When I used Emacs from Brew 26.1, I had to forbid TLS1.3 using this setting.

When I switched to the Emacs for Mac OSX distribution I had to remove that
setting.

When Brew and Cask merged and I upgraded to 26.2 I had to restore this
setting. 

#+name: org_gcr_2019-01-26T01-36-06-06-00_cosmicality_46A574D5-AE39-402A-9F16-AD72732C95CB
#+begin_src emacs-lisp
(setq gnutls-algorithm-priority "NORMAL:-VERS-TLS1.3")
#+end_src

** Org-Mode Exemple Complet Minimal
   :PROPERTIES:
   :ID:       org_gcr_2017-05-12_mara:572E2309-5DCA-4AE1-AAC4-36B7E07AD46D
   :END:

Every new EMACS releases comes with the latest stable Org-Mode release. To get
hot-fixes, cutting edge features, and easy patch creation though, you need to
use the version from Git.

These detailed and clear [[http://orgmode.org/manual/Installation.html][directions]] explain how ot run Org-Mode from Git. The only
thing worth mentioning again is that in order to use *any* version of Org-Mode
other than the one that comes OOTB you *must* load Org-Mode *before* anything else
in your initialization file. It is easy to do! When you get
unexpected Org-Mode behavior be sure to stop and investigate ~org-version~ and
decide whether or not it is what you expect and prepare an ECM if necessary.

*** Things That Must Occur Before Loading Org-Mode
:PROPERTIES:
:ID:       org_gcr_2017-07-30_mara:3CF35008-D435-4CCB-90D7-5CFA06E15467
:END:
Add the Org-Mode core distribution the load path.

#+NAME: org_gcr_2017-05-12_mara_DAFA4781-7A63-44A1-8817-C4AB75F23130
#+BEGIN_SRC emacs-lisp
(add-to-list 'load-path "~/src/org-mode/lisp")
#+END_SRC

Add the Org-Mode-Contributions distribution to the load path. The contributions
are essential.

#+NAME: org_gcr_2017-05-12_mara_018101D7-1448-4844-861B-789F222A9FD4
#+BEGIN_SRC emacs-lisp
(add-to-list 'load-path "~/src/org-mode/contrib/lisp")
#+END_SRC

Allow single-character alphabetical bullet lists. This configuration must occur
before loading Org-Mode. *Never* remove this from a submitted ECM.

#+NAME: org_gcr_2017-05-12_mara_050624C5-3BC5-4049-B070-F0A6736EB754
#+BEGIN_SRC emacs-lisp
(setq org-list-allow-alphabetical t)
#+END_SRC

Unchecked boxes prevent marking the parent as done. This configuration must
occur before loading Org-Mode. *Never* remove this from a submitted ECM.

#+NAME: org_gcr_2017-05-12_mara_7A650900-7023-4EA7-B2DB-CAB39437E9F3
#+BEGIN_SRC emacs-lisp
(setq org-enforce-todo-checkbox-dependencies t)
#+END_SRC

Use math double brackets for _Literate Programming_ instead of GUILLEMET delimeters.

#+NAME: org_gcr_2017-07-17_mara_755B4DF4-9BEF-4349-94CB-0452730D67F1
#+BEGIN_SRC emacs-lisp
(setq org-babel-noweb-wrap-start "⟪")
(setq org-babel-noweb-wrap-end "⟫")
#+END_SRC
*** Loading Org-Mode
:PROPERTIES:
:ID:       org_gcr_2017-07-30_mara:FFA7E062-C039-4F3F-82FC-12A49FF379B8
:END:
Load Org-Mode.

#+NAME: org_gcr_2017-05-12_mara_766E7D57-B6F9-4718-AF7E-30EE4A23BDF1
#+BEGIN_SRC emacs-lisp
(require 'org)
#+END_SRC
*** Things That Must Occur Only After Loading Org-Mode
:PROPERTIES:
:ID:       org_gcr_2017-07-30_mara:D9207828-3783-4599-BA48-A6EB2C3FCAE4
:END:

Helper doubles available memory.

#+NAME: org_gcr_2017-08-02_mara_92B4C3CB-6CE3-4211-8A18-C7BE905BFBC2
#+BEGIN_SRC emacs-lisp
(defun help/double-gc-cons-threshold () "Double `gc-cons-threshold'." (help/set-gc-cons-threshold 2))
#+END_SRC

Double garbage collection during tangling. Instead of storing this in the
primary Org-Mode Literate Programming configuration I want it here so that it
is always available.

#+NAME: org_gcr_2017-08-02_mara_DAC6E558-E49D-4551-8789-2B3FB88F6CE7
#+BEGIN_SRC emacs-lisp
(add-hook 'org-babel-pre-tangle-hook #'help/double-gc-cons-threshold)
(add-hook 'org-babel-post-tangle-hook #'help/set-gc-cons-threshold)
#+END_SRC

Display system info.

#+NAME: org_gcr_2017-05-12_mara_901541A6-1DB6-4EA2-8688-9C888C41902A
#+BEGIN_SRC emacs-lisp
(defun help/display-system-info ()
  (interactive)
  (message "<<<ECM Information>>>\nThis buffer file: %s\nAs Of: %s\nOrg-Version: %s\nOrg-Git-Version:%s\nEmacs-Version: %s\nNoweb wrap start and stop delimeters: '%s' and '%s'\norg-babel-default-header-args:\n"
           buffer-file-name
           (help/get-timestamp)
           (org-version)
           (org-git-version)
           (emacs-version)
           org-babel-noweb-wrap-start
           org-babel-noweb-wrap-end)
  (pp org-babel-default-header-args))
(help/display-system-info)
#+END_SRC