Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alhassy/CheatSheet

Pretty cheat sheets, or ``reference cards'', obtainable from Org files.
https://github.com/alhassy/CheatSheet

cheatsheet emacs org-mode pdf reference-sheets unicode

Last synced: about 2 months ago
JSON representation

Pretty cheat sheets, or ``reference cards'', obtainable from Org files.

Awesome Lists containing this project

README 

        
# 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: 
 Easily Making CheatSheets with Org-mode 


     ,#+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.