Commit 29d34a2f authored by Henrik Tramberend's avatar Henrik Tramberend

Update external tools section

parent 974ca48d
[![build status](https://cgmgit.beuth-hochschule.de/teaching/decker/badges/master/build.svg)](https://cgmgit.beuth-hochschule.de/teaching/decker/commits/master)
[![build
status](https://cgmgit.beuth-hochschule.de/teaching/decker/badges/master/build.svg)](https://cgmgit.beuth-hochschule.de/teaching/decker/commits/master)
# decker
......@@ -6,7 +7,9 @@ A markdown based tool for slide deck creation.
## Installation
Pick a [published release](https://cgmgit.beuth-hochschule.de/teaching/decker/tags), download and unpack:
Pick a [published
release](https://cgmgit.beuth-hochschule.de/teaching/decker/tags), download and
unpack:
``` {.sh}
gunzip decker.gz
......@@ -18,33 +21,57 @@ chmod a+x decker
1. Install [stack](https://docs.haskellstack.org/en/stable/README/).
2. Clone this repo.
3. `cd decker`
3. `make install`
4. `make install`
## External tools
Decker uses a few external tools that need to be installed on the system:
- [*rsync*](http://formulae.brew.sh/repos/Homebrew/homebrew-core/formula/rsync) for publishing slide decks and resources
- [*unzip*](http://formulae.brew.sh/repos/Homebrew/homebrew-core/formula/unzip) to extract resources from the decker executable
- [*decktape*](https://github.com/astefanutti/decktape) to convert HTML slide decks to PDF format
- [*LaTeX with pdflatex*](https://www.latex-project.org/get/) to generate LaTeX in PDF-files
- [*rsync*](http://formulae.brew.sh/repos/Homebrew/homebrew-core/formula/rsync)
for publishing slide decks and resources
- [*unzip*](http://formulae.brew.sh/repos/Homebrew/homebrew-core/formula/unzip)
to extract resources from the decker executable
- [*decktape*](https://github.com/astefanutti/decktape) to convert HTML slide
decks to PDF format
- [*LaTeX* with pdflatex](https://www.latex-project.org) to generate LaTeX in
PDF-files and embedded Tikz figures
- [*Graphviz*](http://graphviz.org) to generate graphs using `dot`
- [*Gnuplot*](http://gnuplot.sourceforge.net) to generate graphs using `dot`
- [*pdf2svg*](https://github.com/dawbarton/pdf2svg) to generate SVG files from
PDF documents
### Installation of external tools on macOS
Use [Homebrew](https://brew.sh) to install most of them.
``` {.sh}
brew install rsync unzip graphviz gnuplot pdf2svg
```
For the rest follow instructions on their respective webites.
## 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.
*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:
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.hmtl` A HTML document containing the speaker notes to the slide show.
- `*-handout.hmtl` 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 `*-page.md` are translated into corresponding HTML or PDF documents.
Markdown files ending on `*-page.md` are translated into corresponding HTML
or PDF documents.
## *decker* targets
......@@ -58,7 +85,8 @@ Decker uses a few external tools that need to be installed on the system:
- `decker pdf`
Builds PDF versions of all documents that are generated from `*-page.md` files.
Builds PDF versions of all documents that are generated from `*-page.md`
files.
- `decker pdf-decks`
......@@ -66,22 +94,29 @@ Decker uses a few external tools that need to be installed on the system:
- `decker watch`
Builds HTML versions of all documents and then watches for document changes. Each change to a watched document triggers a rebuild. Watching can be terminated with `^C`.
Builds HTML versions of all documents and then watches for document changes.
Each change to a watched document triggers a rebuild. Watching can be
terminated with `^C`.
- `decker server`
Like `decker watch`. Additionally a local web server is started that serves the generated HTML files. The `*-deck.html` file is openend in the browser. Changed files are reloaded in the browser. (still requires `livereloadx`)
Like `decker watch`. Additionally a local web server is started that serves
the generated HTML files. The `*-deck.html` file is openend in the browser.
Changed files are reloaded in the browser. (still requires `livereloadx`)
- `decker example`
Write a few example files to the current directory. To start exploring decker type
Write a few example files to the current directory. To start exploring
decker type
``` {.bash}
$ decker example
$ decker server
```
and make some changes to the Markdown files. `example-deck.md` contains the source code for a slide deck that is supposed to (someday) explain most of the features supported.
and make some changes to the Markdown files. `example-deck.md` contains the
source code for a slide deck that is supposed to (someday) explain most of
the features supported.
- `decker clean`
......@@ -93,22 +128,32 @@ Decker uses a few external tools that need to be installed on the system:
- `decker meta`
Pretty prints all meta data that can be found in `*.yaml` files in the current directory and below. Meta data is mainly used to perform substitutions in Markdown documents using the Mustache templating system.
Pretty prints all meta data that can be found in `*.yaml` files in the
current directory and below. Meta data is mainly used to perform
substitutions in Markdown documents using the Mustache templating system.
- `decker publish`
Publish the generated files to a remote location using `rsync` if the location is specified in the meta data. The keys `rsync-destination.host` and `rsync-destination.path` specify the publishing destination.
Publish the generated files to a remote location using `rsync` if the
location is specified in the meta data. The keys `rsync-destination.host`
and `rsync-destination.path` specify the publishing destination.
## Contributions
### Pull requests
Contributions are accepted via pull requests. Before working on a feature, please write up an issue and discuss it with the other developers.
Contributions are accepted via pull requests. Before working on a feature,
please write up an issue and discuss it with the other developers.
### CI build checks
The decker repository has a GitLab CI runner configured, that builds and runs all tests for each commit on every branch. Look at the status display for recent run of the [CI pipelines](pipelines).
The decker repository has a GitLab CI runner configured, that builds and runs
all tests for each commit on every branch. Look at the status display for recent
run of the [CI pipelines](pipelines).
### Haskell source code formatting
Haskell soure code readability depends heavily on consistent formatting conventions. With decker, formatting is automated using the excellent [hindent]() tool. Formatting is checked for each commit that is uploaded to the GitLab repository.
Haskell soure code readability depends heavily on consistent formatting
conventions. With decker, formatting is automated using the excellent
[hindent]() tool. Formatting is checked for each commit that is uploaded to the
GitLab repository.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment