Citation Style Gallery
The citation style is determined when instantiating the CitationBibliography
, via the style
argument.
The built-in styles are:
style=:numeric
(default): numeric stylestyle=:authoryear
: author-year stylestyle=:alpha
: alphabetic style
Numeric style
This is the default style (style=:numeric
) used throughout the other pages of this documentation, cf. the Syntax examples.
[GoerzQ2022](@cite)
renders as "[2]"[FuerstNJP2014](@cite)
renders as "[11]"[GoerzQ2022](@citet)
renders as "Goerz *et al.* [2]"[GoerzQ2022](@citep)
renders as "[2]" —@citep
is the same as@cite
for this style[GoerzQ2022; Eq. (1)](@cite)
renders as "[2, Eq. (1)]"[GoerzQ2022; Eq. (1)](@citet)
renders as "Goerz *et al.* [2, Eq. (1)]"[GoerzQ2022](@citet*)
renders as "Goerz, Carrasco and Malinovsky [2]"[GoerzQ2022; Eq. (1)](@citet*)
renders as "Goerz, Carrasco and Malinovsky [2, Eq. (1)]"[WinckelIP2008](@citet)
renders as "von Winckel and Borzì [4]"[WinckelIP2008](@Citet)
renders as "Von Winckel and Borzì [4]"[arbitrary text](@cite GoerzQ2022)
renders as "arbitrary text"
References:
- [2]
-
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
- [4]
-
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).
- [11]
-
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.
Author-year style
The author-year style (style=:authoryear
) formats citations with the author name and publication year. This is the citation style used, e.g., in Rev. Mod. Phys. (rmp
option in REVTeX). The bibliography is sorted alphabetically by author name. The default @cite
command is parenthetical (@cite
and @citep
are equivalent) which is different from the authoryear
style in natbib.
[GoerzQ2022](@cite)
renders as "(Goerz *et al.*, 2022)"[FuerstNJP2014](@cite)
renders as "(Fürst *et al.*, 2014)"[GoerzQ2022](@citet)
renders as "Goerz *et al.* (2022)"[GoerzQ2022](@citep)
renders as "(Goerz *et al.*, 2022)" —@citep
is the same as@cite
for this style[GoerzQ2022; Eq. (1)](@cite)
renders as "(Goerz *et al.*, 2022, Eq. (1))"[GoerzQ2022; Eq. (1)](@citet)
renders as "Goerz *et al.* (2022, Eq. (1))"[GoerzQ2022](@cite*)
renders as "(Goerz, Carrasco and Malinovsky, 2022)"[GoerzQ2022](@citet*)
renders as "Goerz, Carrasco and Malinovsky (2022)"[GoerzQ2022; Eq. (1)](@cite*)
renders as "(Goerz, Carrasco and Malinovsky, 2022, Eq. (1))"[GoerzQ2022; Eq. (1)](@citet*)
renders as "Goerz, Carrasco and Malinovsky (2022, Eq. (1))"[WinckelIP2008](@citet)
renders as "von Winckel and Borzì (2008)"[WinckelIP2008](@Citet)
renders as "Von Winckel and Borzì (2008)"[arbitrary text](@cite GoerzQ2022)
renders as "arbitrary text"
References:
-
Fürst, H. A.; Goerz, M. H.; Poschinger, U. G.; Murphy, M.; Montangero, S.; Calarco, T.; Schmidt-Kaler, F.; Singer, K. and Koch, C. P. (2014). Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007. Special issue on coherent control of complex quantum systems.
-
Goerz, M. H.; Carrasco, S. C. and Malinovsky, V. S. (2022). Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871.
-
von Winckel, G. and Borzì, A. (2008). Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007.
Alphabetic style
The style=:alpha
formats citations and references like :numeric
, except that it uses labels derived from the author names and publication year and sorts the references alphabetically.
[GoerzQ2022](@cite)
renders as "[GCM22]"[FuerstNJP2014](@cite)
renders as "[FGP+14]"[GoerzQ2022](@citet)
renders as "Goerz *et al.* [GCM22]"[GoerzQ2022](@citep)
renders as "[GCM22]" —@citep
is the same as@cite
for this style[GoerzQ2022; Eq. (1)](@cite)
renders as "[GCM22, Eq. (1)]"[GoerzQ2022; Eq. (1)](@citet)
renders as "Goerz *et al.* [GCM22, Eq. (1)]"[GoerzQ2022](@citet*)
renders as "Goerz, Carrasco and Malinovsky [GCM22]"[GoerzQ2022; Eq. (1)](@citet*)
renders as "Goerz, Carrasco and Malinovsky [GCM22, Eq. (1)]"[WinckelIP2008](@citet)
renders as "von Winckel and Borzì [vWB08]"[WinckelIP2008](@Citet)
renders as "Von Winckel and Borzì [vWB08]"[arbitrary text](@cite GoerzQ2022)
renders as "arbitrary text"
References:
- [FGP+14]
-
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.
- [GCM22]
-
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
- [vWB08]
-
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).
Note that the :alpha
style is able to automatically disambiguate labels:
- [GBR+07a]
-
M. Grace, C. Brif, H. Rabitz, I. A. Walmsley, R. L. Kosut and D. A. Lidar. Optimal control of quantum gates and suppression of decoherence in a system of interacting two-level particles. J. Phys. B 40, S103 (2007), arXiv:quant-ph/0702147.
- [GBR+07b]
-
M. D. Grace, C. Brif, H. Rabitz, D. A. Lidar, I. A. Walmsley and R. L. Kosut. Fidelity of optimally controlled quantum gates with randomly coupled multiparticle environments. J. Mod. Opt. 54, 2339 (2007), arXiv:0712.2935.
This works because the DocumenterCitations
plugin automatically upgrades style=:alpha
to the internal
DocumenterCitations.AlphaStyle
— Type"Smart" alphabetic citation style (relative to the "dumb" :alpha
).
style = AlphaStyle()
instantiates a style for CitationBibliography
that avoids duplicate labels. Any of the entries that would result in the same label will be disambiguated by appending the suffix "a", "b", etc.
Any bibliography that cites a subset of the given entries
is guaranteed to have unique labels.
Custom styles
In the following, we show two examples for user-defined styles. See the notes on customization on how to generally define a custom style.
Custom style: enumerated author-year
In this example, the :authoryear
style is used, but the references are shown in an enumerated list.
import DocumenterCitations
function DocumenterCitations.format_bibliography_reference(::Val{:enumauthoryear}, entry)
text = DocumenterCitations.format_bibliography_reference(:authoryear, entry)
return uppercasefirst(text)
end
DocumenterCitations.format_citation(::Val{:enumauthoryear}, args...; kwargs...) =
DocumenterCitations.format_citation(:authoryear, args...; kwargs...)
DocumenterCitations.bib_sorting(::Val{:enumauthoryear}) = :nyt # name, year, title
DocumenterCitations.bib_html_list_style(::Val{:enumauthoryear}) = :ol
The important part of the definition is in the last line, indicating that the References should be shown as an enumeration (ordered list, <ol>
, in HTML), see below. Meanwhile, citations render exactly as with style=:authoryear
:
[GoerzQ2022](@cite)
renders as "(Goerz *et al.*, 2022)"[FuerstNJP2014](@cite)
renders as "(Fürst *et al.*, 2014)"[WinckelIP2008](@Citet)
renders as "Von Winckel and Borzì (2008)"
References:
-
Fürst, H. A.; Goerz, M. H.; Poschinger, U. G.; Murphy, M.; Montangero, S.; Calarco, T.; Schmidt-Kaler, F.; Singer, K. and Koch, C. P. (2014). Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007. Special issue on coherent control of complex quantum systems.
-
Goerz, M. H.; Carrasco, S. C. and Malinovsky, V. S. (2022). Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871.
-
Von Winckel, G. and Borzì, A. (2008). Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007.
Custom style: Citation-key labels
In this less trivial example, a style similar to :alpha
is used, using the citation keys in the .bib
file as labels. This would be somewhat more appropriate with citation keys that are shorter that the ones used here (keys similar to those automatically generated with the :alpha
style).
import DocumenterCitations, MarkdownAST
# we use some (undocumented) internal helper functions for formatting...
using DocumenterCitations: format_names, tex2unicode
DocumenterCitations.format_bibliography_reference(::Val{:keylabels}, entry) =
DocumenterCitations.format_bibliography_reference(:numeric, entry)
function DocumenterCitations.format_bibliography_label(::Val{:keylabels}, entry, citations)
return "[$(entry.id)]"
end
function DocumenterCitations.format_citation(
style::Val{:keylabels},
entry,
citations;
note,
cite_cmd,
capitalize,
starred
)
link_text = isnothing(note) ? "[$(entry.id)]" : "[$(entry.id), $note]"
if cite_cmd == :citet
et_al = starred ? 0 : 1 # 0: no "et al."; 1: "et al." after 1st author
names =
format_names(entry; names=:lastonly, and=true, et_al, et_al_text="*et al.*") |>
tex2unicode
capitalize && (names = uppercase(names[1]) * names[2:end])
link_text = "$names $link_text"
end
return link_text::String
end
DocumenterCitations.bib_sorting(::Val{:keylabels}) = :nyt # name, year, title
DocumenterCitations.bib_html_list_style(::Val{:keylabels}) = :dl
[GoerzQ2022](@cite)
renders as "[GoerzQ2022]"[FuerstNJP2014](@cite)
renders as "[FuerstNJP2014]"[GoerzQ2022](@citet)
renders as "Goerz *et al.* [GoerzQ2022]"[GoerzQ2022](@citep)
renders as "[GoerzQ2022]" —@citep
is the same as@cite
for this style[GoerzQ2022; Eq. (1)](@cite)
renders as "[GoerzQ2022, Eq. (1)]"[GoerzQ2022; Eq. (1)](@citet)
renders as "Goerz *et al.* [GoerzQ2022, Eq. (1)]"[GoerzQ2022](@citet*)
renders as "Goerz, Carrasco and Malinovsky [GoerzQ2022]"[GoerzQ2022; Eq. (1)](@citet*)
renders as "Goerz, Carrasco and Malinovsky [GoerzQ2022, Eq. (1)]"[WinckelIP2008](@citet)
renders as "von Winckel and Borzì [WinckelIP2008]"[WinckelIP2008](@Citet)
renders as "Von Winckel and Borzì [WinckelIP2008]"[arbitrary text](@cite GoerzQ2022)
renders as "arbitrary text"
References:
- [FuerstNJP2014]
-
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.
- [GoerzQ2022]
-
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
- [WinckelIP2008]
-
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).