# Created 2019-07-12 Fri 21:25
#+OPTIONS: toc:nil d:nil
#+OPTIONS: toc:nil d:nil
#+TITLE: Easily Making CheatSheets with Org-mode
#+AUTHOR: [[http://www.cas.mcmaster.ca/~alhassm/][Musa Al-hassy]]
#+export_file_name: README.org

Pretty cheat sheets, or “reference cards”, obtainable from Org-mode files. See section [[#getting-started]] below to get started making your own cheat sheets!

*The listing sheet, as PDF, can be found
 [[file:CheatSheet.pdf][here]]*,
 or as a [[file:CheatSheet_Portrait.pdf][single column portrait]],
 while below is an unruly html rendition.

This reference sheet is built from a
[[https://github.com/alhassy/CheatSheet][CheatSheets with Org-mode]]
system.

#+toc: headlines 2
#+subtitle: ---Reference Sheet for “What I'm Currently Learning”---
#+macro: blurb Pretty cheat sheets, or “reference cards”, obtainable from Org-mode files. See section [[#getting-started]] below to get started making your own cheat sheets!

#+latex_header: \usepackage{titling,parskip}
#+latex_header: \usepackage{eufrak} % for mathfrak fonts
#+latex_header: \usepackage{multicol,xparse,newunicodechar}

#+latex_header: \usepackage{etoolbox}

#+latex_header: \newif\iflandscape
#+latex_header: \landscapetrue

#+latex_header_extra: \iflandscape \usepackage[landscape, margin=0.5in]{geometry} \else \usepackage[margin=0.5in]{geometry} \fi

#+latex_header: \def\cheatsheetcols{2}
#+latex_header: \AfterEndPreamble{\begin{multicols}{\cheatsheetcols}}
#+latex_header: \AtEndDocument{ \end{multicols} }

#+latex_header: \let\multicolmulticols\multicols
#+latex_header: \let\endmulticolmulticols\endmulticols
#+latex_header: \RenewDocumentEnvironment{multicols}{mO{}}{\ifnum#1=1 #2 \def\columnbreak{} \else \multicolmulticols{#1}[#2] \fi}{\ifnum#1=1 \else \endmulticolmulticols\fi}

#+latex_header: \def\maketitle{}

#+latex: \fontsize{9}{10}\selectfont

#+latex_header_extra: \newcommand\textbox[1]{\parbox{.333\textwidth/\cheatsheetcols}{#1}}

#+latex_header: \def\yoururl{}

#+latex_header: \usepackage[dvipsnames]{xcolor} % named colours
#+latex: \definecolor{grey}{rgb}{0.5,0.5,0.5}

#+latex_header: \usepackage{color}
#+latex_header: \definecolor{darkgreen}{rgb}{0.0, 0.3, 0.1}
#+latex_header: \definecolor{darkblue}{rgb}{0.0, 0.1, 0.3}
#+latex_header: \hypersetup{colorlinks,linkcolor=darkblue,citecolor=darkblue,urlcolor=darkgreen}

#+latex_header: \setlength{\parindent}{0pt}


#+latex_header: \def\cheatsheetitemsep{-0.5em}
#+latex_header: \let\olditem\item
#+latex_header_extra: \def\item{\vspace{\cheatsheetitemsep}\olditem}

#+latex_header: \usepackage{UnicodeSymbols}

#+latex_header: \makeatletter
#+latex_header: \AtBeginEnvironment{minted}{\dontdofcolorbox}
#+latex_header: \def\dontdofcolorbox{\renewcommand\fcolorbox[4][]{##4}}
#+latex_header: \makeatother



#+latex_header: \RequirePackage{fancyvrb}
#+latex_header: \DefineVerbatimEnvironment{verbatim}{Verbatim}{fontsize=\scriptsize}


#+latex_header: \def\yoururl{https://github.com/alhassy/CheatSheet}

#+latex_header: \def\cheatsheetcols{2}
#+latex_header: \landscapetrue
#+latex_header: \def\cheatsheetitemsep{-0.5em}

#+latex_header: \newunicodechar{𝑻}{\ensuremath{T}}
#+latex_header: \newunicodechar{⊕}{\ensuremath{\oplus}}
#+latex_header: \newunicodechar{≈}{\ensuremath{\approx}}


#+begin_quote
- [[#extra-local-setup][Extra, Local, Setup]]
- [[#project-goal][Project Goal]]
- [[#cheatsheet-examples][CheatSheet Examples]]
- [[#why-learn--relearn][Why Learn & Relearn?]]
- [[#getting-started][Getting Started]]
- [[#what-if-its-not-good-enough][What if it's not good enough?]]
- [[#what-if-i-want-n-columns-or-non-landscape-or-multiple-formats][What if I want ~N~ columns? Or non-landscape? Or multiple formats?]]
- [[#colourful-source-blocks][Colourful Source Blocks]]
- [[#break][break]]
- [[#basic-equational-support][Basic Equational Support]]
- [[#unicode][Unicode]]
- [[#parallel-environment][Parallel Environment]]
- [[#break-1][break]]
- [[#subsection-support][Subsection Support]]
  - [[#a-new-child-tree][A new child tree]]
  - [[#another-child-tree][Another child tree]]
- [[#making-readmeorg][Making ~README.org~]]
#+end_quote

* Project Goal

#+latex: \hspace{-12pt}
/Use the elegant & intuitive Org-mode syntax to produce exquisite reference sheets./

- For example, the boxed section headers here are produced from usual Org headers,
  as in ~* my section~; and one may use [[https://github.com/jkitchin/org-ref][org-ref]] for citations, as in nameref:name

#+latex: \vspace{-1em}
Read [[https://orgmode.org/worg/org-tutorials/org4beginners.html][Org-mode for beginners]] for a refresher!
- For more see [[https://orgmode.org/orgguide.pdf][The Compact Org-mode Guide]].

Execute ~C-c C-e l o~ or ~M-x compile~ to produce a nice looking PDF of your reference sheet.

#+latex: \vspace{-0em}
#+begin_center
/To learn more, manipulating this source is the way to go!/
#+end_center

* CheatSheet Examples

Reference sheets created from this project include:

- [[https://github.com/alhassy/ElispCheatSheet][ElispCheatSheet]] :: Quick reference to the core language of Emacs
     ---Editor MACroS.

- [[https://github.com/alhassy/islam][Islam]] :: Important figures in the faith.

- [[https://github.com/alhassy/PrologCheatSheet][PrologCheatSheet]] :: Program where everything is a relation ---i.e., a database table.

- [[https://github.com/alhassy/CatsCheatSheet][CatsCheatSheet]] ::
     Listing of common theorems in elementary category theory.

- [[https://github.com/alhassy/CatsCheatSheet/blob/master/LatticesCheatSheet.pdf][LatticesCheatSheet]] ::
     Reference sheet for definitions and results in Lattice Theory.

- [[https://github.com/alhassy/OCamlCheatSheet][OCamlCheatSheet]] :: Basics of OCaml, “the best imperative language”.

- [[https://github.com/alhassy/CoqCheatSheet][CoqCheatSheet]] ::
     Reference sheet for the Coq language.

- [[https://github.com/alhassy/GojuRyuCheatSheet][GojuRyuCheatSheet]] :: A quick cheat sheet for common terms in Goju Ryu Karate
     ---the hard-soft style of karate.

#+latex: \vspace{0.5em}
#+begin_center
/If you use this org-setup to produce a neat cheat sheet, please let me know!/
#+end_center


#+latex: \vspace{-0.5em}
* Why Learn & Relearn?

/The world of ideas is not revealed to us in one stroke;/
/we must both permanently and unceasingly recreate it in/
/our consciousness./ ---Rene Thom

I think org-mode is ideal for computing cheat sheets especially since it allows us
to use org-babel tangle to have small minimal working examples that go along with
the ideas.

#+begin_quote
/‘Why’, said the Dodo, ‘the best way to explain it is to do it.’/
\newline ---Alice's Adventures in Wonderland
#+end_quote

/A good stock of examples, as large as possible, is indispensable/
/for a thorough understanding of any concept, and when I want to/
/learn something new, I make it my first job to build one./ ---Paul Halmos

* Getting Started
To use this project for your own cheatsheets,
just copy-paste the following into, say, the
~*scratch*~ buffer then ~C-x C-e~ after the final closing parenthesis.

#+begin_src emacs-lisp :tangle no
(let ((your-repo "~/example") ;; Alter this location!
      (enable-local-variables :all))
      ;; Look at my “local variables” below; ensure nothing malicious.
      ;; So no need to be queried about loading them.

 ;; Obtain the submodule then make a /copy/ of this cheatsheet.
 (eshell-command (concat
   "  cd " your-repo
   "; git submodule add https://github.com/alhassy/CheatSheet.git"
   "; cp CheatSheet/CheatSheet.org ."
  ))

 ;; Make your cheat sheet refer to the submodule's setup file.
 (find-file-other-window (concat your-repo "/CheatSheet.org"))
 (beginning-of-buffer)
 (re-search-forward "INCLUDE: CheatSheetSetup.org" nil t)
 (replace-match "INCLUDE: CheatSheet/CheatSheetSetup.org")
 (beginning-of-buffer)
)

;; To remove a submodule:
;; git submodule deinit ⟪path_to_submodule⟫ ; git rm ⟪path_to_submodule⟫
#+end_src

For the ~README.md~ to be generated as desired, fill in the macros ~URL~ and ~blurb~
at the top of this org file to point to your repository and provide a description
of what the cheatsheet serves to accomplish.

Keep your submodule up to date by running the following command from the parent
project ---i.e., your project.
#+begin_src shell :tangle no
git submodule update
#+end_src

*Alternatively*:

1. Go to the repo where you want to make a cheat sheet.

2. Add this project as a submodule then copy its core to where you're working:
   #+begin_src shell :tangle no
      git submodule add https://github.com/alhassy/CheatSheet.git
      ; cp CheatSheet/CheatSheet.org .
      ; cp CheatSheet/README.org .
   #+end_src

3. Open ~CheatSheet.org~ and locate ~#+INCLUDE: CheatSheetSetup.org~
   then rewrite ~CheatSheetSetup.org~ to ~CheatSheet/CheatSheetSetup.org~.

* What if it's not good enough?

/“The person who thinks of doing something, is usually passed by the person doing it.”/

/The more that you read, the more things you will know./
/The more that you learn, the more places you'll go./
---Dr. Seuss

* What if I want ~N~ columns? Or non-landscape? Or multiple formats?

At the top, say after the ~#+INCLUDE: CheatSheet/CheatSheetSetup.org~ line, add
the following.

#+begin_example org :tangle no
,#+LATEX_HEADER: \def\cheatsheetcols{N}
,#+LATEX_HEADER: \landscapefalse
#+end_example

For example, having three narrow columns is useful for term-heavy or formula heavy sheets.
In contrast, dense sheets may appear less daunting when rendered as single-column in portrait.
Sometimes a double-column portrait is more appropriate.

Press ~C-c C-c~ on the following incantation to produce a single column portrait of the cheat sheet.
#+name: make-portrait
#+begin_src emacs-lisp :results none
(with-temp-buffer
    (insert
    "#+EXPORT_FILE_NAME: CheatSheet_Portrait.pdf
     ,#+LATEX_HEADER_EXTRA: \\landscapefalse \\def\\cheatsheetcols{1}
     ,#+INCLUDE: CheatSheet.org
    ")

    (let ((org-export-use-babel nil))
      (org-mode)
      (org-latex-export-to-pdf)
      )
)
#+end_src

* Colourful Source Blocks

Invoke the following with ~C-c C-c~, or better yet place it in your [[https://alhassy.github.io/init/][Emacs configuration]],
to ensure references are picked up and source code highlighting is turned on
using the Minted package ---which in turn requires the pygmentize system tool.

#+begin_src emacs-lisp
(setq org-latex-listings 'minted
      org-latex-packages-alist '(("" "minted"))
      org-latex-pdf-process
      '("pdflatex -shell-escape -output-directory %o %f"
        "biber %b"
        "pdflatex -shell-escape -output-directory %o %f"
        "pdflatex -shell-escape -output-directory %o %f"))
#+end_src

For faster pdf generation, consider invoking:

#+begin_src emacs-lisp
(setq org-latex-pdf-process
      '("pdflatex -interaction nonstopmode -output-directory %o %f"))
#+end_src

By default, Org exports LaTeX using the ~nonstopmode~ option,
which tries its best to produce a PDF
---which ignores typesetting errors altogether,
and therefore is not necessarily ideal when using LaTeX.

#+latex: \columnbreak
* Basic Equational Support

~\eqn{name}{formula}~
yields a displayed equation with ~formula~ left aligned and ~name~ right aligned:

#+latex: \vspace{-0.7em}
\eqn{name}{formula}
Moreover, we can refer to such a formula by invoking ~\ref{name}~ ---e.g., \ref{Functoriality} and \ref{name}.
However, if ~name~ involves unicode symbols, then this may cause problems.

See the [[https://github.com/alhassy/CatsCheatSheet][CatsCheatSheet]] for examples of this kind.

We may also use [[https://github.com/jkitchin/org-ref][org-ref]] style references, as in ~eqref:name~. However, org-ref may warn that
no context for the reference is found ---that's okay.

- eqref   :: Parenthesised reference: eqref:name
- autoref :: Prefix reference with type: autoref:name
- nameref :: The name of the section that contains this reference: nameref:name

#+latex: \vspace{-3em}
* Unicode

I tend to use a lot of unicode and so this project comes with a unicode
style file. We may add additional support for unicode characters as follows.
#+begin_example org
,#+LATEX_HEADER: \newunicodechar{⊕}{\ensuremath{\oplus}}
#+end_example

Below we demonstrate that [[https://frama-c.com/][loops implement finite quantifications]]
by showing how the specification of a loop is implemented, unsurprisingly,
using a loop.

A finite quantification can be defined axiomatically
by the empty-range rule and split-off term rules.
Together these form a recursive definition which can be phrased as a loop.

#+begin_parallel
#+begin_src c
// For _⊕_ : 𝑻 → 𝑻 → 𝑻,
// fold(A,a,b) ≈ (⊕ x:a..b-1 • A[x])
/*@ axiomatic Fold {
  @
  @ logic 𝑻
  @   fold{L}(𝑻 *A, ℤ a, ℤ b)
  @   reads a,b,A, A[..] ;
  @
  @ axiom foldEmptyRange{L} :
  @   ∀ 𝑻 *A, ℤ a, b; a ≥ b
  @   ⇒  fold(A,a,b) ≡ identity(⊕);
  @
  @ axiom foldSplitOffTerm{L} :
  @   ∀ 𝑻 *A, ℤ a, b; a ≤ b
  @   ⇒     fold(A, a, b+1)
  @        ≡ fold(A, a, b  ) ⊕ A[b];
  @ }
  @*/
#+end_src
#+latex: \columnbreak
#+begin_src c
/*@ requires \valid(A+(0..N-1));
  @ assigns \nothing;
  @ ensures \result ≡ fold(A,0,N);
  @*/
𝑻 fold(int N, 𝑻* A) {

    𝑻 total = identity(⊕);

    /*@ loop invariant
             0 ≤ n ≤ N
          ∧  total ≡ fold(A,0,n);
      @ loop assigns n, total;
      @ loop variant N - n;
    ,*/
    for(int n = 0; n != N; n++)
      total = total ⊕ A[n];
    return total;
}
#+end_src
#+end_parallel

#+latex: \vspace{-0.5em}

This pseudo-code is reified by giving concrete values
for ~(𝑻, ⊕, identity)~ such as ~(int, +, 0)~ or ~(bool, ||, false)~.
Any [[https://en.wikipedia.org/wiki/Monoid][monoid]] will do.

#+latex: \ifnum\cheatsheetcols=1 \newpage \else \fi

* Parallel Environment

Cheat sheets should not waste space, so the setup provides
a ~parallel~ LaTeX enviornment that takes an optional parameter
indicating how many columns are desired ---two by default.
Importantly, we use this environment as if it were any normal org-block:

#+begin_parallel
#+begin_example org :tangle no
,#⸲
,#+begin_parallel org
???content here???
,#+end_parallel
#+end_example

The initial new line is important, otherwise the parallel environment
occurs in-line, which may not be the intended behaviour.
#+end_parallel

The column break is automatic, but as
this is sugar for a ~minipage~ containing a ~multicolum~ we can force a column
separation with ~\columnbreak~.

~parallelNB~ produces a side-by-side rendition with ‘N’o ‘B’ar:

#+begin_parallelNB
left \newline left \newline left

#+latex: \columnbreak
right \newline right \newline right
#+end_parallelNB

Here is an example with four columns:

#+begin_parallel
left \newline left \newline left

#+latex: \columnbreak
middle \newline middle \newline middle

#+latex: \columnbreak
middle \newline middle \newline middle

#+latex: \columnbreak
right \newline right \newline right
#+end_parallel

Here is an example with three columns and ‘n’o ‘b’ar:

#+begin_parallel3NB
left \newline left \newline left

#+latex: \columnbreak
middle \newline middle \newline middle

#+latex: \columnbreak
right \newline right \newline right
#+end_parallel3NB

#+latex: \vfill {\color{white}.}

#+latex: \ifnum\cheatsheetcols=1 \newpage \else \columnbreak \fi

* Subsection Support
Ideally a cheat sheet is not too hierarchical and so a subsection, as in ~** child~,
is turned into a rule as follows.

** A new child tree

Here is the first child's content.


** Another child tree

Here is the sibling's content.

* Making ~README.org~

Evaluate the following source block with ~C-c C-c~
to produce a ~README~ file.

#+name: make-readme
#+begin_src emacs-lisp
(with-temp-buffer
    (insert
    "#+EXPORT_FILE_NAME: README.org
     # HTML: <h1> Easily Making CheatSheets with Org-mode </h1>
     ,#+OPTIONS: toc:nil d:nil
     # Toc is displayed below at a strategic position.

     {{{blurb}}}

     :Hide:
     This project is to contain a listing of common results in X Theory.

     ,*The repo contains other articles I've written on X Theory;*
     ,*which may be read in a blog-format at:*
     https://alhassy.github.io/blog/categories/#Xtheory
     :End:

    ,*The listing sheet, as PDF, can be found
     [[file:CheatSheet.pdf][here]]*,
     or as a [[file:CheatSheet_Portrait.pdf][single column portrait]],
     while below is an unruly html rendition.

     # Markdown links: [title](target)

     This reference sheet is built from a
     [[https://github.com/alhassy/CheatSheet][CheatSheets with Org-mode]]
     system.

     ,#+TOC: headlines 2
     ,#+INCLUDE: CheatSheet.org
    ")

    ;; No code execution on export
    ;; ⟪ For a particular block, we use “:eval never-export” ⟫
    ;;
    (let ((org-export-use-babel nil))
      (org-mode)
      ; (org-md-export-to-markdown)
      ; (package-install 'toc-org)
      (toc-org-mode)
      (toc-org-insert-toc)
      ; (delete "TOC" org-export-exclude-tags)
      (pop org-export-exclude-tags)
      (org-org-export-to-org)
      (add-to-list 'org-export-exclude-tags "TOC")
      )
)
#+end_src

Note that the ~blurb~ macro is defined by the user, to provide a terse description of the project.
- Think the one-line statement at the top of a github repo page.