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

2
votes

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

1
haskellhaddock
Are you sure you need this? Sounds like you're using comments wrong, after all a Haskell ADT definition is already pretty much a grammar. This reminds me of i++; // Increment i by 1 style coding. — If you really need BNF, well, provide it as a single plaintext chunk, but not as Haddock inline comments. – leftaroundabout
@leftaroundabout: The BNF already exists, I'm just instantiating it in Haskell. The point of the comments is to line up the constructors, and perhaps more importantly the fields, with the productions/nonterminals in the BNF rules. E.g., in the production Let Ident [Binder] (Maybe Term) Term Term, which Term means what? It helps to see that this production is let /ident/ [/binders/] [: /term/] := /term/ in /term/. So the comments are half "why" and half "what does this mean?". – Antal Spector-Zabusky
@leftaroundabout (And even if you aren't convinced by this use case, the "inline code/code block" ambiguity is something that I've encountered with Haddock before.) – Antal Spector-Zabusky
Yeah, me too, Haddock code-snippet syntax is certainly a bit annoying. But IMO it just doesn't make sense to have “line-spanning inline code”. — I'm indeed not convinced with this use case: if you want readability then improve your code, not your comments. Type operators / infix constructors / type synonyms can help here. – leftaroundabout
@leftaroundabout I tried that at first – and I'm certainly not done iterating on the design of this AST – but with 5-argument type constructors, three of whose arguments are the same type, it gets tricky to do. Type synonyms aren't necessarily a bad choice (although the number needed becomes a bit of a pain), but I've decided that what's more important is at-a-glance correspondence with the BNF source, as this is part of a verification-related project where it's important to know that your model is of the right thing. (Although we're not verifying this code itself, I'm in that mindset.) – Antal Spector-Zabusky

1 Answers

1
votes

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.