Render citation from docs also in in REPL

[kellertuer]

In this section

https://juliadocs.org/DocumenterCitations.jl/stable/syntax/#Citations-in-docstrings

there is a very nice description, that I already follow in my docs as well. In html this looks really nice. Would it be possible to render it that nice on REPL as well? Currently a link like

in [Bergmann et. al., SIAM J Imag Sci, 2014](@cite BergmannLausSteidlWeinmann:2014:1)

renders on REPL like

in Bergmann et. al., SIAM J Imag Sci, 2014 (@cite BergmannLausSteidlWeinmann:2014:1).

and has no collar markup like usually links do omitting the bracket and collaring it would be super nice.

[fredrikekre]

I don't think this would be possible without adding DocumenterCitation as a dependency to your package, and then use a docstring hook from DocStringExtensions to replace the link. DocStringExtensions is very lightweight, but DocumenterCitations is HEAVY, so probably you don't want to do this.

One alternative that would be possible to explore is to replace it with a url to the documenter generated bibliograpy perhaps.

[kellertuer]

But can that maybe be done generically in DocumenterCitations for all these? I do not see why I would have to do it for just my package (and again for the next)

[fredrikekre]

I don't think so -- DocumenterCitations isn't available when you just use the package and view docstrings.

[kellertuer]

Ah, I see, that is a bit unfortunate. It would be great to have something lightweight for this display then.

[fredrikekre]

@mortenpi this is another example where it would be good to be able to use the base doc hooks differently based on the context. In the repl it could then be replaced by a URL, and in Documenter just keep the link as @cite.

[goerz]

I don't think I fully realized until now that the Julia REPL processes the markdown of docstrings. I guess this is part of Base, but I don't think I'm a fan of this behavior. Given how light-weight markdown is, it would seem preferable to just show the unprocessed docstrings in the REPL. Oh well.

Maybe we can submit a patch to Julia Base that it should recognize certain types of links and handle them differently. It looks to me like @ref-links are already handled as a special case. I don't think we can get full bibliographic handling into the REPL, since that would be much too heavy a dependency, as Fredrik points out. Perhaps we can have a very lightweight separate package that similarly to DocStringExtensions processes the citations in docstrings before Base sees them.

My preferred formatting would be very simple:

[Bergmann et. al., SIAM J Imag Sci, 2014](@cite BergmannLausSteidlWeinmann:2014:1) would be translated to Bergmann et. al., SIAM J Imag Sci, 2014 [BergmannLausSteidlWeinmann:2014:1] and [BergmannLausSteidlWeinmann:2014:1](@cite) would simply become [BergmannLausSteidlWeinmann:2014:1]. More or less the citation-key-label-style, while ignoring @citet. Granted, this would look a little better with shorter citation keys.

A completely separate issue is that Documenter also mutates docstrings when it runs, which screws up citations in particular, but that should be fixed in #3.

[kellertuer]

Don't worry I also only noticed that when Frederik answered here.
I think your recommendations are fine, both look reasonable – and sure with a note the way is also relatively clear (and possible without too much processing).

Sure, with shorter keys this would be shorter, but I prefer these little longish keys, since that is what a lot of my co-authors use.

[kellertuer]

This seems to be fixed in Julia 1.11, it I s rendered as

  The tangent vector X can be written in the form X = \bar{\Omega}p
  BendokatZimmermann:2021 (@cite), with

nice!