readme.md 3.35 KB
Newer Older
Henrik Tramberend's avatar
Henrik Tramberend committed
1
2
3
4
# decker

A markdown based tool for slide deck creation.

5
6
## Installation

7
8
9
10
11
12
13
14
15
Pick a [published release](https://cgmgit.beuth-hochschule.de/teaching/decker/tags), download and unpack:

```sh
gunzip decker.gz
chmod a+x decker
```

## Installation from source

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

Henrik Tramberend's avatar
Henrik Tramberend committed
21
22
## Usage

23
*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
24

Henrik Tramberend's avatar
Henrik Tramberend committed
25
-   `*-deck.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
26

27
    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
28
29

    -   `*-deck.html` A reveal.js based slide show
30
    -   `*-handout.hmtl` A HTML document containing the speaker notes to the slide show.
Henrik Tramberend's avatar
Henrik Tramberend committed
31
32
33
    -   `*-deck.pdf` A PDF version of the slide show
    -   `*-handout.pdf` A PDF version of the handout

Henrik Tramberend's avatar
Henrik Tramberend committed
34
-   `*-page.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
35

36
    Markdown files ending on `*-page.md` are translated into corresponding HTML or PDF documents.
Henrik Tramberend's avatar
Henrik Tramberend committed
37
38
39

## *decker* targets

Henrik Tramberend's avatar
Henrik Tramberend committed
40
-   `decker help`
Henrik Tramberend's avatar
Henrik Tramberend committed
41

Henrik Tramberend's avatar
Henrik Tramberend committed
42
    Prints this document to stdout in Markdown format.
Henrik Tramberend's avatar
Henrik Tramberend committed
43

Henrik Tramberend's avatar
Henrik Tramberend committed
44
45
46
47
48
-   `decker html`

    Builds HTML versions of all available documents.

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

50
    Builds PDF versions of all documents that are generated from `*-deck.md` files.
Henrik Tramberend's avatar
Henrik Tramberend committed
51

Henrik Tramberend's avatar
Henrik Tramberend committed
52
53
54
-   `decker pdf-decks`

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

Henrik Tramberend's avatar
Henrik Tramberend committed
56
-   `decker watch`
Henrik Tramberend's avatar
Henrik Tramberend committed
57

58
    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
59

Henrik Tramberend's avatar
Henrik Tramberend committed
60
-   `decker server`
Henrik Tramberend's avatar
Henrik Tramberend committed
61

62
    Like `decker watch`. Additionally a local web server is started that serves the generated HTML files. The `index.html` document is automatically openend in the browser. Changed files are automatically reloaded in the browser. (requires `livereloadx`)
Henrik Tramberend's avatar
Henrik Tramberend committed
63

Henrik Tramberend's avatar
Henrik Tramberend committed
64
-   `decker example`
Henrik Tramberend's avatar
Henrik Tramberend committed
65

66
    Write a few example files to the current directory. To start exploring decker type
Henrik Tramberend's avatar
Henrik Tramberend committed
67
68
69
70
71
72

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

73
    and make some changes to the Markdown files. `example-deck.md` contains the source code for a slide deck that explains most of the features supported.
Henrik Tramberend's avatar
Henrik Tramberend committed
74

Henrik Tramberend's avatar
Henrik Tramberend committed
75
-   `decker clean`
Henrik Tramberend's avatar
Henrik Tramberend committed
76
77

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

Henrik Tramberend's avatar
Henrik Tramberend committed
79
-   `decker check`
Henrik Tramberend's avatar
Henrik Tramberend committed
80

81
    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
82
83
84
85
86
87

    -   `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
88
-   `decker plan`
Henrik Tramberend's avatar
Henrik Tramberend committed
89

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

Henrik Tramberend's avatar
Henrik Tramberend committed
92
-   `decker meta`
Henrik Tramberend's avatar
Henrik Tramberend committed
93

94
    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
95

Henrik Tramberend's avatar
Henrik Tramberend committed
96
-   `decker publish`
Henrik Tramberend's avatar
Henrik Tramberend committed
97

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