<div dir="ltr"><div class="gmail_default" style="font-family:tahoma,sans-serif">I'm open-minded, but I *really* want the text to be readily readable *in the original source file*.  So</div><div class="gmail_default" style="font-family:tahoma,sans-serif">* Back-ticks are much better than `@` signs; the latter are too noisy.</div><div class="gmail_default" style="font-family:tahoma,sans-serif">* For code, backticks add clutter.  Maybe just intentend text can be code?   (Unless it's part of a bulleted list.)</div><div class="gmail_default" style="font-family:tahoma,sans-serif"><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, 13 Apr 2022 at 21:45, Ben Gamari <<a href="mailto:ben@smart-cactus.org">ben@smart-cactus.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">"Sebastian Graf" <<a href="mailto:sgraf1337@gmail.com" target="_blank">sgraf1337@gmail.com</a>> writes:<br>
<br>
> Hi Devs,<br>
><br>
> When writing Notes, I find myself using markdown-inspired or <br>
> haddock-inspired features. The reason is that I keep telling myself<br>
><br>
> > In 5 years time, we'll surely have an automated tool that renders <br>
> > Notes referenced under the cursor in a popup in our IDE<br>
><br>
<br>
I tell myself a similar tale. true. In particular, I would like to see<br>
Haddock gain support for Note-like documentation. When I wrote the Note<br>
linter I was surprised by how simple and robust the parser was despite<br>
the rather ad-hoc choice of syntax. This makes me hopeful that this goal<br>
can be realized.<br>
<br>
Concretely, I suspect that something like<br>
<a href="https://github.com/haskell/haddock/issues/193" rel="noreferrer" target="_blank">https://github.com/haskell/haddock/issues/193</a> might be a reasonable<br>
approximation of what we need.<br>
<br>
> And I might not be completely wrong about that, after all the strong <br>
> conventions about Note declaration syntax allow me to do <br>
> jump-to-definition on Note links in my IDE already (thanks to a shell <br>
> script written by Zubin!).<br>
><br>
> Still, over the years I kept drifting between markdown and haddock <br>
> syntax, sometimes used `backticked inline code` or haddock 'ticks' to <br>
> refer to functions in the compiler (sometimes even <br>
> 'GHC.Fully.Qualified.ticks') and for code blocks I used all of the <br>
> following forms:<br>
><br>
I am quite guilty of the same.<br>
<br>
> I know that at least Simon was thrown off in the past about my use of <br>
> "tool-aware markup", perhaps also because I kept switching the targetted <br>
> tool. I don't like that either. So I wonder<br>
> Do you think it is worth optimising Notes for post-processing by an <br>
> external tool?I think it's only reasonable if we decide for a target <br>
> syntax. Which syntax should it be?<br>
<br>
Yes, we should decide on a direction and document it. My sense is that<br>
Haddock is probably the best option when it comes to integrating with<br>
"normal" Haskell workflows. Happily, backticks are valid Haddock syntax<br>
so at least this particular bit of muscle-memory can be retained [1].<br>
<br>
Incidentally, I suspect that ```-style code blocks would be a<br>
valuable addition to Haddock for syntax-highlighted blocks of code in<br>
languages other than Haskell.<br>
<br>
On the other hand, there is talk [2] of Haddock gaining a Markdown<br>
frontend, so Markdown may be more of a viable option than I'm giving it<br>
credit for.<br>
<br>
Cheers,<br>
<br>
- Ben<br>
<br>
<br>
[1] <a href="https://haskell-haddock.readthedocs.io/en/latest/markup.html#hyperlinked-identifiers" rel="noreferrer" target="_blank">https://haskell-haddock.readthedocs.io/en/latest/markup.html#hyperlinked-identifiers</a><br>
[2] <a href="https://github.com/haskell/haddock/issues/794#issuecomment-1018884773" rel="noreferrer" target="_blank">https://github.com/haskell/haddock/issues/794#issuecomment-1018884773</a><br>
_______________________________________________<br>
ghc-devs mailing list<br>
<a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a><br>
<a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs</a><br>
</blockquote></div>