Skip to content

Latest commit

 

History

History
137 lines (99 loc) · 3.07 KB

contributing.md

File metadata and controls

137 lines (99 loc) · 3.07 KB

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.

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

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