diff --git a/.gitignore b/.gitignore
index 9235563..0c9f8c1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,11 +6,10 @@
 *.fls
 *.log
 *.out
+*.toc
 *.synctex.gz
 
-# template.tex output
-# move to *.pdf once manual is done
-template.pdf
-
 # release tarballs
 moderncv-*.tar.gz
+
+examples/
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..684c2fd
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,167 @@
+.ONESHELL:
+SHELL := /bin/bash
+MODERNCVDIR =.
+MANUALDIR = $(MODERNCVDIR)/manual
+
+# version and date of the current release. This gets updated upon calling
+# either the rule version or the rule release
+VERSION = v2.1.0-40-gfe4d968-dirty
+VERSIONDATE = 2021/01/25
+# user callable NEW option, to specify the new version. If unspecified, the
+# new version gets determined by git.
+ifdef NEW
+    VERSIONNEXT = $(NEW)
+else
+    VERSIONNEXT = $(shell git describe --tags --dirty)
+endif
+VERSIONDATENEXT = $(shell date +"%Y\/%m\/%d")
+TARBALL=moderncv-$(VERSIONNEXT).tar
+
+EXAMPLESDIR = examples
+# MANUALTEX is used by the userguide method that operates in the 
+# $(MANUALDIR) folder. MANUAL is used by methods operating in 
+# the $(MODERNCVDIR) folder. This is to ensuer that the userguide 
+# is also buildable within the manual folder.
+MANUALTEX = moderncv_userguide.tex
+MANUAL = $(MANUALDIR)/$(MANUALTEX)
+TEMPLATE = $(MODERNCVDIR)/template.tex
+TEMPLATEBIB = publications.bib
+TEMPLATEBASE = $(basename $(TEMPLATE))
+TEMPLATEPDF = $(addsuffix .pdf,$(TEMPLATEBASE))
+MANUAL_BASE = $(basename $(MANUAL))
+MANUALPDF = $(addsuffix .pdf,$(MANUAL_BASE))
+
+# redefine the template rule depending on whether the user has specified STYLE
+# or not.
+ifdef STYLE
+	# in this case user has specified STYLE
+else
+	STYLE = casual
+endif
+template: $(TEMPLATE) $(TEMPLATEBIB)
+	if [[ $(strip $(STYLE)) == "casual" ]]; then
+		# build template in default style
+		latexmk -pdflua -bibtex -quiet "$<"
+	else
+		# build template in style $(STYLE). This assumes that casual is the default.
+		sedstring="s/moderncvstyle{casual}/moderncvstyle{$(STYLE)}/g"
+		sed -i $$sedstring $(TEMPLATE)
+		# build template in specified style
+		latexmk -pdflua -bibtex -quiet "$<"
+		# reset template to default value
+		sedstring="s/moderncvstyle{$(STYLE)}/moderncvstyle{casual}/g"
+		sed -i $$sedstring $(TEMPLATE)
+	fi
+
+
+templates: $(TEMPLATE) $(TEMPLATEBIB)
+	# build the template for each style and store pdfs in the examples folder
+	# this is done to include these expamples in release tar balls.
+	mkdir -p $(EXAMPLESDIR)
+	previousstyle="casual"
+	for style in casual classic banking oldstyle fancy; do
+		sedstring="s/moderncvstyle{$$previousstyle}/moderncvstyle{$$style}/g"
+		sed -i $$sedstring $(TEMPLATE)
+		latexmk -pdflua -bibtex -quiet $(TEMPLATE)
+		cp $(TEMPLATEPDF) $(EXAMPLESDIR)/$(TEMPLATEBASE)-$$style.pdf
+		mv $(TEMPLATEPDF) $(MANUALDIR)/$(TEMPLATEBASE)-$$style.pdf
+		previousstyle=$$style
+		unset sedstring
+	done
+	sedstring="s/moderncvstyle{$$previousstyle}/moderncvstyle{casual}/g"
+	sed -i $$sedstring $(TEMPLATE)
+
+
+userguide: templates $(MANUAL)
+	# build the user guide. Since the guide includes the template examples, we
+	# build those first by calling the templates rule.
+	cd $(MANUALDIR)
+	./format_files_for_userguide.py 
+	lualatex $(MANUALTEX)
+	lualatex $(MANUALTEX)
+	cd ..
+
+
+version:
+	# Upate version information and date of all moderncv files. A call make version
+	# will define VERSIONNEXT=$(shell git describe --tags). Alternatively, call
+	# "make version NEW=v5.13.298" to set v5.13.298 as the new version number.
+	# The date gets calculated by the date function.
+	if [[ $(strip $(VERSION)) == $(strip $(VERSIONNEXT)) ]]; then
+		echo "Old version number $(VERSION)  same as new version number $(VERSIONNEXT)"
+		echo "nothing to do, aborting."
+	else
+		# we need to split the $(VERSION) date format into substrings to using
+		# sed. This is due to / being a special character in sed.
+		YEAR=$(shell echo $(VERSIONDATE) | cut -d "/" -f 1)
+		MONTH=$(shell echo $(VERSIONDATE) | cut -d "/" -f 2)
+		DAY=$(shell echo $(VERSIONDATE) | cut -d "/" -f 3)
+		# update version info and date of *.sty, *.cls and *.tex files
+		# prepare find and replace with sed
+		findstr="$$YEAR\\/$$MONTH\\/$$DAY $(VERSION)"
+		replacestr="$(VERSIONDATENEXT) $(VERSIONNEXT)"
+		for currentdir in $(MODERNCVDIR) $(MANUALDIR); do
+			for file in $$currentdir/*.cls $$currentdir/*.sty $$currentdir/*.tex; do
+				if [[ -f "$$file" ]] && [[ ! -h "$$file" ]]; then
+					echo "updating version info of file $$file to $(VERSIONNEXT) (was $(VERSION))";
+					sed -i "s/$$findstr/$$replacestr/g" $$file;
+					# update version info in the title of documentation
+					sed -i "s/Package version $(VERSION)}/Package version $(VERSIONNEXT)}/g" $$file;
+				fi
+			done
+		done
+		unset findstr; unset replacestr
+		# update VERSION and VERSIONDATE variable of this very file
+		sed -i "s/VERSION = $(VERSION)/VERSION = $(VERSIONNEXT)/g" $(MODERNCVDIR)/Makefile
+		findstr="VERSIONDATE = $$YEAR\\/$$MONTH\\/$$DAY"
+		replacestr="VERSIONDATE = $(shell date +"%Y")\\/$(shell date +"%m")\\/$(shell date +"%d")"
+		sed -i "s/$$findstr/$$replacestr/g" $(MODERNCVDIR)/Makefile
+		unset findstr; unset replacestr
+	fi
+
+tarball:
+	# build a tarball for release puposes. If the examples directory exist,
+	# include them
+	# remove existing tarballs
+	rm -f *.gz *.tar
+	# create tar with all files in git repo
+	git archive HEAD > $(TARBALL)
+	# remove git specific files
+	tar -f $(TARBALL) --delete .github/ .gitignore create-release-tarball.sh
+	# if examples exist include them in the tarball
+	if [[ -d "$(EXAMPLESDIR)" ]]; then
+		tar -rf $(TARBALL) --append $(EXAMPLESDIR)
+	fi
+	# include precompiled template pdfs and userguide from manual folder,
+	# the idea being that the userguide can be build from the manual folder
+	# and has everything that it needs to compile. If the release method gets
+	# called this ensures that a precompiled version of the userguide is
+	# included in the tar ball.
+	tar -rf $(TARBALL) --append $(MANUALDIR)
+	# compress
+	gzip $(TARBALL)
+
+release: userguide version clean tarball
+
+#.PHONY: clean
+clean:
+	for dir in $(MODERNCVDIR) $(MANUALDIR); do
+		echo cleaning directory $$dir
+		cd $$dir/
+		rm -fv *.acn *.acr *.alg *.aux *.bcf *.blg *.dvi *.fdb_latexmk *.fls;
+		rm -fv *.glg *.idx *.ilg *.ist *.spl *.lof *.log *.lot *.out *.pdfsync;
+		rm -fv *.run.xml *.snm *.synctex.gz *.tdo *.toc *.vrb *blx.bib *~;
+		if [[ "$$dir" != "." ]]; then
+			cd ..
+		fi
+	done
+
+delete:
+	rm -fv $(TEMPLATEPDF)
+	rm -fv $(MANUALPDF)
+
+deleteexamples:
+	rm -rfv $(EXAMPLESDIR)
+	rm -fv $(MANUALDIR)/*.pdf
+
+force:  delete deleteexamples userguide clean
diff --git a/README.md b/README.md
index dd8b4f9..2b18e44 100644
--- a/README.md
+++ b/README.md
@@ -2,16 +2,62 @@
 
 ## A modern curriculum vitae class for LaTeX
 
-**moderncv** provides a documentclass for typesetting curricula vitae in various styles. Moderncv aims to be both straightforward to use and customizable, providing five ready-made styles (classic, casual, banking, oldstyle and fancy) and allowing one to define his own by modifying colors, fonts, icons, etc.
+`moderncv` provides a documentclass for typesetting applications (curricula vitae and cover letters) in various styles. `moderncv` aims to be both straightforward to use and customizable, providing five ready-made styles (classic, casual, banking, oldstyle and fancy) and allowing one to define his own by modifying colors, fonts, icons, etc.
+
+### Getting started 
+Once you clone this repo have a look at some examples and build the manual to see if this package suits your needs.
+This can be done by issuing 
+```make
+make userguide
+```
+in a terminal. After completion of the compilation precompiled versions of the template in all styles can be found in the folder `examples` and 
+the user guide in the folder `manual`.  
+Alternatively get the tar ball from [CTAN](https://ctan.org/pkg/moderncv?lang=de). The examples as well as the documentation are already prebuilt in that tarball.
+
+To start working on your own application use and modify the template file `template.tex`.
+The user guide can be found in the folder `manual` and contains additional information on what the document class offers.
+
+### Makefile
+The `Makefile` supports the following rules.
+
+#### Rules for building templates and the user guide
+* `template:` Build the `moderncv` template `template.tex` with `LuaLaTeX`. This rule can be called in one of two ways: 
+  * `make template`: Build the template in casual style.
+  * `make template STYLE=<style>`: Build the template in the style specified by
+	`<style>`. `<style>` can be classic, casual, banking, oldstyle or fancy.
+
+* `templates:` Build the template `template.tex` with LuaLaTeX for _all moderncv styles_ and move resulting `pdf` files to the folder `examples/`.
+
+* `userguide:`  Build the user manual `manual/moderncv_userguide.tex` with `LuaLaTeX`. This rule calls the rule `templates` before compiling the documentation.
+
+* `clean:` Clean the clutter created by compiling of the documents.
+
+* `delete:`Delete `template.pdf` and `manual/moderncv_userguide.pdf`.
+
+* `deleteexamples:` Delete `examples/` folder and remaining template example `pdf` files in folder `manual/`.
+
+* `force:`  Force rebuilding the user guide by running the rules `delete` `deleteexamples`  `userguide` and clean `clean
+
+#### Rules intended for package maintainance
+* `version:` Update the version information (version number and date) of all `moderncv` files (*.sty, moderncv.cls, *.tex). This rule can be called in two different ways. Note, however, that it is intended to be called by the rule `release` and usually does not need to be called explicitly.
+  * `make version:` Called in this way the version number is obtained through `git describe --tags`. If this information is newer all `moderncv` files get updated. 
+  * `make version NEW=<version number>:` Optionally, the desired version number `<version number>` can be specified. 
+
+* `tarball:`  Create a new release tarball suitable for upload to CTAN. If the `example/` folder is present, it gets included in the tar archive. Similary, all `pdf` files in the `manual/` folder get included aswell. This rule is intended to be called by the rule `release` and usually does not need to be called explicitly.
+
+* `release:`Update the version information of all files including the subtitle
+  in the user guide, rebuild examples as well as the user
+  guide and create a releasable tarball including the copiled pdfs. 
+  Before runing `make release` for an actual release be sure to tag the last
+  commit with the intended version information.
 
-Most commands are defined in such a way that arguments are optional.
 
 Until a decent manual is written, one can always look in the `template.tex` file for an example. It can be compiled to pdf via `latexmk -pdf ./template.tex`.
 
 `moderncv` requires to be compiled with a Xe(La)TeX or Lua(La)TeX engine because it relies on [`academicons`]-https://ctan.org/tex-archive/fonts/academicons).
 
 ## Licence
-moderncv is licensed under the [LPPL-1.3c](https://spdx.org/licenses/LPPL-1.3c.html).
+`moderncv` is licensed under the [LPPL-1.3c](https://spdx.org/licenses/LPPL-1.3c.html).
 
 ## Origin
 Original author: Xavier Danaux <xdanaux@gmail.com><br/>
diff --git a/create-release-tarball.sh b/create-release-tarball.sh
deleted file mode 100755
index b46b7cd..0000000
--- a/create-release-tarball.sh
+++ /dev/null
@@ -1,18 +0,0 @@
-#!/bin/sh
-# script to create a tarball for the files that should be in the CTAN upload
-
-# fetch version via git
-VERSION=$(git describe --tags --dirty)
-TARBALL=moderncv-$VERSION.tar
-
-# remove existing tarballs
-rm -f $TARBALL $TARBALL.gz
-
-# create tar with all files in git repo
-git archive HEAD > $TARBALL
-
-# remove git specific files
-tar -f $TARBALL --delete .github/ .gitignore create-release-tarball.sh
-
-# compress
-gzip $TARBALL
diff --git a/manual/format_files_for_userguide.py b/manual/format_files_for_userguide.py
new file mode 100755
index 0000000..efdaefe
--- /dev/null
+++ b/manual/format_files_for_userguide.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+
+import os
+
+def create_texlist(path_to_reader: str,
+                   path_to_writer: str,
+                   list_type: str) -> None:
+    readerpath = path_to_reader
+    writerpath = path_to_writer
+    try:
+        f = open(readerpath,'r')
+    except OSError:
+        raise RuntimeError(f'Failed to open file {readerpath}.')
+    else:
+        f.close()
+
+    # remove old file
+    if os.path.exists(writerpath):
+        os.remove(writerpath)
+    with open(readerpath,'r') as reader, open(writerpath,'w') as writer:
+        writer.write('\\begin{'+f'{list_type}'+'}\n')
+        wholefile = reader.read()
+        # clean out latex commands
+        wholefile = wholefile.replace(' \\',' {\\textbackslash}')
+        sentences = wholefile.split('- ')
+        for sentence in sentences:
+            if sentence != '':
+                # writer.write('\n')
+                writer.write(f'    \item {sentence}')
+
+        writer.write('\end{'+f'{list_type}'+'}')
+
+def main():
+    kb_path = '../KNOWN_BUGS'
+    kb_tex_path = 'known_bugs.tex'
+
+    create_texlist(path_to_reader=kb_path,
+                   path_to_writer=kb_tex_path,
+                   list_type='enumerate')
+
+if __name__== "__main__":
+   main()