Markup language/convention for Notes?

Simon Peyton Jones simon.peytonjones at
Wed Apr 13 20:58:45 UTC 2022

I'm open-minded, but I *really* want the text to be readily readable *in
the original source file*.  So
* Back-ticks are much better than `@` signs; the latter are too noisy.
* For code, backticks add clutter.  Maybe just intentend text can be
code?   (Unless it's part of a bulleted list.)

On Wed, 13 Apr 2022 at 21:45, Ben Gamari <ben at> wrote:

> "Sebastian Graf" <sgraf1337 at> 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
> 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]
> [2]
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the ghc-devs mailing list