Comments (7)
@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
.
from documentercitations.jl.
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.
from documentercitations.jl.
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)
from documentercitations.jl.
I don't think so -- DocumenterCitations isn't available when you just use the package and view docstrings.
from documentercitations.jl.
Ah, I see, that is a bit unfortunate. It would be great to have something lightweight for this display then.
from documentercitations.jl.
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.
from documentercitations.jl.
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.
from documentercitations.jl.
Related Issues (20)
- Incompatible with `linkcheck` HOT 2
- Note = not displayed (or: add customs fields in display of a BibteX entry) HOT 5
- About non canonical bibliography inconsistencies (to autodocs) HOT 4
- Allow to exclude specific entries from the bibliography
- Duplicate keys in `:alpha`betic style HOT 12
- How to use `:numeric` but with `:nyt` sorting HOT 6
- doctest and CitationBibliography HOT 11
- Add support for bioRxiv and HAL preprint servers
- Citations from docstrings are not collected HOT 5
- Transform citations with missing references HOT 1
- Add support for corporate authors HOT 5
- This package fails PkgEval HOT 9
- Support `urldate` field HOT 2
- DocumenterCitations 1.3.0 is a breaking change? HOT 24
- Markdown syntax in strings in BibTeX entries is not escaped HOT 4
- Any valid BibTeX entry should be able to auto-link both a URL and a DOI
- Show reference on hover HOT 1
- Backlinks
- Use multiple .bib files to create citation
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from documentercitations.jl.