Re: Markup language/convention for Notes?

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 wrote:

"Sebastian Graf" 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-ide... [2] https://github.com/haskell/haddock/issues/794#issuecomment-1018884773 _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs