Re: Markup language/convention for Notes?
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 signature.asc Description: PGP signature ___ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
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-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
Re: Run-time absence info
ometimes even > 'GHC.Fully.Qualified.ticks') and for code blocks I used all of the > following forms: > > Haddock "code quote" > > > id :: a -> a > > id x = x > > Markdown triple backticks > > ```hs > id :: a -> a > id x = x > ``` > > Indentation by spaces > >id :: a -> a >id x = x > > And so on. > > 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? > Cheers, > Sebastian > -- next part -- > An HTML attachment was scrubbed... > URL: < > http://mail.haskell.org/pipermail/ghc-devs/attachments/20220413/84549293/attachment-0001.html > > > > -- > > Subject: Digest Footer > > ___ > ghc-devs mailing list > ghc-devs@haskell.org > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs > > > -- > > End of ghc-devs Digest, Vol 224, Issue 10 > * > ___ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Re: Markup language/convention for Notes?
"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-identifiers [2] https://github.com/haskell/haddock/issues/794#issuecomment-1018884773 signature.asc Description: PGP signature ___ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Markup language/convention for Notes?
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 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: Haddock "code quote" > id :: a -> a > id x = x Markdown triple backticks ```hs id :: a -> a id x = x ``` Indentation by spaces id :: a -> a id x = x And so on. 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? Cheers, Sebastian___ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Re: Absence info at run-time
W/W should transform such a function into one who takes one less argument removing any runtime overhead at least for fully applied functions. I suppose your suggestion is then if we an expression`f x` where bar takes multiple arguments, but doesn't use the current argument then GHC should: * Inspect f, check if the first argument to f is used * If we can determine it isn't used instead of creating a PAP capturing `f` and `x` instead only capture `f` and record this in the PAP closure somehow. * Once the PAP is fully applied pass a dummy argument instead of `x` to f. If f is a known call that seems doable, although adding a bitmap to paps might require us to increase the size of all PAP closures, making this optimization less useful. If `f` is a unknown function there is currently no way to get absent/used info for it's arguments at runtime. And changing that would be a major change which seems unlikely to pay off. So I think this would be theoretically possible, but it would rarely pay off. Also do you have an example where `(const a) b` leads to stupid thunks? It seems to me const should always be inlined in such a case, avoiding a PAP allocation. Am 12/04/2022 um 23:02 schrieb David Feuer: Suppose `f` doesn't use its first argument. When forming the thunk (or partial application) `f a`, we don't need to record `a`. What if instead of arity, we store a bitmap used/absent arguments, terminated by a 1 bit? Could we then get rid of "stupid thunks" like `(const a) b`? ___ 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
