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

You can write @ code :: With 'Linked' -> Types code = ... @ The linked identifiers are a huge feature of haddock, makes documentation a lot nicer to navigate. Of course general syntax highlighter might also auto-link identifiers in Haskell codeblocks, but none of markdown parsers has a support for such hooks, AFAICT. - Oleg On 14.4.2022 0.15, Ben Gamari wrote:

Simon Peyton Jones writes:

...

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.)

In Markdown region of text indented by at least four spaces denotes a code block element. Unfortunately, Haddock doesn't have a similarly noise-free syntax, requiring that lines of code blocks begin with `>`.

Cheers,

- Ben

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs On 14.4.2022 0.15, Ben Gamari wrote: Simon Peyton Jones writes:

...

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.)

In Markdown region of text indented by at least four spaces denotes a code block element. Unfortunately, Haddock doesn't have a similarly noise-free syntax, requiring that lines of code blocks begin with `>`.

Cheers,

- Ben

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs