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.

Capitalization

Chapter names and headers (section names) must follow sentence casing.

Code samples

Code blocks are wrapped in <syntaxhighlight lang="haskell"></syntaxhighlight> tags.

numOfSolutions a b c
    | disc > 0  = 2
    | disc == 0 = 1
    | otherwise = 0
        where
        disc = b^2 - 4*a*c

We used to prefer plain <code></code> for GHCi samples due to syntax highlighting infelicities. Since the move to pygments-based highlighting, however, that is not a concern anymore.

Example templates

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 code

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 templates

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

Notes and references

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

Links

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 Lists II" 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 solutions

TODO: Template:Exercises and solution pages.

Miscellaneous

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