readme.md 6.65 KB
Newer Older
Henrik Tramberend's avatar
Henrik Tramberend 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 4 5 6
# decker

A markdown based tool for slide deck creation.

7 8
## Installation

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

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`
21
4.  `make install`
22

Henrik Tramberend's avatar
Henrik Tramberend committed
23 24 25 26
## External tools

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

27
-   [*ssh*](https://www.openssh.com) for publishing slide decks and resources
28 29 30 31 32 33 34 35 36 37 38 39
-   [*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
40
-   *libbzip2-dev*
41 42
-   [*NodeJS*](https://nodejs.org/) as a prerequisite for Yarn
-   [*Yarn*](https://yarnpkg.com) to install Javascript dependencies
43 44 45 46 47 48

### Installation of external tools on macOS

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

``` {.sh}
Samantha Monty's avatar
Samantha Monty committed
49
brew install rsync unzip graphviz gnuplot pdf2svg yarn
50 51 52 53
```

For the rest follow instructions on their respective webites.

Henrik Tramberend's avatar
Henrik Tramberend committed
54 55
## Usage

56 57 58 59
*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
60

Henrik Tramberend's avatar
Henrik Tramberend committed
61
-   `*-deck.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
62

63 64
    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
65 66

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

Henrik Tramberend's avatar
Henrik Tramberend committed
72
-   `*-page.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
73

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

77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
### Docker container

We provide prebuild docker containers. You may use them in a directory to build the html slides with 

```
docker run --rm -it -v `pwd`:/decker -p 8888:8888 gitlab2.informatik.uni-wuerzburg.de:4567/decker/decker html
```

or for Windows

```
docker run --rm -it -v %cd%:/decker -p 8888:8888 gitlab2.informatik.uni-wuerzburg.de:4567/decker/decker html
```

Exchange the `html` at the end of the command with your *decker* command of choice. Beware that file updates are not propagated into the container so `decker server` will not auto refresh.

Henrik Tramberend's avatar
Henrik Tramberend committed
93 94
## *decker* targets

Henrik Tramberend's avatar
Henrik Tramberend committed
95
-   `decker help`
Henrik Tramberend's avatar
Henrik Tramberend committed
96

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

Henrik Tramberend's avatar
Henrik Tramberend committed
99 100 101 102 103
-   `decker html`

    Builds HTML versions of all available documents.

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

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

Henrik Tramberend's avatar
Henrik Tramberend committed
108 109 110
-   `decker pdf-decks`

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

Armin Bernstetter's avatar
Armin Bernstetter committed
112 113 114
    To use `decker pdf` or `decker pdf-decks`, Google Chrome has to be installed.    
    **Windows:** Follow the Google Chrome installer instructions.  
    **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`
Armin Bernstetter's avatar
Armin Bernstetter committed
115
    Alternatively you can add `chrome` to `$PATH`.  
Armin Bernstetter's avatar
Armin Bernstetter committed
116
    **Linux:** `chrome` has to be on `$PATH`.    
117

Henrik Tramberend's avatar
Henrik Tramberend committed
118
-   `decker watch`
Henrik Tramberend's avatar
Henrik Tramberend committed
119

120 121 122
    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
123

Henrik Tramberend's avatar
Henrik Tramberend committed
124
-   `decker server`
Henrik Tramberend's avatar
Henrik Tramberend committed
125

126 127 128
    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
129

Henrik Tramberend's avatar
Henrik Tramberend committed
130
-   `decker example`
Henrik Tramberend's avatar
Henrik Tramberend committed
131

132 133
    Write a few example files to the current directory. To start exploring
    decker type
Henrik Tramberend's avatar
Henrik Tramberend committed
134 135 136 137 138 139

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

140 141 142
    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
143

Henrik Tramberend's avatar
Henrik Tramberend committed
144
-   `decker clean`
Henrik Tramberend's avatar
Henrik Tramberend committed
145 146

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

Henrik Tramberend's avatar
Henrik Tramberend committed
148
-   `decker plan`
Henrik Tramberend's avatar
Henrik Tramberend committed
149

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

Henrik Tramberend's avatar
Henrik Tramberend committed
152
-   `decker meta`
Henrik Tramberend's avatar
Henrik Tramberend committed
153

154 155 156
    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
157

Henrik Tramberend's avatar
Henrik Tramberend committed
158
-   `decker publish`
Henrik Tramberend's avatar
Henrik Tramberend committed
159

160 161 162
    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
163 164 165 166 167

## Contributions

### Pull requests

168
Contributions are accepted via pull requests. Before working on a feature,
169 170 171
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.
172 173 174

### CI build checks

175 176 177
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).
178 179 180

### Haskell source code formatting

181 182 183 184
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.
185 186 187

## Compile Flags
The Decker executable contains per default all necessary supporting files and extracts them on the first run. Some packaging solutions prefer to already extract the files during the installation. To support this, a compile flag `preextractedresources` is available which instructs Decker to work with the already extracted resource files. Invoke `stack --flag decker:preextractedresources` to compile such a version.