Merge pull request #25 from JuliaDocs/mg/20-notes-and-preprint

NEWS.md

@@ -7,17 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-* Do not try include a year when rendering a reference if the underlying BibTeX entry has no `year` field.
-* Avoid duplicate labels in `:alpha` style. This is implemented via the new stateful `AlphaStyle()`, but is handled automatically.
+* Avoid duplicate labels in `:alpha` style. This is implemented via the new stateful `AlphaStyle()`, but is handled automatically with (`style=:alpha`).
 * With the alphabetic style (`:alpha`/`AlphaStyle`), include up to 4 names in the label, not 3 (but 5 or more names results in 3 names and "+"). Also, include the first letter of a "particle" in the label, e.g. "vWB08" for a first author "von Winckel". Both of these are consistent with LaTeX's behavior.
+* Handle missing author/year, especially for `:authoryar` and `:alpha` styles. You end up with `:alpha` labels like `Anon04` (missing authors) or `CW??` (missing year), and `:authoryear` citations like "(Anonymous, 2004)" and "(Corcovilos and Weiss, undated)".
+* Consistent punctuation in the rendered bibliography, including for cases of missing fields.
 
 ### Added
 
 * New `style=AlphaStyle()` that generates unique citation labels. This can mostly be considered internal, as `style=:alpha` is automatically upgraded to `style=AlphaStyle()`.
+* Support for `eprint` field. It is recommended to add the arXiv ID in the `eprint` field for any article whose DOI is behind a paywall.
+* Support for `note` field.
+
+### Changed
+
+* In the rendered bibliography, the BibTeX "URL" field is now linked via the title, while the "DOI" is linked via the journal information. This allows to have a DOI and URL at the same time, or a URL for an `@unpublished`/`@misc` citation. If there is a URL but no title, the URL is used as the title.
 
 ### Internal Changes
 
-* Added an internal function `init_bibliography!` that is called at the beginning of the `ExpandBibliography` pipeline step. This function is intended to initialized internal state either of the `style` object or the `CitationBibliography` plugin object before rendering any `@bibliography` blocks. This is used to generate unique citation labels for the new `AlphaStyle()`. For the other builtin styles, it is a no-op. Generally, `init_bibliography!` can help with implementing custom "stateful" styles.
+* Added an internal function `init_bibliography!` that is called at the beginning of the `ExpandBibliography` pipeline step. This function is intended to initialize internal state either of the `style` object or the `CitationBibliography` plugin object before rendering any `@bibliography` blocks. This is used to generate unique citation labels for the new `AlphaStyle()`. For the other builtin styles, it is a no-op. Generally, `init_bibliography!` can help with implementing custom "stateful" styles.
 
 
 ## [Version v1.0.0][1.0.0] - 2023-07-12

docs/latex/numeric.tex

@@ -37,6 +37,7 @@
   \item \verb|\citep*[Eq.~(1)]{GoerzQ2022}| renders as ``\citep*[Eq.~(1)]{GoerzQ2022}''.
   \item \verb|\citet{WinckelIP2008}| renders as ``\citet{WinckelIP2008}''.
   \item \verb|\Citet{WinckelIP2008}| renders as ``\Citet{WinckelIP2008}''.
+  \item \cite{GoerzPhd2015} and \cite{Luc-KoenigEPJD2004}
 \end{itemize}
 
 Further commands that we do not support in markdown:

docs/src/gallery.md

@@ -93,7 +93,7 @@ GraceJMO2007
 GraceJPB2007
 ```
 
-This works because the `DocumenterCitations` automatically upgrades `style=:alpha` to the internal
+This works because the `DocumenterCitations` plugin automatically upgrades `style=:alpha` to the internal
 
 ```@docs
 DocumenterCitations.AlphaStyle

docs/src/refs.bib

@@ -165,6 +165,8 @@ @article{GoerzJPB2011
     Doi = {10.1088/0953-4075/44/15/154011},
     Pages = {154011},
     Volume = {44},
+    eprint = {1103.6050},
+    note = {Special issue on quantum control theory for coherence and information dynamics},
 }
 
 
@@ -176,6 +178,7 @@ @article{TomzaPRA2012
     Doi = {10.1103/PhysRevA.86.043424},
     Pages = {043424},
     Volume = {86},
+    eprint = {1208.4331},
 }
 
 @article{GoerzNJP2014,
@@ -186,6 +189,7 @@ @article{GoerzNJP2014
     Doi = {10.1088/1367-2630/16/5/055012},
     Pages = {055012},
     Volume = {16},
+    note = {Special issue on coherent control of complex quantum systems},
 }
 
 @article{GoerzPRA2014,
@@ -196,6 +200,8 @@ @article{GoerzPRA2014
     Doi = {10.1103/PhysRevA.90.032329},
     Pages = {032329},
     Volume = {90},
+    eprint = {1401.1858},
+    note = {Editor's suggestion},
 }
 
 @article{JaegerPRA2014,
@@ -206,6 +212,7 @@ @article{JaegerPRA2014
     Doi = {10.1103/PhysRevA.90.033628},
     Pages = {033628},
     Volume = {90},
+    eprint = {1409.2976},
 }
 
 @article{FuerstNJP2014,
@@ -216,13 +223,14 @@ @article{FuerstNJP2014
     Doi = {10.1088/1367-2630/16/7/075007},
     Pages = {075007},
     Volume = {16},
+    note = {Special issue on coherent control of complex quantum systems},
 }
 
 @phdthesis{GoerzPhd2015,
     Author = {Goerz, Michael},
     Title = {Optimizing Robust Quantum Gates in Open Quantum Systems},
     School = {Universität Kassel},
-    url = {https://michaelgoerz.net/#PhD-Thesis},
+    url = {https://kobra.uni-kassel.de/handle/123456789/2015052748381},
     Year = {2015},
 }
 
@@ -234,6 +242,7 @@ @article{GoerzPRA2015
     Doi = {10.1103/PhysRevA.91.062307},
     Pages = {062307},
     Volume = {91},
+    eprint = {1412.7350},
 }
 
 @article{WattsPRA2015,
@@ -244,6 +253,7 @@ @article{WattsPRA2015
     Doi = {10.1103/PhysRevA.91.062306},
     Pages = {062306},
     Volume = {91},
+    eprint = {1412.7347},
 }
 
 @article{GoerzEPJQT2015,
@@ -274,6 +284,7 @@ @article{SetserPRA2018
     Doi = {10.1103/PhysRevA.97.062339},
     Pages = {062339},
     Volume = {97},
+    eprint = {1804.08783},
 }
 
 @article{GoerzQST2018,
@@ -284,6 +295,7 @@ @article{GoerzQST2018
     Doi = {10.1088/2058-9565/aace16},
     Pages = {045005},
     Volume = {3},
+    eprint = {1801.04382},
 }
 
 @article{GoerzSPP2019,
@@ -302,6 +314,7 @@ @inproceedings{GoerzSPIEO2021
     Doi = {10.1117/12.2587002},
     Booktitle = {Proc. SPIE 11700, Optical and Quantum Sensing and Precision Metrology},
     Year = {2021},
+    url = {https://michaelgoerz.net/research/GoerzSPIEO2021.pdf},
 }
 
 @article{GoerzQ2022,
@@ -312,8 +325,6 @@ @article{GoerzQ2022
     Doi = {10.22331/q-2022-12-07-871},
     Pages = {871},
     Volume = {6},
-    eprint = {2205.15044},
-    Archiveprefix = {arXiv},
 }
 
 @article{RaithelQST2022,
@@ -334,6 +345,7 @@ @article{CarrascoPRA2022
     Doi = {10.1103/physrevapplied.17.064050},
     Pages = {064050},
     Volume = {17},
+    eprint = {2201.01744},
 }
 
 @article{GoerzA2023,
@@ -344,6 +356,8 @@ @article{GoerzA2023
     Doi = {10.3390/atoms11020036},
     Pages = {36},
     Volume = {11},
+    eprint = {2212.12602},
+    note = {Special issue on Advances in and Prospects for Matter Wave Interferometry},
 }
 
 @book{Tannor2007,
@@ -352,6 +366,7 @@ @book{Tannor2007
     publisher = {University Science Books},
     title = {Introduction to Quantum Mechanics: A Time-Dependent Perspective},
     year = {2007},
+    Url = {https://uscibooks.aip.org/books/introduction-to-quantum-mechanics-a-time-dependent-perspective/},
 }
 
 @incollection{TannorBookChapter1991,
@@ -361,6 +376,7 @@ @incollection{TannorBookChapter1991
     pages = {333--345},
     publisher = {Springer},
     title = {Design of Femtosecond Pulse Sequences to Control Photochemical Products},
+    doi = {0.1007/978-94-011-2642-7_23},
     year = {1991},
 }
 
@@ -382,6 +398,7 @@ @article{HuangPRA2017
     Doi = {10.1103/PhysRevA.95.062325},
     Pages = {062325},
     Volume = {95},
+    eprint= {1705.06150},
 }
 
 @article{WinckelIP2008,
@@ -403,6 +420,7 @@ @article{ImamogluPRE2015
     Pages = {022714},
     Volume = {91},
     Number = {2},
+    arxiv = {1408.5798},
 }
 
 @unpublished{Evans1983,
@@ -439,6 +457,7 @@ @article{LapertPRA09
     Doi = {10.1103/PhysRevA.79.063411},
     Pages = {063411},
     Volume = {79},
+    eprint = {0906.1051},
 }
 
 
@@ -450,6 +469,7 @@ @article{GraceJMO2007
     Doi = {10.1080/09500340701639615},
     Pages = {2339},
     Volume = {54},
+    eprint = {0712.2935},
 }
 
 
@@ -461,6 +481,7 @@ @article{GraceJPB2007
     Doi = {10.1088/0953-4075/40/9/s06},
     Pages = {S103},
     Volume = {40},
+    eprint = {quant-ph/0702147},
 }
 
 
@@ -472,6 +493,7 @@ @article{GrondPRA2009b
     Doi = {10.1103/PhysRevA.80.053625},
     Pages = {053625},
     Volume = {80},
+    eprint = {0908.1634},
 }
 
 
@@ -483,5 +505,49 @@ @article{GrondPRA2009a
     Doi = {10.1103/PhysRevA.79.021603},
     Pages = {021603},
     Volume = {79},
+    eprint = {0806.3877},
+}
+
+
+@article{Luc-KoenigEPJD2004,
+    Author = {Luc-Koenig, E. and Vatasescu, M. and Masnou-Seeuws, F.},
+    Title = {Optimizing the photoassociation of cold atoms by use of chirped laser pulses},
+    Journal = epjd,
+    Year = {2004},
+    Doi = {10.1140/epjd/e2004-00161-8},
+    Pages = {239},
+    Volume = {31},
+    Number = {2},
+    eprint = {physics/0407112},
+    primaryClass = {physics.atm-clus},
+    Archiveprefix = {arXiv},
+}
+
+@article{Wilhelm2003.10132,
+    Author = {Wilhelm, Frank K. and Kirchhoff, Susanna and Machnes, Shai and Wittler, Nicolas and Sugny, Dominique},
+    Title = {An introduction into optimal control for quantum technologies},
+    Journal = {arXiv:2003.10132},
+    Year = {2020},
+    Doi = {10.48550/ARXIV.2003.10132},
+}
+
+@misc{QCRoadmap,
+    editor = {Todd Heinrichs},
+    title = {Quantum Computation Roadmap},
+    url = {http://qist.lanl.gov},
+    note = {Version 2.0; April 2, 2004},
+    Year = {2004},
 }
 
+@unpublished{TedRyd,
+  author    =      {Corcovilos, T. and Weiss, D. S.},
+  title     =      {Rydberg Calculations},
+  note = {Private communication}
+}
+
+
+@misc{jax,
+  author = {James Bradbury and Roy Frostig and Peter Hawkins and Matthew James Johnson and Chris Leary and Dougal Maclaurin and George Necula and Adam Paszke and Jake Vander{P}las and Skye Wanderman-{M}ilne and Qiao Zhang},
+  title = {JAX: composable transformations of Python+NumPy programs},
+  url = {https://github.com/google/jax},
+}

docs/src/syntax.md

@@ -183,10 +183,22 @@ In general, the citation style determines the order of the references, see the [
 
 The [`refs.bib`](./refs.bib) file is in the standard [BibTeX format](https://www.bibtex.com/g/bibtex-format/). It must be parsable by [BibParser.jl](https://github.com/Humans-of-Julia/BibParser.jl).
 
-The use of `@string` macros for abbreviated journal names is encouraged, with the caveat of [#31](https://github.com/Humans-of-Julia/BibParser.jl/issues/31) and [#32](https://github.com/Humans-of-Julia/BibParser.jl/issues/32) in the [BibParser.jl issues](https://github.com/Humans-of-Julia/BibParser.jl/issues).
+You will find that you get the best results by maintaining a `.bib` files by hand, specifically for a given project using `DocumenterCitations`. A `.bib` file that works well with LaTeX may or may not work well with `DocumenterCitations`: remember that in LaTeX, the strings inside any BibTeX fields are rendered through the TeX engine. At least in principle, they may contain arbitrary macros.
 
-Also, even though `DocumenterCitations` has limited support for [escaped symbols](http://www.bibtex.org/SpecialSymbols/), the full use of unicode is both supported and strongly encouraged.
+In contrast, for `DocumenterCitations`, the BibTeX fields are minimally processed to convert some common LaTeX constructs to plain text, but beyond that, they are used "as-is". In future versions, the handling of LaTeX macros may improve, but it is best not to rely on it, and instead edit the `.bib` file so that it gives good results with `DocumenterCitations` (see the tips below).
 
-All entries should have a `Doi` field, or a `Url` field if no DOI is available.
+While we try to be reasonably compatible, "Any `.bib` file will render the bibliography you expect" is not a design goal, but "It is possible to write a `.bib` file so that you get exactly the bibliography you want" is.
 
-You may be interested in using the [`getbibtex` script](https://github.com/goerz/getbibtex) to generate consistent `.bib` files.
+Some tips to keep in mind when editing a `.bib` file to be used with `DocumenterCitations`:
+
+* Use unicode instead of [escaped symbols](http://www.bibtex.org/SpecialSymbols/).
+* You do not need to use [braces to protect capitalization](https://texfaq.org/FAQ-capbibtex). `DocumenterCitations` is not always able to remove such braces. But, unlike `bibtex`, `DocumenterCitation` will preserve the capitalization of titles.
+* Use a consistent scheme for citation keys. Shorter keys are better.
+* All entries should have a `Doi` field, or a `Url` field if no DOI is available.
+* If the published paper (`Doi` link) is not open-access, but a version of the paper is available on the [arXiv](https://arxiv.org), include the arXiv ID as `eprint` in the BibTeX entry. In the rendered bibliography, there will be a link to `https://arxiv.org/abs/<ID>`.
+* It is not necessary to define `Archiveprefix` in the `.bib` file. A missing `Archiveprefix` is assumed to be `arXiv`.
+* For documents that are available only as an arXiv eprint, the best result is obtained with a BibTeX entry using the `@article` class, with, e.g., `arXiv:2003.10132` in the `Journal` field, and, e.g., `10.48550/ARXIV.2003.10132` in the `Doi` field (but no `eprint` field).
+* Use `@string` macros for abbreviated journal names, with the caveat of [#31](https://github.com/Humans-of-Julia/BibParser.jl/issues/31) and [#32](https://github.com/Humans-of-Julia/BibParser.jl/issues/32) in the [BibParser.jl issues](https://github.com/Humans-of-Julia/BibParser.jl/issues).
+
+
+You may be interested in using (or forking) the [`getbibtex` script](https://github.com/goerz/getbibtex) to generate consistent `.bib` files.

src/DocumenterCitations.jl

@@ -148,6 +148,24 @@ end
 Base.show(io::IO, ::AlphaStyle) = print(io, "AlphaStyle()")
 
 
+# Work around https://github.com/Humans-of-Julia/BibInternal.jl/issues/22
+# This is a monkey-patch of the original routine. We give it preference with
+# the type annotation `::String` for the id.
+function Bibliography.BibInternal.make_bibtex_entry(id::String, fields; check=:error)
+    # "eprint" ∈ keys(fields) && (fields["_type"] = "eprint")  # bug #22
+    fields = Dict(lowercase(k) => v for (k, v) in fields) # lowercase tag names
+    errors = Bibliography.BibInternal.check_entry(fields, check, id)
+    if length(errors) > 0 && check ∈ [:error, :warn]
+        message =
+            "Entry $id is missing the " *
+            foldl(((x, y) -> x * ", " * y), errors) *
+            " field(s)."
+        check == :error ? (@error message) : (@warn message)
+    end
+    return Bibliography.BibInternal.Entry(id, fields)
+end
+
+
 include("citations.jl")
 include("bibliography.jl")
 include("formatting.jl")