Merge pull request #251 from rgieseke/feat/note-spec

feat(Note): Draft Note specification

py/stencila/schema/types.py

@@ -10,6 +10,8 @@
 
 EItemListOrder = Enum("ItemListOrder", ["ascending", "descending", "unordered"])
 
+ENoteType = Enum("NoteType", ["Footnote", "Endnote", "Sidenote"])
+
 ESessionStatus = Enum("SessionStatus", ["unknown", "starting", "started", "stopping", "stopped", "failed"])
 
 ECellType = Enum("CellType", ["data", "header"])
@@ -2178,6 +2180,35 @@ def __init__(
 
 
 
+class Note(Entity):
+    """
+    Additional content which is not part of the main content of a document.
+    """
+
+    content: Array["BlockContent"]
+    """Content of the note, usually a paragraph."""
+
+    noteType: Optional["ENoteType"] = None
+    """Determines where the note content is displayed within document."""
+
+
+    def __init__(
+        self,
+        content: Array["BlockContent"],
+        id: Optional[str] = None,
+        meta: Optional[Dict[str, Any]] = None,
+        noteType: Optional["ENoteType"] = None
+    ) -> None:
+        super().__init__(
+            id=id,
+            meta=meta
+        )
+        if content is not None:
+            self.content = content
+        if noteType is not None:
+            self.noteType = noteType
+
+
 class Organization(Thing):
     """An organization such as a school, NGO, corporation, club, etc."""
 
@@ -3926,7 +3957,7 @@ def __init__(
 """
 All type schemas that are derived from Entity
 """
-EntityTypes = Union["Entity", "ArrayValidator", "Article", "AudioObject", "BooleanValidator", "Brand", "Cite", "CiteGroup", "Code", "CodeBlock", "CodeChunk", "CodeError", "CodeExpression", "CodeFragment", "Collection", "Comment", "ConstantValidator", "ContactPoint", "CreativeWork", "Datatable", "DatatableColumn", "Date", "DefinedTerm", "Delete", "Emphasis", "EnumValidator", "Figure", "Function", "Grant", "Heading", "ImageObject", "Include", "IntegerValidator", "Link", "List", "ListItem", "Mark", "Math", "MathBlock", "MathFragment", "MediaObject", "MonetaryGrant", "NontextualAnnotation", "NumberValidator", "Organization", "Paragraph", "Parameter", "Periodical", "Person", "PostalAddress", "Product", "PropertyValue", "PublicationIssue", "PublicationVolume", "Quote", "QuoteBlock", "Review", "SoftwareApplication", "SoftwareEnvironment", "SoftwareSession", "SoftwareSourceCode", "StringValidator", "Strong", "Subscript", "Superscript", "Table", "TableCell", "TableRow", "ThematicBreak", "Thing", "TupleValidator", "Variable", "VideoObject", "VolumeMount"]
+EntityTypes = Union["Entity", "ArrayValidator", "Article", "AudioObject", "BooleanValidator", "Brand", "Cite", "CiteGroup", "Code", "CodeBlock", "CodeChunk", "CodeError", "CodeExpression", "CodeFragment", "Collection", "Comment", "ConstantValidator", "ContactPoint", "CreativeWork", "Datatable", "DatatableColumn", "Date", "DefinedTerm", "Delete", "Emphasis", "EnumValidator", "Figure", "Function", "Grant", "Heading", "ImageObject", "Include", "IntegerValidator", "Link", "List", "ListItem", "Mark", "Math", "MathBlock", "MathFragment", "MediaObject", "MonetaryGrant", "NontextualAnnotation", "Note", "NumberValidator", "Organization", "Paragraph", "Parameter", "Periodical", "Person", "PostalAddress", "Product", "PropertyValue", "PublicationIssue", "PublicationVolume", "Quote", "QuoteBlock", "Review", "SoftwareApplication", "SoftwareEnvironment", "SoftwareSession", "SoftwareSourceCode", "StringValidator", "Strong", "Subscript", "Superscript", "Table", "TableCell", "TableRow", "ThematicBreak", "Thing", "TupleValidator", "Variable", "VideoObject", "VolumeMount"]
 
 
 """

r/NAMESPACE

@@ -59,6 +59,7 @@ export(MediaObjectTypes)
 export(MonetaryGrant)
 export(Node)
 export(NontextualAnnotation)
+export(Note)
 export(NumberValidator)
 export(NumberValidatorTypes)
 export(Organization)

r/R/types.R

@@ -2362,6 +2362,34 @@ NontextualAnnotation <- function(
 }
 
 
+#' Additional content which is not part of the main content of a document.
+#'
+#' @name Note
+#' @param content Content of the note, usually a paragraph. \bold{Required}.
+#' @param id The identifier for this item.
+#' @param meta Metadata associated with this item.
+#' @param noteType Determines where the note content is displayed within document.
+#' @return A `list` of class `Note`
+#' @seealso \code{\link{Entity}}
+#' @export
+Note <- function(
+  content,
+  id,
+  meta,
+  noteType
+){
+  self <- Entity(
+    id = id,
+    meta = meta
+  )
+  self$type <- as_scalar("Note")
+  self[["content"]] <- check_property("Note", "content", TRUE, missing(content), Array(BlockContent), content)
+  self[["noteType"]] <- check_property("Note", "noteType", FALSE, missing(noteType), Enum("Footnote", "Endnote", "Sidenote"), noteType)
+  class(self) <- c(class(self), "Note")
+  self
+}
+
+
 #' An organization such as a school, NGO, corporation, club, etc.
 #'
 #' @name Organization
@@ -4261,7 +4289,7 @@ CreativeWorkTypes <- Union(CreativeWork, Article, AudioObject, Collection, Comme
 #'
 #' @return A `list` of class `Union` describing valid subtypes of this type
 #' @export
-EntityTypes <- Union(Entity, ArrayValidator, Article, AudioObject, BooleanValidator, Brand, Cite, CiteGroup, Code, CodeBlock, CodeChunk, CodeError, CodeExpression, CodeFragment, Collection, Comment, ConstantValidator, ContactPoint, CreativeWork, Datatable, DatatableColumn, Date, DefinedTerm, Delete, Emphasis, EnumValidator, Figure, Function, Grant, Heading, ImageObject, Include, IntegerValidator, Link, List, ListItem, Mark, Math, MathBlock, MathFragment, MediaObject, MonetaryGrant, NontextualAnnotation, NumberValidator, Organization, Paragraph, Parameter, Periodical, Person, PostalAddress, Product, PropertyValue, PublicationIssue, PublicationVolume, Quote, QuoteBlock, Review, SoftwareApplication, SoftwareEnvironment, SoftwareSession, SoftwareSourceCode, StringValidator, Strong, Subscript, Superscript, Table, TableCell, TableRow, ThematicBreak, Thing, TupleValidator, Variable, VideoObject, VolumeMount)
+EntityTypes <- Union(Entity, ArrayValidator, Article, AudioObject, BooleanValidator, Brand, Cite, CiteGroup, Code, CodeBlock, CodeChunk, CodeError, CodeExpression, CodeFragment, Collection, Comment, ConstantValidator, ContactPoint, CreativeWork, Datatable, DatatableColumn, Date, DefinedTerm, Delete, Emphasis, EnumValidator, Figure, Function, Grant, Heading, ImageObject, Include, IntegerValidator, Link, List, ListItem, Mark, Math, MathBlock, MathFragment, MediaObject, MonetaryGrant, NontextualAnnotation, Note, NumberValidator, Organization, Paragraph, Parameter, Periodical, Person, PostalAddress, Product, PropertyValue, PublicationIssue, PublicationVolume, Quote, QuoteBlock, Review, SoftwareApplication, SoftwareEnvironment, SoftwareSession, SoftwareSourceCode, StringValidator, Strong, Subscript, Superscript, Table, TableCell, TableRow, ThematicBreak, Thing, TupleValidator, Variable, VideoObject, VolumeMount)
 
 
 #' All type schemas that are derived from Grant

schema/Note.schema.yaml

@@ -0,0 +1,33 @@
+title: Note
+'@id': stencila:Note
+extends: Entity
+role: secondary
+status: unstable
+description: Additional content which is not part of the main content of a document.
+$comment: |
+  A note is usually associated with a word or paragraph using a number or other symbol. 
+  It can be displayed as a footnote, endnote, or side note, or in interactive elements.
+  For analogues, see 
+  - [JATS `<fn>`](https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/fn.html)
+  - [Pandoc footnotes](https://pandoc.org/MANUAL.html#footnotes)
+  - [HTML `<aside>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside)
+properties:
+  noteType:
+    '@id': stencila:noteType
+    description: Determines where the note content is displayed within the document.
+    type: string
+    enum:
+      - Footnote
+      - Endnote
+      - Sidenote
+  content:
+    '@id': stencila:content
+    description: Content of the note, usually a paragraph.
+    type: array
+    items:
+      $ref: BlockContent
+    $comment: |
+      Most notes will have a single paragraph but could have multiple
+      paragraphs, tables and even figures.
+required:
+  - content