---
title: "Generating MariaDB MaxScale PDF and HTML Documentation"
publish_date: 2016-04-19
updated_date: 2019-08-20
author: "Markus Mäkelä"
---

# Generating MariaDB MaxScale PDF and HTML Documentation

I![MaxScale0907015_0.png](/sites/default/files/pictures/Images/MaxScale0907015_0.png) was recently talking on the #mariadb channel on FreeNode and I got a question about the often overlooked PDF documentation generation. In this blog I will show how to create a set of PDF files of the MariaDB MaxScale’s documentation – a good way to keep the documentation handy. I did this on Ubuntu 14.04, but it should also work on other platforms.

## Installing Packages

Since we’ll be configuring MariaDB MaxScale, we’ll need to install a few dependencies for MariaDB MaxScale and also grab the MariaDB server tarball. We start by installing the following packages.

```
sudo apt-get install git build-essential libssl-dev libaio-dev ncurses-dev bison flex cmake perl libtool libcurl4-openssl-dev libpcre3-dev tcl tcl-dev
```

Then we’ll get the MariaDB server tarball which contains all the required parts for MariaDB MaxScale and extract it into our home directory.

```
wget --content-disposition https://downloads.mariadb.org/f/mariadb-10.0.24/bintar-linux-glibc_214-x86_64/mariadb-10.0.24-linux-glibc_214-x86_64.tar.gz/from/http%3A//mirror.netinch.com/pub/mariadb/?serve
tar -axf  mariadb-10.0.24-linux-glibc_214-x86_64.tar.gz
```

MariaDB MaxScale uses Pandoc and Latex to generate the PDF documentation from the raw Markdown files. This means that we’ll have to install the following extra packages.

```
sudo apt-get install pandoc texlive texlive-xetex texlive-latex-extra
```

After installing these packages, we need to clone the MariaDB MaxScale repo, check out the 1.4.1 tag and create a directory where we can generate the PDF documentation.

```
git clone https://github.com/mariadb-corporation/MaxScale.git
git -C MaxScale checkout 1.4.1
mkdir build
cd build
```

## Creating PDF Documentation

The final step is to configure MaxScale and run the `generate_pdf`target. Since we used the binary tarball, we’ll need to define the paths to various files in the extracted tarball in our home directory.

```
cmake ../MaxScale -DERRMSG=$HOME/mariadb-10.0.24-linux-x86_64/share/english/ 
-DMYSQL_EMBEDDED_LIBRARIES=$HOME/mariadb-10.0.24-linux-x86_64/lib/libmysqld.a 
-DMYSQL_EMBEDDED_INCLUDE_DIR=$HOME/mariadb-10.0.24-linux-x86_64/include/
```

After configuration, the only thing we need to do is to generate the actual PDF documentation.

```
make generate_pdf
```

After the generation is complete, all the PDF files can be found in the `pdf/` directory.

## Alternative HTML Documentation

MariaDB MaxScale can also create HTML documentation from the Markdown files. Creating it is as simple as running the `make generate_html target`.

```
make generate_html
```

This will create HTML documentation in the` html/ `directory.

And there we go, two different types of documentation ready for use. Although the contents of the PDF and HTML documents aren’t as smooth as [MariaDB MaxScale’s Knowledge Base Articles](https://staging-mdb.com/kb/en/mariadb-enterprise/mariadb-maxscale/), they can be a good substitute when browsing on a mobile device or when Internet access isn’t available.