Markup language/convention for Notes?

[Simon Peyton Jones]

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 smart-cactus.org> wrote:

> "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
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20220413/85eb5c38/attachment.html>