Improve the creation of citations

Bug #1609 has a number of great suggestions for improving citation metadata for documents. This addresses most of those suggestions, generating additional `citation_` meta tags based upon document citation data as well as making our handling of citation data more consistent.

We will newly output:
`citation_abstract`
`citation_doi`
`citation_pmid`
`citation_language`
`citation_keywords`
`citation_pdf_url`
`citation_public_url`
`citation_abstract_url`
`citation_fulltext_url`
`citation_journal_abbrev`
`citation_publisher`

Based upon the `type` specified:
`citation_conference_title`/`citation_conference`
`citation_dissertation_institution`
`citation_book_title`

General approach is to allow specification of citation data with names and structure that corresponds with CSL schema and to map those values onto the appropriate meta names (rather than matching the meta names directly).

Author: dragonstyle

src/core/csl.ts

@@ -5,7 +5,18 @@
 *
 */
 
-import { parsePandocDate } from "./date.ts";
+import { formatDate, parsePandocDate } from "./date.ts";
+
+export const kPdfUrl = "pdf-url";
+export const kAbstractUrl = "abstract-url";
+export const kEIssn = "eissn";
+
+export interface CSLExtras {
+  [kPdfUrl]?: string;
+  [kAbstractUrl]?: string;
+  [kEIssn]?: string;
+  keywords?: string[];
+}
 
 export interface CSL extends Record<string, unknown> {
   // The id. This is technically required, but some providers (like crossref) don't provide
@@ -32,14 +43,16 @@ export interface CSL extends Record<string, unknown> {
   // Array of Contributors
   author?: CSLName[];
 
+  editor?: CSLName[];
+
   // Earliest of published-print and published-online
   issued?: CSLDate;
 
   // Full titles of the containing work (usually a book or journal)
   "container-title"?: string;
 
   // Short titles of the containing work (usually a book or journal)
-  "short-container-title"?: string;
+  "container-title-short"?: string;
 
   // Issue number of an article's journal
   issue?: string;
@@ -66,7 +79,9 @@ export interface CSL extends Record<string, unknown> {
   // primarily because they may need to be sanitized
   ISSN?: string;
   ISBN?: string;
+  PMID?: string;
   "original-title"?: string;
+  "collection-title"?: string;
   "short-title"?: string;
   subtitle?: string;
   subject?: string;
@@ -247,7 +262,8 @@ export function cslDate(dateRaw: unknown): CSLDate | undefined {
           date.getMonth() + 1,
           date.getDate(),
         ]],
-        raw: dateRaw,
+        literal: formatDate(date, "YYYY-MM-DD"),
+        raw: formatDate(date, "YYYY-MM-DD"),
       };
     }
     return undefined;

src/format/html/format-html-appendix.ts

@@ -326,12 +326,12 @@ function creativeCommonsUrl(license: string, lang?: string) {
 }
 
 async function generateCite(input: string, format: Format, offset?: string) {
-  const entry = documentCSL(input, format, "webpage", offset);
-  if (entry) {
+  const { csl } = documentCSL(input, format, "webpage", offset);
+  if (csl) {
     // Render the HTML and BibTeX form of this document
     const cslPath = getCSLPath(input, format);
-    const html = await renderHtml(entry, cslPath);
-    const bibtex = await renderBibTex(entry);
+    const html = await renderHtml(csl, cslPath);
+    const bibtex = await renderBibTex(csl);
     return {
       html,
       bibtex,

src/format/html/format-html-meta.ts

@@ -8,7 +8,14 @@
 import { kHtmlEmptyPostProcessResult } from "../../command/render/constants.ts";
 import { Format, Metadata } from "../../config/types.ts";
 import { bibliographyCslJson } from "../../core/bibliography.ts";
-import { CSL, cslDateToEDTFDate } from "../../core/csl.ts";
+import {
+  CSL,
+  cslDateToEDTFDate,
+  CSLExtras,
+  kAbstractUrl,
+  kEIssn,
+  kPdfUrl,
+} from "../../core/csl.ts";
 import { Document } from "../../core/deno-dom.ts";
 import { encodeAttributeValue } from "../../core/html.ts";
 import { kWebsite } from "../../project/types/website/website-constants.ts";
@@ -24,8 +31,8 @@ export function metadataPostProcessor(
 ) {
   return async (doc: Document) => {
     if (googleScholarEnabled(format)) {
-      const csl = documentCSL(input, format, "webpage", offset);
-      const documentMetadata = googleScholarMeta(csl);
+      const { csl, extras } = documentCSL(input, format, "webpage", offset);
+      const documentMetadata = googleScholarMeta(csl, extras);
       const referenceMetadata = await googleScholarReferences(input, format);
       [...documentMetadata, ...referenceMetadata].forEach((meta) => {
         writeMetaTag(meta.name, meta.content, doc);
@@ -56,6 +63,7 @@ interface MetaTagData {
 
 function googleScholarMeta(
   csl: CSL,
+  extras: CSLExtras,
 ): MetaTagData[] {
   // The scholar metadata that we'll generate into
   const scholarMeta: MetaTagData[] = [];
@@ -66,6 +74,14 @@ function googleScholarMeta(
     write("citation_title", csl.title);
   }
 
+  if (csl.abstract) {
+    write("citation_abstract", csl.abstract);
+  }
+
+  if (extras.keywords) {
+    write("citation_keywords", extras.keywords);
+  }
+
   // Authors
   if (csl.author) {
     csl.author.forEach((author) => {
@@ -76,6 +92,26 @@ function googleScholarMeta(
     });
   }
 
+  // Editors
+  if (csl.editor) {
+    csl.editor.forEach((editor) => {
+      write(
+        "citation_editor",
+        editor.literal || `${editor.given} ${editor.family}`,
+      );
+    });
+  }
+
+  if (csl.issued) {
+    const edtfIssued = cslDateToEDTFDate(csl.issued);
+    write("citation_publication_date", edtfIssued);
+    write("citation_cover_date", edtfIssued);
+    const parts = csl.issued["date-parts"];
+    if (parts) {
+      write("citation_year", parts[0][0]);
+    }
+  }
+
   if (csl["available-date"]) {
     write("citation_online_date", cslDateToEDTFDate(csl["available-date"]));
   }
@@ -87,14 +123,22 @@ function googleScholarMeta(
     );
   }
 
-  if (csl.issued) {
-    write("citation_publication_date", cslDateToEDTFDate(csl.issued));
+  if (extras[kPdfUrl]) {
+    write("citation_pdf_url", extras[kPdfUrl]);
+  }
+
+  if (extras[kAbstractUrl]) {
+    write("citation_abstract_html_url", extras[kAbstractUrl]);
   }
 
   if (csl.issue) {
     write("citation_issue", csl.issue);
   }
 
+  if (csl.DOI) {
+    write("citation_doi", csl.DOI);
+  }
+
   if (csl.ISBN) {
     write("citation_isbn", csl.ISBN);
   }
@@ -103,10 +147,22 @@ function googleScholarMeta(
     write("citation_issn", csl.ISSN);
   }
 
+  if (extras[kEIssn]) {
+    write("citation_eissn", extras[kEIssn]);
+  }
+
+  if (csl.PMID) {
+    write("citation_pmid", csl.PMID);
+  }
+
   if (csl.volume) {
     write("citation_volume", csl.volume);
   }
 
+  if (csl.language) {
+    write("citation_language", csl.language);
+  }
+
   if (csl["page-first"]) {
     write("citation_firstpage", csl["page-first"]);
   }
@@ -117,9 +173,17 @@ function googleScholarMeta(
 
   const type = csl.type;
   if (type === "paper-conference") {
-    write("citation_conference_title", csl["container-title"]);
+    if (csl["container-title"]) {
+      write("citation_conference_title", csl["container-title"]);
+    }
+
+    if (csl.publisher) {
+      write("citation_conference", csl.publisher);
+    }
   } else if (type === "thesis") {
-    write("citation_dissertation_institution", csl.publisher);
+    if (csl.publisher) {
+      write("citation_dissertation_institution", csl.publisher);
+    }
   } else if (type === "report") {
     if (csl.publisher) {
       write(
@@ -133,8 +197,28 @@ function googleScholarMeta(
         csl.number,
       );
     }
+  } else if (type === "book") {
+    if (csl["container-title"]) {
+      write("citation_book_title", csl["container-title"]);
+    }
+  } else if (type === "chapter") {
+    write("citation_inbook_title", csl["container-title"]);
   } else {
-    write("citation_journal_title", csl["container-title"]);
+    if (csl["container-title"]) {
+      write("citation_journal_title", csl["container-title"]);
+    }
+
+    if (csl["container-title-short"]) {
+      write("citation_journal_abbrev", csl["container-title-short"]);
+    }
+
+    if (csl.publisher) {
+      write("citation_publisher", csl.publisher);
+    }
+  }
+
+  if (csl["collection-title"]) {
+    write("citation_series_title", csl["collection-title"]);
   }
 
   return scholarMeta;
@@ -149,7 +233,7 @@ async function googleScholarReferences(input: string, format: Format) {
 
   if (references) {
     references.forEach((reference) => {
-      const refMetas = googleScholarMeta(reference);
+      const refMetas = googleScholarMeta(reference, {});
       const metaStrs = refMetas.map((refMeta) => {
         return `${refMeta.name}=${refMeta.content};`;
       });

src/quarto-core/attribution/document.ts

@@ -20,9 +20,13 @@ import { pathWithForwardSlashes } from "../../core/path.ts";
 import {
   CSL,
   cslDate,
+  CSLExtras,
   cslNames,
   CSLType,
   cslType,
+  kAbstractUrl,
+  kEIssn,
+  kPdfUrl,
   suggestId,
 } from "../../core/csl.ts";
 import {
@@ -35,6 +39,7 @@ const kCitation = "citation";
 const kURL = "URL";
 const kId = "id";
 const kCitationKey = "citation-key";
+const kEditor = "editor";
 
 const kType = "type";
 const kCategories = "categories";
@@ -81,7 +86,7 @@ export function documentCSL(
   format: Format,
   defaultType: CSLType,
   offset?: string,
-) {
+): { csl: CSL; extras: CSLExtras } {
   const citationMetadata = citationMeta(format);
 
   // The type
@@ -104,12 +109,20 @@ export function documentCSL(
 
   // Author
   const authors = parseAuthor(
-    format.metadata[kAuthor] || citationMetadata[kAuthor],
+    citationMetadata[kAuthor] || format.metadata[kAuthor],
   );
   csl.author = cslNames(
     authors?.filter((auth) => auth !== undefined).map((auth) => auth?.name),
   );
 
+  // Editors
+  const editors = parseAuthor(citationMetadata[kEditor]);
+  csl.editor = cslNames(
+    editors?.filter((editor) => editor !== undefined).map((editor) =>
+      editor?.name
+    ),
+  );
+
   // Categories
   const categories =
     (citationMetadata[kCategories] || format.metadata[kCategories]);
@@ -371,7 +384,29 @@ export function documentCSL(
     csl[kCustom] = custom;
   }
 
-  return csl;
+  // Process anything extra
+  const extras: CSLExtras = {};
+  if (format.metadata.keywords) {
+    const kw = format.metadata.keywords;
+    extras.keywords = Array.isArray(kw) ? kw : [kw];
+  }
+
+  // Process extra URLS
+  if (citationMetadata[kPdfUrl]) {
+    extras[kPdfUrl] = citationMetadata[kPdfUrl] as string;
+  }
+  if (citationMetadata[kAbstractUrl]) {
+    extras[kAbstractUrl] = citationMetadata[kAbstractUrl] as string;
+  }
+
+  if (citationMetadata[kEIssn]) {
+    extras[kEIssn] = citationMetadata[kEIssn] as string;
+  }
+
+  return {
+    csl,
+    extras,
+  };
 }
 
 interface PageRange {
@@ -400,10 +435,14 @@ function synthesizeCitationUrl(
   if (baseUrl && outputFile && offset) {
     const rootDir = Deno.realPathSync(join(dirname(input), offset));
     if (outputFile === "index.html") {
-      return `${baseUrl}/${pathWithForwardSlashes(relative(rootDir, dirname(input)))}`;
+      return `${baseUrl}/${
+        pathWithForwardSlashes(relative(rootDir, dirname(input)))
+      }`;
     } else {
-      return `${baseUrl}/${pathWithForwardSlashes(
-        relative(rootDir, join(dirname(input), outputFile)))
+      return `${baseUrl}/${
+        pathWithForwardSlashes(
+          relative(rootDir, join(dirname(input), outputFile)),
+        )
       }`;
     }
   } else {

src/resources/editor/tools/vs-code.mjs

@@ -10015,6 +10015,11 @@ var require_yaml_intelligence_resources = __commonJS({
                   description: "Abstract of the item (e.g. the abstract of a journal article)"
                 }
               },
+              "abstract-url": {
+                string: {
+                  description: "A url to the abstract for this item."
+                }
+              },
               accessed: {
                 ref: "csl-date",
                 description: "Date the item has been accessed."
@@ -10228,6 +10233,11 @@ var require_yaml_intelligence_resources = __commonJS({
                 },
                 hidden: true
               },
+              "fulltext-url": {
+                string: {
+                  description: "A url to the full text for this item."
+                }
+              },
               genre: {
                 string: {
                   description: {
@@ -10424,6 +10434,11 @@ var require_yaml_intelligence_resources = __commonJS({
                 ref: "csl-person",
                 description: "Producer (e.g. of a television or radio broadcast)."
               },
+              "public-url": {
+                string: {
+                  description: "A public url for this item."
+                }
+              },
               publisher: {
                 string: {
                   description: "The publisher of the item."