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 <b...@smart-cactus.org> wrote: > "Sebastian Graf" <sgraf1...@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@haskell.org > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs >
_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs