Link two functions without a space between them

Question

I am writing documentation for a library using haddock, and, for reasons that are not really necessary to explain, I need to include a little code block in my documentation that looks like:

z(<>)

Importantly there can be no space between z and (<>). It may be a bit esoteric but

z (<>)

would make my documentation incorrect, even if it is more stylistically correct.

Now I believe that hyperlinks to both z and (<>) would be helpful. Neither has a very informative name, so a link that helps people remember their definitions and purpose is nice.

So my code without the hyperlinks looks like:

@z(<>)@

And to add hyperlinks I just use single quotes:

@'z''(<>)'@

Except that doesn't work, haddock sees 'z'' and thinks that I mean to link z' (a function that does exist in my module), and then just leaves the rest alone. The rendered output looks like

z'(<>)'

Now as an experiment I deleted the definition of z', however the only difference this makes is that the link to z' goes away. The raw text remains the same. The next thing I tried was ditching @s altogether and did

'z''(<>)'

Which also created a hyperlink to z' and left the rest untouched, the same problem as earlier except now nothing is in a code block.

How can I make a code block that links two functions without a space between?

score 2 · Answer 1 · answered Mar 26 '20 at 00:07

2

You can separate the two functions into different code blocks. If there is no space between the code blocks, it will appear no different than a single code block. So

@'z'@@'(<>)'@

will render as desired.

You can also do it in one code block by moving the 's inside of the parentheses to only surround <>.

@'z'('<>')@

This will render slightly differently with the parentheses not being part of any hyperlink, however this may be desired.

answered Mar 26 '20 at 00:07

Wheat Wizard

3,982
14
34

That second version seems much more semantically reasonable than the first. – dfeuer Mar 26 '20 at 00:10

score 1 · Answer 2 · answered Mar 27 '20 at 20:23

Here is an alternative solution to add to the answer you already provided:

You can mix and match ' and `. These two will also be rendered correctly by haddock:

-- | @`z`'(<>)'@

-- | @'z'`(<>)`@

At the same time I've tried your solution @'z'@@'(<>)'@ and for some reason it did not render for me properly, but with haddock you never know.

Here are all of the ones that I've tried:

-- * @'z'@@'(<>)'@
-- * @'z'('<>')@
-- * @'z'`(<>)`@
-- * @`z`'(<>)'@

With corresponding result:

Link two functions without a space between them

2 Answers2