readme.md 4.82 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

Henrik Tramberend's avatar
Henrik Tramberend committed
7
Pick a [published release](master/tags), download and unpack:
8

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

## Installation from source

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

Henrik Tramberend's avatar
Henrik Tramberend committed
21
22
23
24
## External tools

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

25
-   [*ssh*](https://www.openssh.com) for publishing slide decks and resources
26
27
28
29
30
31
32
33
34
35
36
37
-   [*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
38
-   [*sassc*](https://github.com/sass/sassc) to compile SCSS to CSS
39
40
41
42
43
44

### Installation of external tools on macOS

Use [Homebrew](https://brew.sh) to install most of them.

``` {.sh}
45
brew install rsync unzip graphviz gnuplot pdf2svg sassc
46
47
48
49
```

For the rest follow instructions on their respective webites.

Henrik Tramberend's avatar
Henrik Tramberend committed
50
51
## Usage

52
53
54
55
*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
56

Henrik Tramberend's avatar
Henrik Tramberend committed
57
-   `*-deck.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
58

59
60
    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
61
62

    -   `*-deck.html` A reveal.js based slide show
63
64
    -   `*-handout.hmtl` A HTML document containing the speaker notes to the
        slide show.
Henrik Tramberend's avatar
Henrik Tramberend committed
65
66
67
    -   `*-deck.pdf` A PDF version of the slide show
    -   `*-handout.pdf` A PDF version of the handout

Henrik Tramberend's avatar
Henrik Tramberend committed
68
-   `*-page.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
69

70
71
    Markdown files ending on `*-page.md` are translated into corresponding HTML
    or PDF documents.
Henrik Tramberend's avatar
Henrik Tramberend committed
72
73
74

## *decker* targets

Henrik Tramberend's avatar
Henrik Tramberend committed
75
-   `decker help`
Henrik Tramberend's avatar
Henrik Tramberend committed
76

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

Henrik Tramberend's avatar
Henrik Tramberend committed
79
80
81
82
83
-   `decker html`

    Builds HTML versions of all available documents.

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

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

Henrik Tramberend's avatar
Henrik Tramberend committed
88
89
90
-   `decker pdf-decks`

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

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

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

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

100
101
102
    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
103

Henrik Tramberend's avatar
Henrik Tramberend committed
104
-   `decker example`
Henrik Tramberend's avatar
Henrik Tramberend committed
105

106
107
    Write a few example files to the current directory. To start exploring
    decker type
Henrik Tramberend's avatar
Henrik Tramberend committed
108
109
110
111
112
113

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

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

Henrik Tramberend's avatar
Henrik Tramberend committed
118
-   `decker clean`
Henrik Tramberend's avatar
Henrik Tramberend committed
119
120

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

Henrik Tramberend's avatar
Henrik Tramberend committed
122
-   `decker plan`
Henrik Tramberend's avatar
Henrik Tramberend committed
123

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

Henrik Tramberend's avatar
Henrik Tramberend committed
126
-   `decker meta`
Henrik Tramberend's avatar
Henrik Tramberend committed
127

128
129
130
    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
131

Henrik Tramberend's avatar
Henrik Tramberend committed
132
-   `decker publish`
Henrik Tramberend's avatar
Henrik Tramberend committed
133

134
135
136
    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
137
138
139
140
141

## Contributions

### Pull requests

142
143
Contributions are accepted via pull requests. Before working on a feature,
please write up an issue and discuss it with the other developers.
144
145
146

### CI build checks

147
148
149
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).
150
151
152

### Haskell source code formatting

153
154
155
156
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.