readme.md 7.38 KB
Newer Older
monofon's avatar
monofon committed
1
2
[![pipeline
status](https://gitlab2.informatik.uni-wuerzburg.de/decker/decker/badges/master/pipeline.svg)](https://gitlab2.informatik.uni-wuerzburg.de/decker/decker/commits/master)
Henrik Tramberend's avatar
Henrik Tramberend committed
3

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

A markdown based tool for slide deck creation.

8
9
## Installation

10
Pick a [published release](), download and unpack:
11

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

## Installation from source

19
1.  Install [stack](https://docs.haskellstack.org/en/stable/README/), [Node.js](https://www.npmjs.com/get-npm) (for `npm`) and [sassc](https://github.com/sass/sassc) (Mac: `brew install sassc`, Linux: available for most package managers)
20
2.  Clone this repo.
Henrik Tramberend's avatar
Henrik Tramberend committed
21
3.  `cd decker`
22
23
4.  `git submodule update --init --recursive`
5.  `make install`
24

25
26
27
28
29
30
31
32
33
34
35
36
37
38
## 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"```


monofon's avatar
monofon committed
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
## 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.

Henrik Tramberend's avatar
Henrik Tramberend committed
56
57
58
59
## External tools

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

60
-   [*ssh*](https://www.openssh.com) for publishing slide decks and resources
61
62
63
64
65
66
67
68
-   [*rsync*](http://formulae.brew.sh/repos/Homebrew/homebrew-core/formula/rsync)
    for publishing slide decks and resources
-   [*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
69
-   *libbzip2-dev*
70
-   [*NodeJS*](https://nodejs.org/) to install JavaScript dependencies
Armin Bernstetter's avatar
Armin Bernstetter committed
71
-   [*coreutils*](https://www.gnu.org/software/coreutils/) the GNU coreutils
72
73
74
75
76
77

### Installation of external tools on macOS

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

``` {.sh}
78
brew install rsync graphviz gnuplot pdf2svg yarn coreutils
79
80
81
82
```

For the rest follow instructions on their respective webites.

83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
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)](https://ubuntu.com/server/docs/package-management) to install external tools. 

``` {.sh}
apt-get update && apt-get install -y gnuplot graphviz libbz2-dev pdf2svg rsync ssh      
```

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

`decker check`

Henrik Tramberend's avatar
Henrik Tramberend committed
99
100
## Usage

101
102
103
104
*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
105

Henrik Tramberend's avatar
Henrik Tramberend committed
106
-   `*-deck.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
107

108
109
    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
110
111

    -   `*-deck.html` A reveal.js based slide show
112
113
    -   `*-handout.hmtl` A HTML document containing the speaker notes to the
        slide show.
Henrik Tramberend's avatar
Henrik Tramberend committed
114
115
116
    -   `*-deck.pdf` A PDF version of the slide show
    -   `*-handout.pdf` A PDF version of the handout

Henrik Tramberend's avatar
Henrik Tramberend committed
117
-   `*-page.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
118

119
120
    Markdown files ending on `*-page.md` are translated into corresponding HTML
    or PDF documents.
Henrik Tramberend's avatar
Henrik Tramberend committed
121
122
123

## *decker* targets

124
125
-   `decker version`

monofon's avatar
monofon committed
126
127
    Prints the current decker version and branch as well as the current pandoc
    version.
128

Henrik Tramberend's avatar
Henrik Tramberend committed
129
-   `decker help`
Henrik Tramberend's avatar
Henrik Tramberend committed
130

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

133
134
-   `decker info`

monofon's avatar
monofon committed
135
136
    Prints information about the current project's directories, the targets
    (files which will be generated) and the meta data options which are found in
137
    top level `decker.yaml` file.
138

Henrik Tramberend's avatar
Henrik Tramberend committed
139
140
141
142
-   `decker html`

    Builds HTML versions of all available documents.

143
144
145
146
-   `decker decks`

    Builds only HTML slide decks.

Henrik Tramberend's avatar
Henrik Tramberend committed
147
-   `decker pdf`
Henrik Tramberend's avatar
Henrik Tramberend committed
148

monofon's avatar
monofon committed
149
    Builds PDF versions of all documents.
Henrik Tramberend's avatar
Henrik Tramberend committed
150

Henrik Tramberend's avatar
Henrik Tramberend committed
151
152
-   `decker pdf-decks`

Armin Bernstetter's avatar
Armin Bernstetter committed
153
    Builds PDF versions of all slide decks.
Henrik Tramberend's avatar
Henrik Tramberend committed
154

monofon's avatar
monofon committed
155
156
157
158
159
160
161
162
163
164
    To use `decker pdf` or `decker pdf-decks`, Google Chrome has to be
    installed.\
    **Windows:** Currently `decker pdf` does not work on Windows. Please add
    `print: true` or `menu: true` to your slide deck and use the print button in
    the menu or on the title slide. **MacOS:** Follow the Google Chrome
    installer instructions. **Google Chrome.app** has to be located in either
    `/Applications/Google Chrome.app` or
    `/Users/username/Applications/Google Chrome.app` Alternatively you can add
    `chrome` to `$PATH`.\
    **Linux:** `chrome` has to be on `$PATH`.
165

Henrik Tramberend's avatar
Henrik Tramberend committed
166
-   `decker watch`
Henrik Tramberend's avatar
Henrik Tramberend committed
167

168
169
170
    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
171

Henrik Tramberend's avatar
Henrik Tramberend committed
172
-   `decker server`
Henrik Tramberend's avatar
Henrik Tramberend committed
173

174
175
176
    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
177

Henrik Tramberend's avatar
Henrik Tramberend committed
178
-   `decker example`
Henrik Tramberend's avatar
Henrik Tramberend committed
179

180
181
    Write a few example files to the current directory. To start exploring
    decker type
Henrik Tramberend's avatar
Henrik Tramberend committed
182
183
184
185
186
187

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

188
    and make some changes to the Markdown files. `example-deck.md` contains the
monofon's avatar
monofon committed
189
190
    source code for a slide deck that explains most of the available features
    for creating slide decks.
Henrik Tramberend's avatar
Henrik Tramberend committed
191

192
-   `decker clean`
Henrik Tramberend's avatar
Henrik Tramberend committed
193

monofon's avatar
monofon committed
194
195
196
    Recursively removes all generated files from the current directory (i.e. the
    `public` folder). Also removes cached resources witch version number lower
    than the current version.
Henrik Tramberend's avatar
Henrik Tramberend committed
197

Henrik Tramberend's avatar
Henrik Tramberend committed
198
-   `decker publish`
Henrik Tramberend's avatar
Henrik Tramberend committed
199

200
201
202
    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
203
204
205
206
207

## Contributions

### Pull requests

208
Contributions are accepted via pull requests. Before working on a feature,
monofon's avatar
monofon committed
209
210
211
please write up an issue and discuss it with the other developers. For each
implemented feature, increment the version number in `package.yaml`. Breaking
changes increment the second number. Fixes increment the third number.
212
213
214

### CI build checks

215
216
217
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).
218
219
220

### Haskell source code formatting

221
222
223
224
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.