[Haskell-cafe] Haddock changes pushed upstream

[Mateusz Kowalczyk]

Hi all,

As some of you might know, I hacked on Haddock over summer as part of
GSOC. After some tedious fighting with GHC validation process and help
of the guys on ghc-devs, the changes were finally pushed upstream couple
of hours ago. While I'm waiting for the maintainer to make a call on the
official release, you can already get the changes if you compile GHC HEAD.

For those not so eager about compiling HEAD, 7.8 should be coming out
the changes will be in that. You can read the brief changelog at [1] and
the updated documentation at [2].

We were careful to not make changes to any existing syntax that would
result in a large amount of packages breaking. If you're a package
maintainer, here are some things to consider:

* If your documentation looks fine how it is now, you're probably fine.
Read the changelog[1] as it mentions some issues that were fixed.
Amongst others, Haddock will now link qualified function names properly
so that's something to look out for.

* none of your documentation should get parse failures: any
previously-failing documentation should now be displayed. This means
that if you have parse failures, now is the time to go and fix them up
or your documentation probably won't look pretty. On an upside, this
means that we won't have whole Hackage packages missing documentation
due to a minor mistake in one of the comments.

* You no longer need to break up lists of the same type with newlines.
Previously you'd get two lists merged on a single line in an incoherent
mess. Now it'll be rendered properly. I know that even GHC documentation
is guilty of this mistake.

* You can now escape the markup properly. Before, you were very limited
on how the markup could be escaped. For example, <<foo ba\>r>> would
result in a parse failure.

* Bold markup added. The syntax is two underscores around what you want
bold. Note, we still do not support multi-line markup. It's possible but
it's a design choice not to support it.

* You previously have gotten a document coverage report. We now have
--print-missing-docs flag which will also tell you where the
undocumented entities are:

```
✓ misaki shana % haddock -h -U F.hs --print-missing-docs -o .
Haddock coverage:
  33% (  2 /  6) in 'F'
  Missing documentation for:
    Baz (F.hs:5)
    Bar (F.hs:6)
    Foo (F.hs:7)
    add
```

* You can now nest paragraphs inside of lists. For most people this
simply means that you can now have multiple levels of lists. We allow
arbitrary nesting depth. The rules are: 4 spaces of indentation, new
paragraphs have to be preceded by an empty line.

```
1. Foo

    1. Nested inside of Foo
    2. Another thing inside of Foo

    >>> example inside of Foo
    example result

2. Back after Foo
```

* You can now have headings inside of your documentation rather than
only for splitting up sections of your module. Example usage:

```
= Heading level one
>>> some code example
hello

== Heading level two
* Hello Haddock!
```

Up to 6 ‘=’s are currently supported. LaTeX back-end only honours up to
three ‘=’s but it is not an error to have >3, they'll simply be treated
as 3.

* You can now display enabled module extensions in the generated
documentation with {-# OPTIONS_HADDOCK show-extensions #-}.

* Picture syntax now documented.

* You can now have the title attribute for your hyperlinks. The syntax
is <link title>

I think that about covers it all. Perhaps I will write a more visual
guide to the new changes but please don't hold your breath! Feel free to
ask questions. If you have bugs to report or features to ask for, please
head to the Haddock Trac[3].

[1]: http://www.haskell.org/haddock/CHANGES.txt
[2]: http://www.haskell.org/haddock/doc/html/
[3]: http://trac.haskell.org/haddock

-- 
Mateusz K.