fix(Cite): Alter citation modes; add docs

py/stencila/schema/types.py

@@ -6,7 +6,7 @@
 from typing import Any, Dict, List as Array, Optional, Union
 from enum import Enum
 
-ECitationMode = Enum("CitationMode", ["normal", "suppressAuthor"])
+ECitationMode = Enum("CitationMode", ["parenthetical", "narrative", "narrative-author", "narrative-year", "normal", "suppressAuthor"])
 
 EItemListOrder = Enum("ItemListOrder", ["ascending", "descending", "unordered"])
 
@@ -110,7 +110,7 @@ class Cite(Entity):
     """The target of the citation (URL or reference ID)."""
 
     citationMode: Optional["ECitationMode"] = None
-    """How the cite is rendered in the surrounding text."""
+    """Determines how the citation is shown within the surrounding text."""
 
     content: Optional[Array["InlineContent"]] = None
     """Optional structured content/text of this citation."""
@@ -127,10 +127,10 @@ class Cite(Entity):
 """
 
     prefix: Optional[str] = None
-    """A prefix to show before the citation."""
+    """Text to show before the citation."""
 
     suffix: Optional[str] = None
-    """A suffix to show after the citation."""
+    """Text to show after the citation."""
 
 
     def __init__(

r/R/types.R

@@ -89,15 +89,15 @@ BooleanValidator <- function(
 #'
 #' @name Cite
 #' @param target The target of the citation (URL or reference ID). \bold{Required}.
-#' @param citationMode How the cite is rendered in the surrounding text.
+#' @param citationMode Determines how the citation is shown within the surrounding text.
 #' @param content Optional structured content/text of this citation.
 #' @param id The identifier for this item.
 #' @param meta Metadata associated with this item.
 #' @param pageEnd The page on which the work ends; for example "138" or "xvi".
 #' @param pageStart The page on which the work starts; for example "135" or "xiii".
 #' @param pagination Any description of pages that is not separated into pageStart and pageEnd; for example, "1-6, 9, 55".
-#' @param prefix A prefix to show before the citation.
-#' @param suffix A suffix to show after the citation.
+#' @param prefix Text to show before the citation.
+#' @param suffix Text to show after the citation.
 #' @return A `list` of class `Cite`
 #' @seealso \code{\link{Entity}}
 #' @export
@@ -119,7 +119,7 @@ Cite <- function(
   )
   self$type <- as_scalar("Cite")
   self[["target"]] <- check_property("Cite", "target", TRUE, missing(target), "character", target)
-  self[["citationMode"]] <- check_property("Cite", "citationMode", FALSE, missing(citationMode), Enum("normal", "suppressAuthor"), citationMode)
+  self[["citationMode"]] <- check_property("Cite", "citationMode", FALSE, missing(citationMode), Enum("parenthetical", "narrative", "narrative-author", "narrative-year", "normal", "suppressAuthor"), citationMode)
   self[["content"]] <- check_property("Cite", "content", FALSE, missing(content), Array(InlineContent), content)
   self[["pageEnd"]] <- check_property("Cite", "pageEnd", FALSE, missing(pageEnd), Union("numeric", "character"), pageEnd)
   self[["pageStart"]] <- check_property("Cite", "pageStart", FALSE, missing(pageStart), Union("numeric", "character"), pageStart)

schema/Cite.schema.yaml

@@ -8,11 +8,32 @@ description: |
 properties:
   citationMode:
     '@id': stencila:citationMode
-    description: How the cite is rendered in the surrounding text.
+    description: Determines how the citation is shown within the surrounding text.
     type: string
     enum:
-      - normal
-      - suppressAuthor
+      - parenthetical
+      - narrative
+      - narrative-author
+      - narrative-year
+      # Deprecated mode names: retained for backwards compatibility
+      # TODO: Remove in v2
+      - normal # == parenthetical
+      - suppressAuthor # == narrative-year
+    $comment: |
+      There are two main citation modes: parenthetical and narrative (a.k.a textual).
+      See https://apastyle.apa.org/style-grammar-guidelines/citations/basic-principles/parenthetical-versus-narrative
+      for an explanation.
+
+      Narrative citations will usually be of form "As noted by Smith (1992)," but `narrative-author`
+      allows for "In the early nineties, Smith noted" and `narrative-year` allows for "As noted by Smith in 1992 and 1993".
+
+      Pandoc's `CitationMode` enumeration has `Normal` (for `parenthetical`), `AuthorInText` (for `textual`),
+      and `SuppressAuthor` (for `textual-year`).
+      See https://github.com/jgm/pandoc-types/blob/0158cd0e2a2ca9d6f14389a1a57bc64cab45a7dd/src/Text/Pandoc/Definition.hs#L353.
+
+      LaTeX's `natbib` package has `\citep{}` (for `parenthetical`), `\citet{}` (for `textual`),
+      `\citeauthor{}` (for `textual-author`), `\citeyear{}` (for `textual-year`).
+      See https://www.overleaf.com/learn/latex/Natbib_citation_styles.
   content:
     '@id': stencila:content
     description: Optional structured content/text of this citation.
@@ -39,11 +60,11 @@ properties:
     type: string
   prefix:
     '@id': stencila:citationPrefix
-    description: A prefix to show before the citation.
+    description: Text to show before the citation.
     type: string
   suffix:
     '@id': stencila:citationSuffix
-    description: A suffix to show after the citation.
+    description: Text to show after the citation.
     type: string
   target:
     '@id': stencila:target

schema/CiteGroup.schema.yaml

@@ -3,8 +3,14 @@ title: CiteGroup
 extends: Entity
 role: secondary
 status: unstable
-description: |
-  A group of `Cite` nodes
+description: A group of `Cite` nodes
+$comment: |
+  This type allows us to group associated citations together.
+  At present we do not give a `citationMode` property to a `CiteGroup` since
+  they will almost always be parenthetical as opposed to narrative.
+  In other words, it usually only makes sense for individual `Cite` nodes to be
+  narrative (although they may be connected together within `content` using words
+  such as "and").
 properties:
   items:
     '@id': schema:itemListElement