---

lang: en-US

Decker

A markdown based tool for slide deck creation.

Installation of binaries

Under Releases you can find the binaries of decker.

To install the program by hand you simply need to download the binary and put it in a location where your operating system can find executable files. The executable and its internal dependencies are statically linked and everything decker extracts in order to generate its output is inside its binary.

Manual installation on Windows

If you have already installed decker with an installer you can simply replace the decker.exe inside its installation directory with a new version.

If you have not yet installed decker and want to install one of the released binaries by hand, simply put it into an isolated directory of your choice. You want to rename the executable to decker.exe. Then you need to put that directory onto your system's search path for binaries. To do this, search for "environment variables" in Windows' own search bar and pick the option "Edit the system environment variables". Then click the "Environment Variables..." button in the bottom right corner of the opened dialog. In the next dialog window, pick either your user account's or your system's environment variables and search for the entry Path. "Edit" the entry, press "New" and enter the location of the directory you put the decker.exe exectuable in. Confirm your changes by pressing the "OK" buttons and you are done. If any program you want to run decker from was still running, it needs to be restarted now.

Manual installation on Linux

After you download the decker-executable from the Releases rename it to decker (or any name of your liking). You may need to set the downloaded file as executable. In a terminal, this is done by entering chmod +x decker while inside the directory where your decker-executable resides.

Now you need to put the executable onto your search path. To see your current search path, enter echo $PATH in a terminal. You should see a list of directories that are on your binary search path.

To install decker for your user, simply put the downloaded executable into one of the listed directories inside that user's home directory. These are usually /home/user/.bin, /home/user/.local/bin or /home/user/bin. If none of these directories are in your search path you can add a directory of your choice to the search path by adding this to your user's .profile configuration file which is also usually located inside that user's home directory:

if [ -d "$HOME/.local/bin" ] ; then
    PATH="$HOME/.local/bin:$PATH"
fi

If a configuration like this already exists inside your .profile config it usually means that the requested directory does not exist yet. Simply create it and move the decker executable there, then restart your shell.

To install decker for the entire system, simply put it into that system's directory for locally installed binaries which usually is /usr/local/bin. You usually need to be root in order to perform this operation.

Manual installation on MacOS

To install decker on MacOS you need to download the executable and put it into your binary search path and set the downloaded file as executable. For instance, download the latest executable from Releases and globally then globally install it on your system:

cd ~/Downloads/
mv decker-* decker
chmod +x decker

You should then put the decker binary into a directory that is in your PATH (see Linux instructions above).

If you then run decker -h in the terminal for the first time, MacOS will show a dialog complaining that it cannot open decker for security reasons. Click on "Done", not on "Move to Trash". The open your system settings, go to "Privacy & Security", scroll down to "decker was blocked to protect your Mac". Click "Allow Anyway" and run decker -h in the terminal again. In the dialog asking "Open decker?" click on "Open Anyway" and enter the requested password. From that time on you can run decker like any other command line programm.

Installation from source

1. Install stack and Node.js (for npm)
2. Clone this repo.
3. cd decker
4. git submodule update --init --recursive
5. make install

Notes:

• Decker will be built using the language: GHC2021 option for selection of modern haskell language features. The default version of stack installed by your package manager might not be high enough to recognize this option. You can use stack upgrade to ask your stack installation to self-update to the latest version.

• Decker will be installed under ~/.local/bin which is default not recognized by your terminal. If decker is not found by your terminal, add the path to the corresponding config file. For zsh (default for macos) do the following steps. Run from the terminal:

  1. touch ~/.zshrc
  2. echo PATH=$HOME/.local/bin:$PATH > ~/.zshrc
  3. source ~/.zshrc

Third-party resources

reveal.js MathJax and Font-Awesome dependencies are tracked via submodules. After upgrading any of these submodules you need to run

make upgrade-third-party

to copy the needed resources into the main repo at resource/decker/support/vendor.

Installation from source on Windows

Instead of a makefile we use a PowerShell script on Windows to install decker from source

1. cd decker
2. .\bin\build.ps1

If you want to copy decker to C:\Program Files (x86) you can call .\bin\build.ps1 -local. This needs a PowerShell session with administrator rights.

To then call decker from anywhere on the PowerShell command line create a PowerShell profile file, add the following line, and restart your PowerShell session!

$Env:Path += ";${Env:ProgramFiles(x86)}\Decker\bin"

Note:

Windows Antivirus Protection has a high impact on compilation time. Add the following directories as exclusions to safe about 20-40% compilation time.

• Haskell stack build tool: usually under C:\sr
• Haskell compiler: %AppData%\Local\Programs\stack\x86_64-windows\ghc-x.x.x\bin
• this repository

Development

Haskell

Use appropriate tooling. I use:

• Visual Studio Code with the following plugins:
  • Haskell Language Server
  • hindent-format

Templates and CSS

To interactively work on the template, CSS and Javascript files in resource/template and resource/support run Decker as stack run decker server. This will automatically incorporate all changes and reload the documents in the browser.

External tools

Decker uses a few external tools that need to be installed on the system to use the full functionality:

• ssh for publishing slide decks and resources
• rsync for publishing slide decks and resources
  • Note: The default openSSH implementation on Windows does not work together with cygwin's rsync implementation. Either move cygwin's ssh implementation higher up in the PATH list or run decker publish from cygwin's terminal.
• LaTeX with pdflatex to generate LaTeX in PDF-files and embedded Tikz figures
• Graphviz to generate graphs using dot
• Gnuplot to generate graphs using dot
• pdf2svg to generate SVG files from PDF documents
• libbzip2-dev
• NodeJS to install JavaScript dependencies
• coreutils the GNU coreutils

Installation of external tools on macOS

Use Homebrew to install most of them.

brew install rsync graphviz gnuplot pdf2svg yarn coreutils pkg-config

For the rest follow instructions on their respective webites.

To confirm that you have installed all of the required external tools, run the following command in a terminal window:

decker check

Installation of external tools on Linux

Use Ubuntu's Advanced Packaging Tool (APT) to install external tools.

apt-get update && apt-get install -y texlive-full plantuml gnuplot graphviz libbz2-dev pdf2svg rsync ssh libtinfo-dev libgmp3-dev zlib1g-dev

To confirm that you have installed all of the required external tools, run the following command in a terminal window:

decker check

Usage

Decker behaves very much like a build tool. It works recursively on the current directory and all subdirectories. Markdown files ending on .md in those directories are processed and converted to either a Reveal.js slide show, a HTML document, or a PDF document, depending on the file name.

• *-deck.md

  Files with this ending are processed as silde decks. From one source file potentially four different targets can be generated:

  • *-deck.html A reveal.js based slide show
  • *-handout.html A HTML document containing the speaker notes to the slide show.
  • *-deck.pdf A PDF version of the slide show
  • *-handout.pdf A PDF version of the handout

• *-page.md

  Markdown files ending on