readme.md 4.6 KB
Newer Older
Henrik Tramberend's avatar
Henrik Tramberend committed
1 2
[![build status](https://cgmgit.beuth-hochschule.de/teaching/decker/badges/master/build.svg)](https://cgmgit.beuth-hochschule.de/teaching/decker/commits/master)

Henrik Tramberend's avatar
Henrik Tramberend committed
3 4 5 6
# decker

A markdown based tool for slide deck creation.

7 8
## Installation

9 10
Pick a [published release](https://cgmgit.beuth-hochschule.de/teaching/decker/tags), download and unpack:

11
``` {.sh}
12 13 14 15 16 17
gunzip decker.gz
chmod a+x decker
```

## Installation from source

18 19
1.  Install [stack](https://docs.haskellstack.org/en/stable/README/).
2.  Clone this repo.
Henrik Tramberend's avatar
Henrik Tramberend committed
20
3.  `cd decker`
Henrik Tramberend's avatar
Henrik Tramberend committed
21
3.  `make install`
22

Henrik Tramberend's avatar
Henrik Tramberend committed
23 24 25 26 27 28 29 30
## 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
 
Henrik Tramberend's avatar
Henrik Tramberend committed
31 32
## Usage

33
*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.
Henrik Tramberend's avatar
Henrik Tramberend committed
34

Henrik Tramberend's avatar
Henrik Tramberend committed
35
-   `*-deck.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
36

37
    Files with this ending are processed as silde decks. From one source file potentially four different targets can be generated:
Henrik Tramberend's avatar
Henrik Tramberend committed
38 39

    -   `*-deck.html` A reveal.js based slide show
40
    -   `*-handout.hmtl` A HTML document containing the speaker notes to the slide show.
Henrik Tramberend's avatar
Henrik Tramberend committed
41 42 43
    -   `*-deck.pdf` A PDF version of the slide show
    -   `*-handout.pdf` A PDF version of the handout

Henrik Tramberend's avatar
Henrik Tramberend committed
44
-   `*-page.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
45

46
    Markdown files ending on `*-page.md` are translated into corresponding HTML or PDF documents.
Henrik Tramberend's avatar
Henrik Tramberend committed
47 48 49

## *decker* targets

Henrik Tramberend's avatar
Henrik Tramberend committed
50
-   `decker help`
Henrik Tramberend's avatar
Henrik Tramberend committed
51

Henrik Tramberend's avatar
Henrik Tramberend committed
52
    Prints a help document to stdout in Markdown format.
Henrik Tramberend's avatar
Henrik Tramberend committed
53

Henrik Tramberend's avatar
Henrik Tramberend committed
54 55 56 57 58
-   `decker html`

    Builds HTML versions of all available documents.

-   `decker pdf`
Henrik Tramberend's avatar
Henrik Tramberend committed
59

Henrik Tramberend's avatar
Henrik Tramberend committed
60
    Builds PDF versions of all documents that are generated from `*-page.md` files.
Henrik Tramberend's avatar
Henrik Tramberend committed
61

Henrik Tramberend's avatar
Henrik Tramberend committed
62 63 64
-   `decker pdf-decks`

    Builds PDF versions of all slide decks (requires `decktape.sh`).
Henrik Tramberend's avatar
Henrik Tramberend committed
65

Henrik Tramberend's avatar
Henrik Tramberend committed
66
-   `decker watch`
Henrik Tramberend's avatar
Henrik Tramberend committed
67

68
    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`.
Henrik Tramberend's avatar
Henrik Tramberend committed
69

Henrik Tramberend's avatar
Henrik Tramberend committed
70
-   `decker server`
Henrik Tramberend's avatar
Henrik Tramberend committed
71

Henrik Tramberend's avatar
Henrik Tramberend committed
72
    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`)
Henrik Tramberend's avatar
Henrik Tramberend committed
73

Henrik Tramberend's avatar
Henrik Tramberend committed
74
-   `decker example`
Henrik Tramberend's avatar
Henrik Tramberend committed
75

76
    Write a few example files to the current directory. To start exploring decker type
Henrik Tramberend's avatar
Henrik Tramberend committed
77 78 79 80 81 82

    ``` {.bash}
    $ decker example
    $ decker server
    ```

Henrik Tramberend's avatar
Henrik Tramberend committed
83
    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.
Henrik Tramberend's avatar
Henrik Tramberend committed
84

Henrik Tramberend's avatar
Henrik Tramberend committed
85
-   `decker clean`
Henrik Tramberend's avatar
Henrik Tramberend committed
86 87

    Recursively removes all generated files from the current directory.
Henrik Tramberend's avatar
Henrik Tramberend committed
88

Henrik Tramberend's avatar
Henrik Tramberend committed
89
-   `decker check`
Henrik Tramberend's avatar
Henrik Tramberend committed
90

91
    Check for all required external depencies. If one of the programs is missing, an error is generated. Required programs include:
Henrik Tramberend's avatar
Henrik Tramberend committed
92 93 94 95 96 97

    -   `pdflatex` as part of a complete LaTeX installation
    -   `decktape.sh` for the generation of PDF versions of slide decks
    -   `livereloadx` as live-reloading local webserver
    -   `rsync` to publish the documents to a remote location

Henrik Tramberend's avatar
Henrik Tramberend committed
98
-   `decker plan`
Henrik Tramberend's avatar
Henrik Tramberend committed
99

Henrik Tramberend's avatar
Henrik Tramberend committed
100 101
    Prints a list of all source files found below the current directory.

Henrik Tramberend's avatar
Henrik Tramberend committed
102
-   `decker meta`
Henrik Tramberend's avatar
Henrik Tramberend committed
103

104
    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.
Henrik Tramberend's avatar
Henrik Tramberend committed
105

Henrik Tramberend's avatar
Henrik Tramberend committed
106
-   `decker publish`
Henrik Tramberend's avatar
Henrik Tramberend committed
107

108
    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.
Henrik Tramberend's avatar
Henrik Tramberend committed
109 110 111 112 113

## Contributions

### Pull requests

114 115 116 117
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

Henrik Tramberend's avatar
Henrik Tramberend committed
118
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).
119 120 121 122

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