Haddock numbered list continuation

Question

How to continue a numbered list with haddock documentation tool? The following lines in haddock

--  1. First line.
-- 
--  2. Second line with instructions to do something 
-- 
--     >>> command-linecmd param
--
--  3. Third line..
--

generate the next html:

</p><ol><li> First line.
</li><li> Second line with instructions to do something 
</li></ol><pre class="screen"><code class="prompt">&gt;&gt;&gt; </code><strong         class="userinput"><code>command-linecmd param
</code></strong></pre><ol><li> Third line..
</li></ol>

This breaks the numbering. Is there a way to make haddock continue with third-number also in HTML or should I try something other (>>> gives a nice formatting, why I'd like to use it)?

Answer 1

You can't. You're using >>>. In order to have this rendered as an example, it needs to be at the beginning of the paragraph.

What's considered a beginning of the paragraph?

• Anything at the start of a Haddock comment, skipping any white space preceding it.

• Anything following an empty line.

In your scenario you have 4 paragraphs: list element, list element, example, list element. Internally, Haddock completely ignores the list numbers you're putting down: you could start from 999 if you wanted to. When Haddock sees consecutive paragraphs with the same type of list, it joins them and numbers them. As you're breaking the pattern, the lists are not treated as a continuation. Indenting >>> with spaces there is actually pointless in this scenario as they will be stripped away as we're in a new paragraph. Note that the spaces are important if you have consecutive examples: you can put them in the same paragraph as long as your indentation is identical.

Other things that have to be on their own paragraph (and will therefore break the list order) is lists, birdtracks, codeblocks (paragraph containing only text between @s) and properties (prop>).

While this could be solved by allowing paragraph nesting, this isn't planned. Ticket #27 is solely about nesting lists (which do happen to be paragraph-level entities) but would not solve this problem.

I recommend that you use unordered lists if the numbers aren't vital or cheat a bit and use named lists ([name] content)

EDIT: As of 12 January 2014, Haddock ticket #27 has been resolved and this is now possible by indenting the example 4 spaces after the second list element. This:

1. First element

2. Second element

    >>> your example
    your example result

3. Third element

Now results in:

_{(source: fuuzetsu.co.uk)}