2015-01-19 05:04:01 +03:00
|
|
|
Contributing
|
|
|
|
============
|
|
|
|
|
2015-01-06 18:09:41 +03:00
|
|
|
As always, I rely on the perpetual kindness and goodwill of Haskellers (like
|
|
|
|
you!) to help correct grammar, clarify, and fix errors.
|
|
|
|
|
|
|
|
Git Repo
|
|
|
|
--------
|
|
|
|
|
2015-01-11 23:25:47 +03:00
|
|
|
*Simple Fixes*
|
|
|
|
|
|
|
|
For most fixes you can simply edit the Markdown files at the toplevel of the Git
|
|
|
|
repo and then submit a pull request on Github. There should be no need to
|
|
|
|
compile the text locally. I will try to merge the changes quickly and rebuild
|
|
|
|
the text daily.
|
|
|
|
|
2015-01-19 05:04:01 +03:00
|
|
|
If you would like to add your name to
|
|
|
|
[CONTRIBUTORS.md](https://github.com/sdiehl/write-you-a-haskell/blob/master/CONTRIBUTORS.md)
|
|
|
|
submit this along with your pull request.
|
|
|
|
|
2015-01-11 23:25:47 +03:00
|
|
|
*Complex Fixes*
|
|
|
|
|
|
|
|
If you'd like to submit a change to the publishing software around the text,
|
|
|
|
then clone the repo. You will need a local copy of Pandoc library to use the
|
|
|
|
build system.
|
|
|
|
|
2015-01-06 18:09:41 +03:00
|
|
|
```bash
|
2015-01-06 18:41:04 +03:00
|
|
|
$ git clone https://github.com/sdiehl/write-you-a-haskell.git
|
2015-01-08 05:28:56 +03:00
|
|
|
$ make # Makes all html files
|
|
|
|
$ make pdf # Makes a pdf containing all the chapters
|
2015-01-06 18:09:41 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
Pandoc
|
|
|
|
------
|
|
|
|
|
|
|
|
The text is written in the Markdown language and handled with the Pandoc
|
|
|
|
processing library, which is itself written in Haskell!
|
|
|
|
|
|
|
|
The tutorial uses a custom pandoc preprocessor contained in *includes.hs*. This
|
2015-01-11 23:25:47 +03:00
|
|
|
allows us to include and slice fragments of code from files in the src
|
|
|
|
directory.
|
2015-01-06 18:09:41 +03:00
|
|
|
|
|
|
|
*LaTeX Macros*
|
|
|
|
|
|
|
|
```perl
|
|
|
|
~~~~ {literal="latex_macros"}
|
|
|
|
~~~~
|
|
|
|
```
|
|
|
|
|
|
|
|
*Including Whole Source Files*
|
|
|
|
|
|
|
|
```perl
|
|
|
|
~~~~ {.haskell include="includes.hs"}
|
|
|
|
~~~~
|
|
|
|
```
|
|
|
|
|
|
|
|
*Including Partial Source Files*
|
|
|
|
|
|
|
|
Will slice the lines 5-15 inclusively from the file *parsec.hs* with the Haskell
|
|
|
|
syntax highlighting.
|
|
|
|
|
|
|
|
```perl
|
|
|
|
~~~~ {.haskell slice="src/parsers/parsec.hs" lower=5 upper=15}
|
|
|
|
~~~~
|
|
|
|
```
|
|
|
|
|
|
|
|
*Math Typesetting*
|
|
|
|
|
2015-01-19 05:04:01 +03:00
|
|
|
Equations can be included in display form:
|
|
|
|
|
|
|
|
```latex
|
|
|
|
$$
|
|
|
|
\int_\Omega \mathrm{d}\omega = \oint_{\partial \Omega} \omega
|
|
|
|
$$
|
|
|
|
```
|
|
|
|
|
|
|
|
$$
|
|
|
|
\int_\Omega \mathrm{d}\omega = \oint_{\partial \Omega} \omega
|
|
|
|
$$
|
|
|
|
|
|
|
|
Or in inline form (like $a^2 + b^2 = c^2$) with single dollar signs. Specially
|
|
|
|
there must be no spaces around the dollar signs otherwise Pandoc will not parse
|
|
|
|
it properly.
|
|
|
|
|
|
|
|
```latex
|
|
|
|
$a^2 + b^2 = c^2$
|
|
|
|
```
|
|
|
|
|
|
|
|
For most definitions, the ``aligned`` block is used:
|
|
|
|
|
2015-01-06 18:09:41 +03:00
|
|
|
```latex
|
|
|
|
$$
|
2015-01-08 05:30:14 +03:00
|
|
|
\begin{aligned}
|
|
|
|
e :=\ & x & \text{Var} \\
|
|
|
|
& \lambda x. e & \text{Lam} \\
|
2015-01-06 18:09:41 +03:00
|
|
|
& e\ e & \text{App} \\
|
2015-01-08 05:30:14 +03:00
|
|
|
\end{aligned}
|
2015-01-06 18:09:41 +03:00
|
|
|
$$
|
|
|
|
```
|
|
|
|
|
|
|
|
Will generate:
|
|
|
|
|
|
|
|
$$
|
2015-01-08 05:30:14 +03:00
|
|
|
\begin{aligned}
|
|
|
|
e :=\ & x & \text{Var} \\
|
|
|
|
& \lambda x. e & \text{Lam} \\
|
2015-01-06 18:09:41 +03:00
|
|
|
& e\ e & \text{App} \\
|
2015-01-08 05:30:14 +03:00
|
|
|
\end{aligned}
|
2015-01-06 18:09:41 +03:00
|
|
|
$$
|
|
|
|
|
|
|
|
Several type theory macros are also included on many pages:
|
|
|
|
|
|
|
|
```latex
|
|
|
|
$$
|
|
|
|
\infrule{ 0 : \t{nat}}{\infrule{\t{succ}(0) : \t{nat}}{ \t{succ}(\t{succ}(0)) : \t{nat} }}
|
|
|
|
$$
|
|
|
|
```
|
|
|
|
|
|
|
|
Will generate:
|
|
|
|
|
|
|
|
$$
|
|
|
|
\infrule{ 0 : \t{nat}}{\infrule{\t{succ}(0) : \t{nat}}{ \t{succ}(\t{succ}(0)) : \t{nat} }}
|
|
|
|
$$
|
|
|
|
|
|
|
|
Typography
|
|
|
|
----------
|
|
|
|
|
|
|
|
* Body is the system sans serif default preferring *Helvetica Neue Regular* or
|
|
|
|
*Arial* if available.
|
|
|
|
* Subtitles are in *Signika*.
|
|
|
|
* Titles are in *Helvetica Neue Light*.
|
|
|
|
* Code is typeset in *Inconsolata* or *Monaco*.
|
|
|
|
|
2015-01-11 23:25:47 +03:00
|
|
|
LaTeX
|
|
|
|
-----
|
|
|
|
|
2015-01-19 05:04:01 +03:00
|
|
|
The LaTeX styling is sourced from the ``template.latex`` file, which is an
|
2015-01-11 23:25:47 +03:00
|
|
|
extension of Pandoc's default template with some custom modifications.
|
|
|
|
|
2015-01-06 18:09:41 +03:00
|
|
|
Images
|
|
|
|
------
|
|
|
|
|
|
|
|
The images are drawn in SVG using Inkscape.
|
|
|
|
|
|
|
|
Graphs and blocks diagrams are generated using graphviz.
|
|
|
|
|
|
|
|
Preprocessor
|
|
|
|
------------
|
|
|
|
|
|
|
|
The source for the preprocessor is a simple bottom-up traversal replacement of
|
|
|
|
these custom markdown extensions:
|
|
|
|
|
|
|
|
~~~~ {.haskell include="includes.hs"}
|
|
|
|
~~~~
|
|
|
|
|
|
|
|
Reference Code
|
|
|
|
--------------
|
|
|
|
|
|
|
|
The subject of this text is largely build around the mini Haskell compiler.
|
|
|
|
Several other files are included for earlier chapters.
|