Auto-link both URL and DOI

This restores the DocumenterCitation 1.2 behavior of always being able to link to a URL as well as a DOI (for entries that define all required fields for their respective type).
JuliaDocs · Nov 6, 2023 · de9fd1f · de9fd1f
1 parent 392d454
commit de9fd1f
Show file tree

Hide file tree

Showing 4 changed files with 43 additions and 50 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -10,7 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Warn about markdown link syntax in `.bib` files [[#60][]]
 * Warn about invalid DOIs in `.bib` files. The DOI field should never contain a URL (`https://doi.org/...`). This is detected as a special case, and the DOI is extracted from the URL.
-
+* Automatically link both URL and DOI fields. This fixes a regression in `v1.3.0`, which would throw an error for `@book` and `@proceeding` entries with both a URL and a DOI field. Now, the DOI in such a case will be automatically linked via the `Title` field, and the DOI via the `organization`/`publisher`/`address` fields, similar to the behavior in `v1.2.0`. You may prefer to have the DOI linked via that `Title`, in which case you should add a `Note` field containing the `URL` (using `\url`/`\href`, as appropriate).
+
 
 ## [Version 1.3.1][1.3.1] - 2023-11-02
 
@@ -63,8 +64,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 For anyone who was using custom styles, which rely on the [Internals](https://juliadocs.org/DocumenterCitations.jl/stable/internals/) of `DocumenterCitations`, this release will almost certainly break the customization. See the above list of internal changes.
 
-There were some subtle changes in how DOI and URL fields are linked in the rendered documentation, which may require adjustments. In particular, in version `1.3.0`, non-`@article` entries that do not have both a `title` and a `booktitle` can only have a DOI *or* a URL, but not both. This most likely occurs for `@book` entries. For `@book` entries that have both a DOI and a URL, the URL should be placed in the `note` field (using `\url`/`\href`, as appropriate).
-
 There were several bugs and limitations in version `1.2.x` for which some existing documentations may have been using workarounds. These workarounds may cause some breakage in the new version `1.3.0`. In particular:
 
 * The `Pages` attribute in a `@bibliography` block in version `1.2.x` required any names to be relative to the `docs/src` directory [[#22][]]. This was both unintentional and undocumented. These names must now be updated to be relative to to the folder containing the file which contains the `@bibliography` block. This is consistent with how `Pages` is used, e.g., in `@contents` or `@index` blocks. For the common usage where `Pages` was referring to the current file, `@__FILE__` should be used.

diff --git a/src/formatting.jl b/src/formatting.jl
@@ -230,6 +230,7 @@ function format_published_in(
     elseif entry.type in ["book", "proceedings"]
         _push!(1, format_edition(entry))
         _push!(1, format_vol_num_series(entry; title_transform_case=title_transform_case))
+        _push!(2, tex_to_markdown(entry.in.organization))
         _push!(2, tex_to_markdown(entry.in.publisher))
         _push!(2, tex_to_markdown(entry.in.address))
         _push!(2, format_year(entry); _if=include_date)
@@ -270,7 +271,6 @@ function format_published_in(
         _push!(2, tex_to_markdown(entry.in.organization))
         _push!(2, tex_to_markdown(entry.in.publisher))
         _push!(2, tex_to_markdown(entry.in.address))
-        # TODO: month/day date???
         _push!(2, format_year(entry); _if=include_date)
         _push!(3, format_chapter(entry))
         _push!(3, format_pages(entry))
@@ -307,16 +307,20 @@ function format_published_in(
             @warn "unpublished $(entry.id) does not have a 'note'"
         end
     end
-    if length(urls) > 0
-        @warn "Could not link $(repr(urls)) in \"published in\" information for entry $(entry.id). Add a Note field that links to the URL(s)."
-    end
     mdstr = join(segments[1], ", ")
     if length(segments[2]) > 0
-        mdstr *= " (" * join(segments[2], ", ") * ")"
+        segment2 = join(segments[2], ", ")
+        if length(urls) > 0
+            segment2 = linkify(segment2, pop_url!(urls))
+        end
+        mdstr *= " (" * segment2 * ")"
     end
     if length(segments[3]) > 0
         mdstr *= "; " * join(segments[3], ", ")
     end
+    if length(urls) > 0
+        @warn "Could not link $(repr(urls)) in \"published in\" information for entry $(entry.id). Add a Note field that links to the URL(s)."
+    end
     return mdstr
 end
 

diff --git a/test/test_formatting.jl b/test/test_formatting.jl
@@ -254,61 +254,37 @@ end
     numeric = Val(:numeric)
     authoryear = Val(:authoryear)
 
-    c = IOCapture.capture() do
-        md(numeric, "JuhlARNMRS2020X")
-    end
-    @test contains(
-        c.output,
-        "Warning: Could not link [\"https://doi.org/10.1016/bs.arnmr.2019.12.001\"] in \"published in\" information for entry JuhlARNMRS2020X. Add a Note field that links to the URL(s)."
-    )
-    @Test c.value ==
-          "D. W. Juhl, Z. Tošner and T. Vosegaard. [*Versatile NMR simulations using SIMPSON*](https://pure.au.dk/portal/files/230817709/Versatile_NMR_simulations_using_SIMPSON.pdf). Vol. 100 of *Annual Reports on NMR Spectroscopy*, edited by G. A. Webb (Elsevier, 2020); Chapter 1, pp. 1–59."
-
-    c = IOCapture.capture() do
-        md(authoryear, "JuhlARNMRS2020X")
-    end
-    @test contains(
-        c.output,
-        "Warning: Could not link [\"https://doi.org/10.1016/bs.arnmr.2019.12.001\"] in \"published in\" information for entry JuhlARNMRS2020X. Add a Note field that links to the URL(s)."
-    )
-    @Test c.value ==
-          "Juhl, D. W.; Tošner, Z. and Vosegaard, T. (2020). [*Versatile NMR simulations using SIMPSON*](https://pure.au.dk/portal/files/230817709/Versatile_NMR_simulations_using_SIMPSON.pdf). Vol. 100 of *Annual Reports on NMR Spectroscopy*, edited by Webb, G. A. (Elsevier); Chapter 1, pp. 1–59."
-
-    c = IOCapture.capture() do
-        md(numeric, "Nolting1997CoulombX")
-    end
-    @test contains(
-        c.output,
-        "Warning: Could not link [\"https://doi.org/10.1007/978-3-663-14691-9\"] in \"published in\" information for entry Nolting1997CoulombX. Add a Note field that links to the URL(s)."
-    )
-    @Test c.value ==
-          "W. Nolting. In: [*Quantenmechanik*](https://link.springer.com/book/10.1007/978-3-662-44230-2), Vol. 5 no. 2 of *Grundkurs Theoretische Physik* (Vieweg & Teubner Verlag, 1997); 6th chapter, p. 100."
-
-    c = IOCapture.capture() do
-        md(authoryear, "Nolting1997CoulombX")
-    end
-    @test contains(
-        c.output,
-        "Warning: Could not link [\"https://doi.org/10.1007/978-3-663-14691-9\"] in \"published in\" information for entry Nolting1997CoulombX. Add a Note field that links to the URL(s)."
-    )
-    @Test c.value ==
-          "Nolting, W. (1997). In: [*Quantenmechanik*](https://link.springer.com/book/10.1007/978-3-662-44230-2), Vol. 5 no. 2 of *Grundkurs Theoretische Physik* (Vieweg & Teubner Verlag); 6th chapter, p. 100."
-
+    @Test md(numeric, "JuhlARNMRS2020X") ==
+          "D. W. Juhl, Z. Tošner and T. Vosegaard. [*Versatile NMR simulations using SIMPSON*](https://pure.au.dk/portal/files/230817709/Versatile_NMR_simulations_using_SIMPSON.pdf). Vol. 100 of *Annual Reports on NMR Spectroscopy*, edited by G. A. Webb ([Elsevier, 2020](https://doi.org/10.1016/bs.arnmr.2019.12.001)); Chapter 1, pp. 1–59."
+    @Test md(authoryear, "JuhlARNMRS2020X") ==
+          "Juhl, D. W.; Tošner, Z. and Vosegaard, T. (2020). [*Versatile NMR simulations using SIMPSON*](https://pure.au.dk/portal/files/230817709/Versatile_NMR_simulations_using_SIMPSON.pdf). Vol. 100 of *Annual Reports on NMR Spectroscopy*, edited by Webb, G. A. ([Elsevier](https://doi.org/10.1016/bs.arnmr.2019.12.001)); Chapter 1, pp. 1–59."
+    @Test md(numeric, "Nolting1997CoulombX") ==
+          "W. Nolting. In: [*Quantenmechanik*](https://link.springer.com/book/10.1007/978-3-662-44230-2), Vol. 5 no. 2 of *Grundkurs Theoretische Physik* ([Vieweg & Teubner Verlag, 1997](https://doi.org/10.1007/978-3-663-14691-9)); 6th chapter, p. 100."
+    @Test md(authoryear, "Nolting1997CoulombX") ==
+          "Nolting, W. (1997). In: [*Quantenmechanik*](https://link.springer.com/book/10.1007/978-3-662-44230-2), Vol. 5 no. 2 of *Grundkurs Theoretische Physik* ([Vieweg & Teubner Verlag](https://doi.org/10.1007/978-3-663-14691-9)); 6th chapter, p. 100."
     @Test md(numeric, "Shapiro2012X") ==
           "M. Shapiro and P. Brumer. [*Quantum Control of Molecular Processes*](https://onlinelibrary.wiley.com/doi/book/10.1002/9783527639700). ``2^{nd}`` Ed. (Wiley and Sons, 2012)."
     @Test md(authoryear, "Shapiro2012X") ==
           "Shapiro, M. and Brumer, P. (2012). [*Quantum Control of Molecular Processes*](https://onlinelibrary.wiley.com/doi/book/10.1002/9783527639700). ``2^{nd}`` Ed. (Wiley and Sons)."
-
     @Test md(numeric, "PercontiSPIE2016") ==
           "P. Perconti, W. C. Alberts, J. Bajaj, J. Schuster and M. Reed. [*Sensors, nano-electronics and photonics for the Army of 2030 and beyond*](https://doi.org/10.1117/12.2217797). In: *Quantum Sensing and Nano Electronics and Photonics XIII*, Vol. 9755 no. 6 of *Proceedings SPIE* (2016)."
     @Test md(authoryear, "PercontiSPIE2016") ==
           "Perconti, P.; Alberts, W. C.; Bajaj, J.; Schuster, J. and Reed, M. (2016). [*Sensors, nano-electronics and photonics for the Army of 2030 and beyond*](https://doi.org/10.1117/12.2217797). In: *Quantum Sensing and Nano Electronics and Photonics XIII*, Vol. 9755 no. 6 of *Proceedings SPIE*."
-
     @Test md(numeric, "DevoretLH1995") ==
           "M. H. Devoret. [*Quantum fluctuations in electrical circuits*](https://boulderschool.yale.edu/sites/default/files/files/devoret_quantum_fluct_les_houches.pdf). In: *Quantum Fluctuations*, Session LXIII (1995) of *the Les Houches Summer School*, edited by S. Reynaud, E. Giacobino and J. Zinn-Justin (Elsevier, 1997); Chapter 10, p. 353."
     @Test md(authoryear, "DevoretLH1995") ==
           "Devoret, M. H. (1997). [*Quantum fluctuations in electrical circuits*](https://boulderschool.yale.edu/sites/default/files/files/devoret_quantum_fluct_les_houches.pdf). In: *Quantum Fluctuations*, Session LXIII (1995) of *the Les Houches Summer School*, edited by Reynaud, S.; Giacobino, E. and Zinn-Justin, J. (Elsevier); Chapter 10, p. 353."
 
+    c = IOCapture.capture() do
+        md(numeric, "Nolting1997CoulombXX")
+    end
+    @test contains(
+        c.output,
+        "Warning: Could not link [\"https://doi.org/10.1007/978-3-663-14691-9\"] in \"published in\" information for entry Nolting1997CoulombXX."
+    )
+    @Test c.value ==
+          "W. Nolting. Vol. 5 no. 2 of *Grundkurs Theoretische Physik* ([Vieweg & Teubner Verlag, 1997](https://link.springer.com/book/10.1007/978-3-662-44230-2)); 6th chapter, p. 100."
+
 end
 
 

diff --git a/test/test_formatting/alternative_non_articles.bib b/test/test_formatting/alternative_non_articles.bib
@@ -27,6 +27,20 @@ @inbook{Nolting1997CoulombX
 }
 
 
+@inbook{Nolting1997CoulombXX,
+    author = {Wolfgang Nolting},
+    series = {Grundkurs Theoretische Physik},
+    volume = {5},
+    number = {2},
+    chapter = {{6th chapter}},
+    pages = {100},
+    doi = {10.1007/978-3-663-14691-9},
+    url = {https://link.springer.com/book/10.1007/978-3-662-44230-2},
+    year = 1997,
+    publisher = {Vieweg \& Teubner Verlag},
+}
+
+
 @book{Shapiro2012X,
     author = {Shapiro, Moshe and Brumer, Paul},
     edition = {{$2^{nd}$ Ed.}},