write-you-a-haskell/contributing.md

Contributing

As always, I rely on the perpetual kindness and goodwill of Haskellers (like you!) to help correct grammar, clarify, and fix errors.

Git Repo

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.

If you would like to add your name to CONTRIBUTORS.md submit this along with your pull request.

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.

$ git clone https://github.com/sdiehl/write-you-a-haskell.git
$ make        # Makes all html files
$ make pdf    # Makes a pdf containing all the chapters

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 allows us to include and slice fragments of code from files in the src directory.

LaTeX Macros

~~~~ {literal="latex_macros"}
~~~~

Including Whole Source Files

~~~~ {.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.

~~~~ {.haskell slice="src/parsers/parsec.hs" lower=5 upper=15}
~~~~

Math Typesetting

Equations can be included in display form:

$$
\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.

$a^2 + b^2 = c^2$

For most definitions, the aligned block is used:

$$
\begin{aligned}
e :=\ & x            & \text{Var} \\
     & \lambda x. e  & \text{Lam} \\
     & e\ e          & \text{App} \\
\end{aligned}
$$

Will generate:

\begin{aligned}
e :=\ & x            & \text{Var} \\
     & \lambda x. e  & \text{Lam} \\
     & e\ e          & \text{App} \\
\end{aligned}

Several type theory macros are also included on many pages:

$$
\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.

LaTeX

The LaTeX styling is sourced from the template.latex file, which is an extension of Pandoc's default template with some custom modifications.

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:

Reference Code

The subject of this text is largely build around the mini Haskell compiler. Several other files are included for earlier chapters.

Translations

I am also very keen to the idea of having multiple language translations, if you would like to translate the text into your native language please get in touch.