CODEWITHSUNDEEP
haskellhaddock
Antal Spector-Zabusky
Antal Spector-Zabusky

Reputation: 36622

How to generate a Haddock inline code span that takes up a whole line

In Haddock, the "inline code"¹ markup, @...@, is the same as the "code block" markup,

@
...
@

How can I write a single-line Haddock comment that consists only of an inline code span, without it being misinterpreted as a block? A comment like

-- |@/code/ span@

renders as the block

code span

instead of the desired inline

code span

The context, in case more examples help, is that I'm writing a data type that represents a BNF grammar, and so I have a number of types that look like the following:

-- |@/term/ ::=@
data Term = Var Name       -- ^@/name/@
          | Plus Term Term -- ^@/term/ + /term/@
          | Print Term     -- ^@print /term/@

This example corresponds to the grammar

term ::= name
      |  term + term
      |  print term

and so the grammar is embedded in the Haddock comments. But since Haddock parses those @...@ comments as blocks, the output is unnecessarily tall, and is inconsistent when some lines have extra comment text (e.g., -- ^@double /term/@ – syntax sugar).

¹ A.k.a. "monospaced" or "typewriter".

Upvotes: 3

Views: 571

Answers (1)

sclv
sclv

Reputation: 38891

Here is a suggested dirty hack. Your problem is that your lines only have code, and not text, correct? Well, just add, after the code, a bit of meaningless text. You can use the &#xH; format to insert hexcodes of unicode characters, for example zero-width or nonbreaking spaces. I would imagine that this would let you convince haddock that you are in an inline rather than block context.

Upvotes: 1

Related Questions