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/LatticesCheatSheet][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:

Easily Making CheatSheets with Org-mode

 {{{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.