Auto merge of #70 - matthiasbeyer:paper-setup, r=matthiasbeyer

Paper setup

This branch aims for a paper setup so we can start writing down where this project should go.

The paper build is not yet included in travis, though I'd really like to do that, so @TheNeikos will you have a look? I'd like to see something like `if changes in doc/, then cd && make; else cargo...` - is this possible?

If not, how to proceed?

.travis.yml

@@ -16,10 +16,14 @@ before_script:
 
 script:
     - |
-        travis-cargo build &&
-        travis-cargo test &&
-        travis-cargo bench &&
-        travis-cargo --only stable doc
+        if [[ "doc" == $(git diff --name-only $TRAVIS_BRANCH..$TRAVIS_COMMIT | cut -d "/" -f 1 | uniq) ]]; then
+            echo "There are only changes in the ./doc directory... not doing anything"
+        else
+            travis-cargo build &&
+            travis-cargo test &&
+            travis-cargo bench &&
+            travis-cargo --only stable doc
+        fi
 
 addons:
     apt:

doc/.gitignore

@@ -0,0 +1 @@
+bin

doc/Makefile

@@ -0,0 +1,138 @@
+#
+#
+#
+# Variables
+#
+#
+#
+
+export MAKE_FLAGS=--no-print-directory
+
+export OUT=$(shell pwd)/bin
+export OUT_PDF=$(OUT)/pdf/
+export OUT_HTML=$(OUT)/html/
+
+DOCUMENT_CLASS=article
+SETTING_FONTSIZE=11pt
+
+## Source directory
+SRC_DIR=$(shell pwd)/src
+
+## CSS directory
+CSS_DIR=$(SRC_DIR)/css
+
+## All markdown files in the working directory
+export SRC=$(shell find $(SRC_DIR) -name "*.md" | sort)
+
+## Templates
+TEMPLATES=$(shell pwd)/templates
+
+DOCUMENT_SETTINGS_PDF=                           \
+	--listings                                   \
+	--variable fontsize=$(SETTING_FONTSIZE)      \
+	--variable papersize=a4paper                 \
+	--variable classoption=cleardoublepage=empty \
+	--variable classoption=index=totoc           \
+	--variable classoption=openright             \
+	--variable classoption=final                 \
+	--variable classoption=listof=nochaptergap   \
+	--variable documentclass=$(DOCUMENT_CLASS)   \
+	--variable babel-lang=english                \
+	--variable geometry=portrait
+
+DOCUMENT_SETTINGS_HTML=			\
+	--variable lang=de 			\
+	--variable lof=true			\
+	--variable lol=true			\
+	--variable lot=true			\
+	--variable toc=true			\
+	--table-of-contents			\
+	--webtex
+
+#
+#
+#
+# Binary and argument construction
+#
+#
+#
+
+ECHO_CMD=$(shell which echo)
+ECHO_ARG=-e
+ECHO=$(ECHO_CMD) $(ECHO_ARG)
+export ECHO
+
+MKDIR_CMD=$(shell which mkdir)
+MKDIR_ARG=-p
+MKDIR=$(MKDIR_CMD) $(MKDIR_ARG)
+export MKDIR
+
+RM_CMD=$(shell which rm)
+RM_ARG=-fr
+RM=$(RM_CMD) $(RM_ARG)
+export RM
+
+PANDOC=$(shell which pandoc)
+
+PANDOC_PARAMS=-r markdown+simple_tables+table_captions+yaml_metadata_block+definition_lists+raw_html+markdown_in_html_blocks \
+			  --filter pandoc-crossref
+
+PANDOC_CC=$(PANDOC) $(PANDOC_PARAMS)
+
+export PANDOC_CC_PDF=$(PANDOC)        \
+			  $(PANDOC_PARAMS)        \
+			  --latex-engine=pdflatex \
+			  $(DOCUMENT_SETTINGS_PDF)
+
+export PANDOC_CC_HTML=$(PANDOC) $(PANDOC_PARAMS) $(DOCUMENT_SETTINGS_HTML)
+
+TARGET_PDF=$(OUT_PDF)/paper.pdf
+TARGET_HTML=$(OUT_HTML)/index.html
+#
+#
+# Tasks
+#
+#
+
+# Main task
+all: $(TARGET_PDF) $(TARGET_HTML)
+	@$(ECHO) "\t[ALL   ]"
+
+# create out directory
+$(OUT):
+	@$(ECHO) "\t[MKDIR ] $@"
+	@$(MKDIR) $(OUT)
+
+# create html out directory
+$(OUT_HTML): $(OUT)
+	@$(ECHO) "\t[MKDIR ] $@"
+	@$(MKDIR) $(OUT_HTML)
+
+# create html out directory
+$(OUT_PDF): $(OUT)
+	@$(ECHO) "\t[MKDIR ] $@"
+	@$(MKDIR) $(OUT_PDF)
+
+# cleanup task
+clean:
+	@$(ECHO) "\t[RM    ] $@"
+	@$(RM) $(OUT)
+
+pdf: $(TARGET_PDF)
+
+$(TARGET_PDF): $(OUT_PDF)
+	@$(ECHO) "\t[PANDOC] pdf"
+	@$(PANDOC_CC_PDF)                         \
+		--template $(TEMPLATES)/default.latex \
+		$(SRC) -o $@
+
+html: $(TARGET_HTML)
+
+$(TARGET_HTML): $(OUT_HTML)
+	@$(ECHO) "\t[PANDOC] html"
+	@$(PANDOC_CC_HTML)                        \
+		--template $(TEMPLATES)/default.html5 \
+		$(SRC) -o $@
+
+.PHONY: $(TARGET_PDF) $(TARGET_HTML)
+

doc/README.md

@@ -0,0 +1,21 @@
+# Documentation of the idea
+
+This subdirectory contains the documentation of the basic idea behind ``imag''.
+It is written in Markdown and compiled to both PDF and HTML via pandoc.
+
+# Contributing to this paper
+
+First, the paper is not build by travis-ci. This means if there are errors, they
+will be detected by me only if I build the paper. I know this is not optimal,
+but as documented in [70](https://github.com/matthiasbeyer/imag/pull/70),
+building the paper in travis would slow down the travis-ci machines too much.
+
+So if you want to contribute I would like you to build the paper, if you can.
+The dependencies you need are listed in the `default.nix` file (you don't need
+either nix nor nixos, all of these packages should be available in all major
+distros). Make sure you use pandoc `1.10+`.
+
+Contributing to this paper is done via normal pull requests, RFC-Like.
+
+That's all to it so far.
+

doc/default.nix

@@ -0,0 +1,39 @@
+{ pkgs ? (import <nixpkgs> {}) }:
+
+let
+  env = with pkgs.haskellPackages; [
+    pandoc
+    pandoc-crossref
+
+    (pkgs.texlive.combine {
+      inherit (pkgs.texlive)
+        scheme-small
+        algorithms
+        cm-super
+        collection-basic
+        collection-fontsextra
+        collection-fontutils
+        collection-langenglish
+        collection-latex
+        collection-latexextra
+        collection-latexrecommended
+        collection-mathextra
+        collection-pictures
+        collection-plainextra
+        collection-science
+      ;
+    })
+
+    pkgs.lmodern
+  ];
+in
+
+pkgs.stdenv.mkDerivation rec {
+    name = "imag-doc";
+    src = ./.;
+    version = "0.0.0";
+
+    buildInputs = [ env ];
+
+}
+

doc/src/0000.md

@@ -0,0 +1,33 @@
+---
+title: imag Project
+version: 0.1
+date: January 2016
+listings: true
+codeBlockCaptions: true
+figureTitle: "Figure"
+tableTitle: "Table"
+listingTitle: "Listing"
+titleDelimiter: ":"
+figPrefix:
+  - "Figure"
+  - "Figures"
+eqnPrefix:
+  - "Equation"
+  - "Equations"
+tblPrefix:
+  - "Table"
+  - "Tables"
+lstPrefix:
+  - "Listing"
+  - "Listings"
+secPrefix:
+  - "Section"
+  - "Sections"
+chapDelim: "."
+rangeDelim: "-"
+loftitle: "# List of Figures"
+lotTitle: "# List of Tables"
+lolTitle: "# List of Listings"
+...
+
+

doc/src/pandoc-reference

@@ -0,0 +1,170 @@
+<!--
+
+The following file is not included in the output and is just included in the
+repository as a quick reference how things are formatted with pandoc-markdown
+
+-->
+
+# Code examples {#sec:codeexamples}
+
+In @sec:codeexamples we show some code examples.
+
+```{#lst:mypython .python .numberLines caption="Python"}
+def foo():
+    return 1;
+```
+
+With some Python code in @lst:mypython
+
+
+```{#lst:myruby .ruby .numberLines caption="Ruby"}
+def foo
+    1
+end
+```
+
+With some Ruby code in @lst:myruby
+
+
+``` {#lst:myc .c .numberLines caption="C"}
+int
+foo() {
+    return 1;
+}
+```
+
+and Some C code in @lst:myc.
+
+
+Aaah, and some `C++`:
+
+``` {#mycpp .cpp .numberLines caption="C++"}
+template <typename T>
+std::tuple<T, T> mymodule::hassome::foo()
+{
+    return std::make_tuple<T, T>(1, 1);
+} // I don't even know whether this works
+```
+
+And, of course, because pandoc:
+
+~~~~ {#mycode .haskell .numberLines startFrom="100" caption="Haskell"}
+qsort []     = []
+qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
+               qsort (filter (>= x) xs)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Table examples
+
+Pandoc has several extensions for tables, we have them all here:
+
+## Simple tables
+
+This is an example for simple tables (@tbl:simple).
+
+  Right     Left     Center     Default
+-------     ------ ----------   -------
+     12     12        12            12
+    123     123       123          123
+      1     1          1             1
+
+Table:  Demonstration of simple table syntax. {#tbl:simple}
+
+-------     ------ ----------   -------
+     12     12        12             12
+    123     123       123           123
+      1     1          1              1
+-------     ------ ----------   -------
+
+And some more go here (in @tbl:more):
+
+-------------------------------------------------------------
+ Centered   Default           Right Left
+  Header    Aligned         Aligned Aligned
+----------- ------- --------------- -------------------------
+   First    row                12.0 Example of a row that
+                                    spans multiple lines.
+
+  Second    row                 5.0 Here's another one. Note
+                                    the blank line between
+                                    rows.
+-------------------------------------------------------------
+
+Table: Here's the caption. It, too, may span
+multiple lines. {#tbl:more}
+
+
+## Grid tables
+
+: Sample grid table.
+
++---------------+---------------+--------------------+
+| Fruit         | Price         | Advantages         |
++===============+===============+====================+
+| Bananas       | $1.34         | - built-in wrapper |
+|               |               | - bright color     |
++---------------+---------------+--------------------+
+| Oranges       | $2.10         | - cures scurvy     |
+|               |               | - tasty            |
++---------------+---------------+--------------------+
+
+## Pipe tables
+
+| Right | Left | Default | Center |
+|------:|:-----|---------|:------:|
+|   12  |  12  |    12   |    12  |
+|  123  |  123 |   123   |   123  |
+|    1  |    1 |     1   |     1  |
+
+  : Demonstration of pipe table syntax.
+
+
+# Some maths
+
+This is simply embedded tex. It renders both in the PDF version
+and the HTML version of the output.
+
+Greek letters are not supported by this setup, though.
+
+<!-- This way, the equation is numbered, but does not appear in the HTML -->
+\begin{equation}
+i_{a} = 15
+\end{equation}
+
+---
+
+<!-- This way, the equation is not numbered, but appears in both pdf and HTML -->
+$$ \forall x \in X, \quad \exists y \leq \epsilon $$ {#eq:foo}
+
+In @eq:foo we show something.
+
+---
+
+$$ \frac{n!}{k!(n-k)!} = \binom{n}{k} $$ {#eq:bar}
+
+---
+
+$$ \displaystyle\sum_{i=1}^{10} t_i $$ {#eq:barbar}
+
+---
+
+$$ \sum_{\substack{
+   0<i<m \\
+   0<j<n
+  }}
+ P(i,j) $$ {#eq:foofoo}
+
+---
+
+$$ P\left(A=2\middle|\frac{A^2}{B}>4\right) $$ {#eq:somethingelse}
+
+---
+
+$$ A_{m,n} =
+ \begin{pmatrix}
+  a_{1,1} & a_{1,2} & \cdots & a_{1,n} \\
+  a_{2,1} & a_{2,2} & \cdots & a_{2,n} \\
+  \vdots  & \vdots  & \ddots & \vdots  \\
+  a_{m,1} & a_{m,2} & \cdots & a_{m,n}
+ \end{pmatrix} $$ {#eq:somethingelseagain}
+

doc/templates/default.html5

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html$if(lang)$ lang="$lang$"$endif$>
+<head>
+  <meta charset="utf-8">
+  <meta name="generator" content="pandoc">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
+
+$if(date)$
+  <meta name="dcterms.date" content="$date$">
+$endif$
+
+  <title>$if(title-prefix)$$title-prefix$ - $endif$$pagetitle$</title>
+  <style type="text/css">code{white-space: pre;}</style>
+  <!--[if lt IE 9]>
+    <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
+  <![endif]-->
+
+$if(highlighting-css)$
+  <style type="text/css">
+    $highlighting-css$
+  </style>
+$endif$
+
+$for(css)$
+  <link rel="stylesheet" href="$css$">
+$endfor$
+
+</head>
+    <body style="margin-left: 20%; margin-right: 20%;">
+        $if(title)$
+            <header>
+                <h1 class="title">$title$</h1>
+                $if(date)$
+                    <small class="date">$date$</small>
+                $endif$
+
+                $if(version)$
+                    <small class="date">Version: $version$</small>
+                $endif$
+            </header>
+            <hr />
+        $endif$
+
+        $body$
+
+    </body>
+</html>

doc/templates/default.latex

@@ -0,0 +1,56 @@
+\documentclass[$if(fontsize)$$fontsize$,$endif$$if(lang)$$babel-lang$,$endif$$if(papersize)$$papersize$,$endif$$for(classoption)$$classoption$$sep$,$endfor$]{$documentclass$}
+
+\usepackage[sort]{natbib}
+\usepackage{fancyhdr}
+\usepackage{hyperref}
+\usepackage{listings}  % source code listings
+\usepackage{longtable} % tables
+\usepackage{booktabs}  % tables
+\usepackage{mathtools}
+\usepackage{enumitem}
+
+\providecommand{\tightlist}{ % pandoc wants this
+      \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}
+}
+
+\oddsidemargin 0.2cm
+\topmargin -1.0cm
+\textheight 24.0cm
+\textwidth 15.25cm
+\parindent=0pt
+\parskip 1ex
+\renewcommand{\baselinestretch}{1.1}
+\pagestyle{fancy}
+
+$if(title)$
+    \lhead{\normalsize \textrm{$title$}}
+$endif$
+
+\chead{}
+
+$if(version)$
+    \lfoot{\normalsize \textrm{$version$}}
+$endif$
+\cfoot{}
+
+$if(date)$
+    \rfoot{$date$}
+$endif$
+
+$for(header-includes)$
+    $header-includes$
+$endfor$
+
+\setlength{\fboxrule}{4pt}\setlength{\fboxsep}{2ex}
+\renewcommand{\headrulewidth}{0.4pt}
+\renewcommand{\footrulewidth}{0.4pt}
+
+\begin{document}
+
+    \begin{center}
+        {\bf $title$}
+    \end{center}
+
+    $body$
+
+\end{document}