Markup language/convention for Notes?

[Ben Gamari]

"Sebastian Graf" <sgraf1337 at gmail.com> writes:

> Hi Devs,
>
> When writing Notes, I find myself using markdown-inspired or 
> haddock-inspired features. The reason is that I keep telling myself
>
> > In 5 years time, we'll surely have an automated tool that renders 
> > Notes referenced under the cursor in a popup in our IDE
>

I tell myself a similar tale. true. In particular, I would like to see
Haddock gain support for Note-like documentation. When I wrote the Note
linter I was surprised by how simple and robust the parser was despite
the rather ad-hoc choice of syntax. This makes me hopeful that this goal
can be realized.

Concretely, I suspect that something like
https://github.com/haskell/haddock/issues/193 might be a reasonable
approximation of what we need.

> And I might not be completely wrong about that, after all the strong 
> conventions about Note declaration syntax allow me to do 
> jump-to-definition on Note links in my IDE already (thanks to a shell 
> script written by Zubin!).
>
> Still, over the years I kept drifting between markdown and haddock 
> syntax, sometimes used `backticked inline code` or haddock 'ticks' to 
> refer to functions in the compiler (sometimes even 
> 'GHC.Fully.Qualified.ticks') and for code blocks I used all of the 
> following forms:
>
I am quite guilty of the same.

> I know that at least Simon was thrown off in the past about my use of 
> "tool-aware markup", perhaps also because I kept switching the targetted 
> tool. I don't like that either. So I wonder
> Do you think it is worth optimising Notes for post-processing by an 
> external tool?I think it's only reasonable if we decide for a target 
> syntax. Which syntax should it be?

Yes, we should decide on a direction and document it. My sense is that
Haddock is probably the best option when it comes to integrating with
"normal" Haskell workflows. Happily, backticks are valid Haddock syntax
so at least this particular bit of muscle-memory can be retained [1].

Incidentally, I suspect that ```-style code blocks would be a
valuable addition to Haddock for syntax-highlighted blocks of code in
languages other than Haskell.

On the other hand, there is talk [2] of Haddock gaining a Markdown
frontend, so Markdown may be more of a viable option than I'm giving it
credit for.

Cheers,

- Ben


[1] https://haskell-haddock.readthedocs.io/en/latest/markup.html#hyperlinked-identifiers
[2] https://github.com/haskell/haddock/issues/794#issuecomment-1018884773
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 487 bytes
Desc: not available
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20220413/6aba7297/attachment.sig>