Add support for Urldate field

NEWS.md

@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Functions `DocumenterCitations.set_latex_options` and `DocumenterCitations.reset_latex_options` to tweak the rendering of bibliographies in PDFs.
 * The `Pages` in a `@bibliography` block can now use `@__FILE__` to refer to the current file. [[#22][]]
 * You may now use `\url` and `\href` commands in the `@misc` field of an entry.
+* The `Urldate` field is now supported for citing websites. [[#53][]]
 
 ### Internal Changes
 
@@ -116,6 +117,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [1.2.0]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/JuliaDocs/DocumenterCitations.jl/compare/v0.2.12...v1.0.0
+[#53]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/53
 [#42]: https://github.com/JuliaDocs/DocumenterCitations.jl/pull/42
 [#40]: https://github.com/JuliaDocs/DocumenterCitations.jl/pull/40
 [#39]: https://github.com/JuliaDocs/DocumenterCitations.jl/issues/39

Project.toml

@@ -6,6 +6,7 @@ version = "1.2.1+dev"
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
 Bibliography = "f1be7e48-bf82-45af-a471-ae754a193061"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"

docs/latex/.gitignore

@@ -1,4 +1,6 @@
 *.pdf
+*.xml
+*.bcf
 *.aux
 *.log
 *.toc

docs/latex/Makefile

@@ -1,6 +1,6 @@
 .PHONY: all clean
 
-ALL = numeric.pdf authoryear.pdf rmp.pdf prb.pdf alpha.pdf
+ALL = numeric.pdf authoryear.pdf rmp.pdf prb.pdf alpha.pdf biblatex.pdf
 
 all: $(ALL)
 
@@ -34,6 +34,12 @@ alpha.pdf: alpha.tex
 	pdflatex $<
 	pdflatex $<
 
+biblatex.pdf: biblatex.tex
+	pdflatex $<
+	biber $(basename $<)
+	pdflatex $<
+	pdflatex $<
+
 clean:
 	@rm -f ${ALL}
 	@rm -f *.aux
@@ -50,6 +56,8 @@ clean:
 	@rm -f *.table
 	@rm -f *.dvi
 	@rm -f *.fls
+	@rm -f *.xml
+	@rm -f *.bcf
 	@rm -f *~
 	@rm -f *Notes.bib
 	@rm -f *-eps-converted-to.pdf

docs/latex/biblatex.tex

@@ -0,0 +1,47 @@
+\documentclass{article}
+
+\def\Author{Michael Goerz}
+\def\Title{Demo of the Biblatex numeric citation style}
+
+\usepackage[utf8]{inputenc}
+\usepackage{caption}
+\captionsetup{justification=raggedright, singlelinecheck=true}
+\usepackage[
+  pdftitle={\Title},
+  pdfauthor={\Author},
+  colorlinks=true, linkcolor=magenta, urlcolor=black, citecolor=magenta,
+  bookmarksopen=false, breaklinks=true, plainpages=false, pdfpagelabels
+]{hyperref}
+
+\usepackage[style=numeric]{biblatex}
+\addbibresource{refs.bib}
+
+\begin{document}
+
+\title{\Title}
+\author{\Author}
+\date{\today}
+
+\maketitle
+
+\begin{itemize}
+  \item \verb|\cite{GoerzQ2022}| renders as ``\cite{GoerzQ2022}''.
+  %\item \verb|\citet{GoerzQ2022}| renders as ``\citet{GoerzQ2022}''.
+  %\item \verb|\citep{GoerzQ2022}| renders as ``\citep{GoerzQ2022}''.
+  \item \verb|\cite[Eq.~(1)]{GoerzQ2022}| renders as ``\cite[Eq.~(1)]{GoerzQ2022}''.
+  %\item \verb|\citet[Eq.~(1)]{GoerzQ2022}| renders as ``\citet[Eq.~(1)]{GoerzQ2022}''.
+  %\item \verb|\citep[Eq.~(1)]{GoerzQ2022}| renders as ``\citep[Eq.~(1)]{GoerzQ2022}''.
+  %\item \verb|\citet*{GoerzQ2022}| renders as ``\citet*{GoerzQ2022}''.
+  %\item \verb|\citep*{GoerzQ2022}| renders as ``\citep*{GoerzQ2022}''.
+  %\item \verb|\citet*[Eq.~(1)]{GoerzQ2022}| renders as ``\citet*[Eq.~(1)]{GoerzQ2022}''.
+  %\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}
+  \item Refs.~\cite[and references therein]{WinckelIP2008,BrumerShapiro2003,BrifNJP2010,Shapiro2012,KochJPCM2016,GoerzQ2022,SolaAAMOP2018,MorzhinRMS2019,KochEPJQT2022}.
+  \item Ref.~\cite{WP_Schroedinger}
+\end{itemize}
+
+\printbibliography
+
+\end{document}

docs/latex/numeric.tex

@@ -39,6 +39,7 @@
   \item \verb|\Citet{WinckelIP2008}| renders as ``\Citet{WinckelIP2008}''.
   \item \cite{GoerzPhd2015} and \cite{Luc-KoenigEPJD2004}
   \item Refs.~\cite[and references therein]{WinckelIP2008,BrumerShapiro2003,BrifNJP2010,Shapiro2012,KochJPCM2016,GoerzQ2022,SolaAAMOP2018,MorzhinRMS2019,KochEPJQT2022}.
+  \item Ref.~\cite{WP_Schroedinger}
 \end{itemize}
 
 Further commands that we do not support in markdown:

docs/latex/refs.bib

@@ -117,3 +117,12 @@ @phdthesis{GoerzPhd2015
     url = {https://kobra.uni-kassel.de/handle/123456789/2015052748381},
     Year = {2015},
 }
+
+@misc{WP_Schroedinger,
+    Author = {Wikipedia},
+    Title = {Schrödinger equation},
+    url = {https://en.wikipedia.org/wiki/Schrödinger_equation},
+    year = {2023},
+    urldate={2023-10-24},
+    note={Online},
+}

docs/src/refs.bib

@@ -678,3 +678,11 @@ @misc{jax
   url = {https://github.com/google/jax},
   note = {\url{https://numpy.org}},
 }
+
+
+@misc{WP_Schroedinger,
+    Author = {Wikipedia:},
+    Title = {Schrödinger equation},
+    url = {https://en.wikipedia.org/wiki/Schrödinger_equation},
+    urldate={2023-10-24},
+}

docs/src/syntax.md

@@ -188,7 +188,7 @@ The [`refs.bib`](./refs.bib) file is in the standard [BibTeX format](https://www
 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 will usually, but not always 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.
 
 In contrast, `DocumenterCitations` only parses a subset of LaTeX syntax and converts it to markdown. This includes the [commands for special symbols](https://www.bibtex.org/SpecialSymbols/) (although unicode is preferred) and a handful of commands like [`\url` and `\href`](https://www.overleaf.com/learn/latex/Hyperlinks#Linking_web_addresses).  If you would like to have support added  for a specific additional command, [please open an issue](https://github.com/JuliaDocs/DocumenterCitations.jl/issues/new/choose).
-In addition, `DocumeterCitations` recognizes and preserves in-line math and removes braces.
+In addition, `DocumenterCitations` recognizes and preserves in-line math and removes braces.
 
 "Any `.bib` file will render the bibliography you expect" is not a design goal of `DocumenterCitations`: "It is possible to write a `.bib` file so that you get exactly the bibliography you want", and "Most reasonably clean `.bib` files that work with BibTeX should work out of the box" are.
 
@@ -198,6 +198,7 @@ Some tips to keep in mind when editing a `.bib` file to be used with `Documenter
 * You do not need to use [braces to protect capitalization](https://texfaq.org/FAQ-capbibtex). Unlike `bibtex`, `DocumenterCitation` will preserve the capitalization of titles. You should always put the title in the `.bib` file as it appears in the published paper.
 * 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.
+* When citing websites [WP_Schroedinger](@cite), in addition to the `Url` field, a `Urldate` field may be given in the format `YYYY-MM-DD`. This will be rendered as, e.g., "Accessed on Oct 24, 2023".
 * 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).
 
 

src/DocumenterCitations.jl

@@ -14,6 +14,7 @@ using Markdown
 using Bibliography: Bibliography, xyear, xlink, xtitle
 using OrderedCollections: OrderedDict, OrderedSet
 using Unicode
+using Dates: Dates, @dateformat_str
 
 export CitationBibliography
 

src/formatting.jl

@@ -1,5 +1,11 @@
 # helper functions to render references in various styles
 
+_URLDATE_FMT = Dates.DateFormat("u d, Y", "english")
+_URLDATE_ACCESSED_ON = "Accessed on "
+# We'll leave this not a `const`, as a way for people to "hack" this with
+# `eval`
+
+
 function linkify(text, link)
     if isempty(text)
         text = link
@@ -272,6 +278,34 @@ function format_note(entry)
 end
 
 
+function format_urldate(entry; accessed_on=_URLDATE_ACCESSED_ON, fmt=_URLDATE_FMT)
+    urldate = strip(get(entry.fields, "urldate", ""))
+    if urldate != ""
+        if entry.access.url == ""
+            @warn "Entry $(entry.id) defines an 'urldate' field, but no 'url' field."
+        end
+        formatted_date = urldate
+        try
+            date = Dates.Date(urldate, dateformat"yyyy-mm-dd")
+            formatted_date = Dates.format(date, fmt)
+        catch exc
+            if exc isa ArgumentError
+                @warn "Invalid field urldate = $(repr(urldate)). Must be in the format YYYY-MM-DD. $exc"
+                # We'll continue with the unformatted `formatted_date = urldate`
+            else
+                # Most likely, a MethodError because there's something wrong
+                # with `fmt`.
+                @error "Check if fmt=$(repr(fmt)) is a valid dateformat!"
+                rethrow()
+            end
+        end
+        return "$accessed_on$formatted_date"
+    else
+        return ""
+    end
+end
+
+
 function format_year(entry)
     year = entry.date.year |> tex_to_markdown
     return year
@@ -338,14 +372,14 @@ function _join_bib_parts(parts)
         mdstr = ""
     elseif length(parts) == 1
         mdstr = strip(parts[1])
-        if !endswith(_strip_md_formatting(mdstr), r"[.!?]")
+        if !endswith(_strip_md_formatting(mdstr), r"[:.!?]")
             mdstr *= "."
         end
     else
         mdstr = strip(parts[1])
         rest = _join_bib_parts(parts[2:end])
         rest_text = _strip_md_formatting(rest)
-        if endswith(_strip_md_formatting(mdstr), r"[,;.!?]") || startswith(rest_text, "(")
+        if endswith(_strip_md_formatting(mdstr), r"[:,;.!?]") || startswith(rest_text, "(")
             mdstr *= " " * rest
         else
             if uppercase(rest_text[1]) == rest_text[1]

src/labeled_styles_utils.jl

@@ -217,21 +217,35 @@ function citation_label end  # implemented by various styles
 """Format a bibliography reference as in a "labeled" style.
 
 ```julia
-mdstr = format_labeled_bibliography_reference(style, entry; namesfmt=:last)
+mdstr = format_labeled_bibliography_reference(
+    style, entry;
+    namesfmt=:last,
+    urldate_accessed_on="Accessed on ",
+    urldate_fmt=dateformat"u d, Y",
+)
 ```
 
 # Options
 
 * `namesfmt`: How to format the author names (`:full`, `:last`, `:lastonly`)
+* `urldate_accessed_on`: The prefix for a rendered `urldate` field.
+* `urldate_fmt`: The format in which to render an `urldate` field.
 """
-function format_labeled_bibliography_reference(style, entry; namesfmt=:last)
+function format_labeled_bibliography_reference(
+    style,
+    entry;
+    namesfmt=:last,
+    urldate_accessed_on=_URLDATE_ACCESSED_ON,
+    urldate_fmt=_URLDATE_FMT,
+)
     authors = format_names(entry; names=namesfmt)
     title = format_title(entry)
     published_in = format_published_in(entry)
     eprint = format_eprint(entry)
+    urldate = format_urldate(entry; accessed_on=urldate_accessed_on, fmt=urldate_fmt)
     note = format_note(entry)
     parts = String[]
-    for part in (authors, title, published_in, eprint, note)
+    for part in (authors, title, published_in, eprint, urldate, note)
         if !isempty(part)
             push!(parts, part)
         end

src/styles/authoryear.jl

@@ -109,20 +109,28 @@ end
 
 ```julia
 mdstr = format_authoryear_bibliography_reference(
-    style, entry; namesfmt=:lastfirst, empty_names="—"
+    style, entry;
+    namesfmt=:lastfirst,
+    empty_names="—",
+    urldate_accessed_on="Accessed on ",
+    urldate_fmt=dateformat"u d, Y",
 )
 ```
 
 # Options
 
 * `namesfmt`: How to format the author names (`:full`, `:last`, `:lastonly`)
 * `empty_names`: String to use in place of the authors if there are no authors
+* `urldate_accessed_on`: The prefix for a rendered `urldate` field.
+* `urldate_fmt`: The format in which to render an `urldate` field.
 """
 function format_authoryear_bibliography_reference(
     style,
     entry;
     namesfmt=:lastfirst,
-    empty_names="—"
+    empty_names="—",
+    urldate_accessed_on=_URLDATE_ACCESSED_ON,
+    urldate_fmt=_URLDATE_FMT,
 )
     authors = format_names(entry; names=namesfmt)
     year = format_year(entry)
@@ -135,9 +143,10 @@ function format_authoryear_bibliography_reference(
     title = format_title(entry)
     published_in = format_published_in(entry; include_date=false)
     eprint = format_eprint(entry)
+    urldate = format_urldate(entry; accessed_on=urldate_accessed_on, fmt=urldate_fmt)
     note = format_note(entry)
     parts = String[]
-    for part in (authors, year, title, published_in, eprint, note)
+    for part in (authors, year, title, published_in, eprint, urldate, note)
         if !isempty(part)
             push!(parts, part)
         end

test/Project.toml

@@ -2,6 +2,7 @@
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
 Bibliography = "f1be7e48-bf82-45af-a471-ae754a193061"
 Coverage = "a2441757-f6aa-5fb2-8edb-039e3f45d037"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 IOCapture = "b5f81e59-6552-4d32-b1f0-c071b021bf89"