Haskell/Style conventions

This page documents some of the style conventions in use through the Haskell wikibook. Before we start, a few important remarks.

  • This page will have examples for most of the conventions present; so if you have doubts on how to add them to a page, just click edit and check the wikitext source.
  • At present many of the conventions here are still in flux; and there are several inconsistencies accumulated over the years around the book (we will point out some of the most annoying ones). You can use the talk page to voice your opinions about such issues and bring them closer to resolution.
  • Last, but not least: do not bite newcomers over these conventions! Not only because several of the points are not set in stone, but also because making a fuss about them would generally be counter-productive - new editors who stick around will get used to the main conventions soon enough.

Code samplesEdit

The one stable convention about code samples is to use <source lang="haskell"></source> blocks for samples in source files and <code></code> blocks for GHCi samples:

numOfSolutions a b c
    | disc > 0  = 2
    | disc == 0 = 1
    | otherwise = 0
        where
        disc = b^2 - 4*a*c
Prelude> (2 + 2 == 5) || (2 > 0)
True
Prelude> (||) (18 == 17) (9 >= 11)
False

The main difference is that source blocks have syntax highlighting, while pre blocks do not (the highlighting does not fit well with GHCi samples). Large sections of the book still do not follow this basic convention, but that is slowly being corrected (you can help with that if you find non-conforming passages).

Example templatesEdit

Beyond the basic tags, there are also the example templates - Template:HaskellExample, Template:HaskellGHCi and Template:HaskellGHCiExample - click the links to see usage instructions. As of now, these are used mostly on the first few chapters of the book. There are a few issues with the usage of such templates. In most places all they add is a caption to the examples, which is not too useful given the lack of an index of examples, plus some extra indentation to the block atop the already distinctive layout of pre/source blocks (but cf. this discussion about the semantics of example blocks). Furthermore, their handling is annoying to editors - not just due to verbosity, but also due to the issues with escaping special characters (see Template:! and Template:=) which make adding source and pre tags automatically with the template more trouble than it is worth. Due to these issues, there is recurring talk of eliminating example templates altogether, but thus far no editor was bold enough to push in one direction or the other.

Inline codeEdit

Inline code samples like 2 + 2 == 4 should be within <code></code> tags (tt tags are used for that purpose in several places; they are gradually being converted to code tags). A minor technicality is that lists within lists such as [['a','b'],"c"] should be wrapped in nowiki tags inside the code tags - otherwise MediaWiki or other renderers might process the double square brackets as wikilinks.

Navigational templatesEdit

TODO: Template:Haskell minitoc, Template:Haskell navigation and the chapter templates.

Notes and referencesEdit

We make liberal use of footnotes as a way to present brief but distracting digressions, external references and pointers to chapters later in the book. References should be added at the point they are anchored in the text, within <ref></ref> tags, like this one[1]. If a page has footnotes, Template:Haskell/NotesSection should be added to the bottom of the page, between the last section and the navigational templates at the very bottom.

Note

For longer digressions, create a body note like this one with Template:Body note. It would be wise not to have too many of these in a single page...


LinksEdit

Hyperlinks can be useful, but should be used with discretion - since a wikibook is in essence still a book, it should not rely too heavily on external content and also be useful and easy to navigate in a printed version. Internal links within the book are less problematic than external links, but it is better to make to what the link points explicit (that is, "as we will see in More about lists" is better than "as we will see a few chapters ahead"). TODO: Mention Template:Haskell lib, and when it is better to move a link to a footnote.

Exercises and solutionsEdit

TODO: Template:Exercises and solution pages.

MiscellaneousEdit

TODO: math tags, clear templates and other small tricks.


NotesEdit

  1. foobar
Last modified on 3 May 2012, at 05:58