Package citations

M2/Macaulay2/editors/prism/index.js

@@ -1,3 +1,4 @@
 import Prism from 'prismjs';
 import macaulay2 from './macaulay2.js';
+import 'prismjs-bibtex';
 import "./prism-M2.css";

M2/Macaulay2/editors/prism/package.json

@@ -3,7 +3,8 @@
     "build": "webpack"
   },
   "dependencies": {
-    "prismjs": "^1.29.0"
+    "prismjs": "^1.29.0",
+    "prismjs-bibtex": "^2.1.0"
   },
   "devDependencies": {
     "css-loader": "^7.1.2",

M2/Macaulay2/m2/document.m2

@@ -647,6 +647,7 @@ KeywordFunctions := new HashTable from {
     Acknowledgement => val -> getSubsection(val, "Acknowledgement"),
     Contributors    => val -> getSubsection(val, "Contributors"),
     References      => val -> getSubsection(val, "References"),
+    Citation        => identity, -- TODO: eventually might want to process this
     Caveat          => val -> getSubsection(val, "Caveat"),
     SeeAlso         => val -> getSubsection(UL (TO \ enlist val), "See also"),
     Subnodes        => val -> getSubnodes enlist val,
@@ -665,6 +666,7 @@ documentOptions := new OptionTable from {
     Acknowledgement => null,
     Contributors => null,
     References => null,
+    Citation => null,
     Caveat => null,
     SeeAlso => null,
     Subnodes => null,

M2/Macaulay2/m2/exports.m2

@@ -106,6 +106,7 @@ export {
 	"ChainComplexMap",
 	"ChangeMatrix",
 	"CheckDocumentation",
+	"Citation",
 	"ClosestFit",
 	"CodimensionLimit",
 	"CoefficientRing",

M2/Macaulay2/m2/help.m2

@@ -219,6 +219,8 @@ documentationValue(Symbol, Package)         := (S, pkg) -> if pkg =!= Core then
     fn := pkg#"pkgname" | ".m2";
     -- authors
     au := pkg.Options.Authors;
+    -- citation
+    ci := citePackage pkg;
     -- exported symbols
     -- TODO: this misses exported symbols from Macaulay2Doc; is this intentional?
     e := toSequence pkg#"exported symbols";
@@ -268,6 +270,12 @@ documentationValue(Symbol, Package)         := (S, pkg) -> if pkg =!= Core then
 	    SUBSECTION "Version",
 	    PARA { "This documentation describes version ", BOLD pkg.Options.Version, " of ",
 		if pkg#"pkgname" === "Macaulay2Doc" then "Macaulay2" else pkg#"pkgname", "." }},
+	if instance(ci, DIV) then ci else DIV {
+	    SUBSECTION "Citation",
+	    PARA "If you have used this package in your research, please cite it as follows:",
+	    TABLE {"class" => "examples",
+		TR TD PRE prepend("class" => "language-bib", CODE ci)}
+	    },
 	if pkg#"pkgname" =!= "Macaulay2Doc" and #e + #m > 0 then DIV {
 	    SUBSECTION "Exports",
 	    DIV { "class" => "exports",
@@ -429,6 +437,7 @@ getData = (key, tag, rawdoc) -> (
 	Acknowledgement => getOption(rawdoc, Acknowledgement),
 	Contributors    => getOption(rawdoc, Contributors),
 	References      => getOption(rawdoc, References),
+	Citation        => getOption(rawdoc, Citation),
 	Caveat          => getOption(rawdoc, Caveat),
 	SeeAlso         => getOption(rawdoc, SeeAlso),
 	Subnodes        => getOption(rawdoc, Subnodes),
@@ -461,8 +470,8 @@ getBody := (key, tag, rawdoc) -> (
     DIV nonnull splice (
 	data := getData(key, tag, rawdoc);
 	HEADER1 toList data.Headline,
-	apply(("Synopsis", Description, SourceCode, Acknowledgement,
-		Contributors, References, Caveat, SeeAlso, Subnodes, "WaysToUse"),
+	apply(("Synopsis", Description, SourceCode, Acknowledgement, Contributors,
+		References, Caveat, SeeAlso, Subnodes, "WaysToUse"),
 	    section -> if data#?section then data#section)
         )
     )
@@ -582,6 +591,15 @@ briefDocumentation = key -> (
 ? Thing    := -- TODO: does this interfere with anything?
 ? Type     := briefDocumentation
 
+-----------------------------------------------------------------------------
+-- extract the citation guide from the documentation or package info
+-----------------------------------------------------------------------------
+-- this is used by cite from PackageCitations
+citePackage = pkg -> (
+    tag := makeDocumentTag pkg;
+    rawdoc := fetchAnyRawDocumentation tag;
+    getOption(rawdoc, Citation) ?? (symbolFrom("PackageCitations", "iCite")) pkg)
+
 -----------------------------------------------------------------------------
 -- get a list of commands whose name matches the regex
 -----------------------------------------------------------------------------

M2/Macaulay2/packages/PackageCitations.m2

@@ -49,6 +49,8 @@ export {
     --"headlineToTex" -- internal method
     }
 
+importFrom_Core { "citePackage" }
+
 -- store for the TeX equivalent of needed diacritics and symbols
 -- add symbols as needed
 -- note that the length of a diacritic (as a string in M2) is 2
@@ -197,13 +199,12 @@ iCite Package := P -> (
             "@misc{", T, "Source,\n",
                 concatenate ("  title = {", bibPackageTitle, "},\n"),
                 concatenate ("  author = {", bibPackageAuthors, "},\n"),
-                concatenate (///  howpublished = {A \emph{Macaulay2} package available at ///, bibPackageSource, "}\n"),
+                concatenate (///  howpublished = {A \emph{Macaulay2} package available at///, newline, 4, bibPackageSource, "}\n"),
             "}\n",
             bibtexCert);
     bibtexString
     )
 
-
 iCite String := S -> (
     if S === "M2" then return (
         concatenate (
@@ -212,14 +213,11 @@ iCite String := S -> (
             "  title = {Macaulay2, a software system for research in algebraic geometry},\n",
             "  howpublished = {Available at ", ///\///, "url{https://macaulay2.com/}}\n",
             "}\n",
-            ))
-    else
-        L := select (1, loadedPackages, p -> toString p === S);
-        P := if #L === 1 then L#0 else loadPackage S;
-    return iCite P)
+            ));
+    iCite needsPackage S)
 
 -- The cite command
-cite = new Command from (T -> if T === () then iCite "M2" else iCite T)
+cite = new Command from (T -> if T === () or T === "M2" then iCite "M2" else citePackage T)
 
 ------------------------
 -- End of source code --

M2/Macaulay2/packages/SimpleDoc.m2

@@ -82,12 +82,13 @@ NodeFunctions = new HashTable from {
     "Usage"           => (textlines, keylinenum) -> Usage           => multiString(Usage, textlines, keylinenum),
     "Inputs"          => (textlines, keylinenum) -> Inputs          => items(textlines, keylinenum),
     "Outputs"         => (textlines, keylinenum) -> Outputs         => items(textlines, keylinenum),
-    "Consequences"    => (textlines, keylinenum) -> Consequences    => applySplit(ConsequencesFuntions, textlines),
+    "Consequences"    => (textlines, keylinenum) -> Consequences    => applySplit(ConsequencesFunctions, textlines),
     "Description"     => (textlines, keylinenum) -> toSequence applySplit(DescriptionFunctions, textlines),
     "Synopsis"        => (textlines, keylinenum) -> SYNOPSIS   applySplit(SynopsisFunctions, textlines),
     "Acknowledgement" => (textlines, keylinenum) -> Acknowledgement => DIV markup(textlines, keylinenum),
     "Contributors"    => (textlines, keylinenum) -> Contributors    => DIV markup(textlines, keylinenum),
     "References"      => (textlines, keylinenum) -> References      => DIV markup(textlines, keylinenum),
+    "Citation"        => (textlines, keylinenum) -> Citation        => getTeX(textlines, keylinenum), -- TODO: return TEX?
     "Caveat"          => (textlines, keylinenum) -> Caveat          => DIV markup(textlines, keylinenum),
     "SeeAlso"         => (textlines, keylinenum) -> SeeAlso         => apply(getNonempty textlines, value),
     "Subnodes"        => (textlines, keylinenum) -> Subnodes        => submenu(textlines, keylinenum),
@@ -115,7 +116,7 @@ DescriptionFunctions = new HashTable from {
     "Code"          => (textlines, keylinenum) -> getCode(textlines, keylinenum),
     }
 
-ConsequencesFuntions = new HashTable from {
+ConsequencesFunctions = new HashTable from {
     "Item" => (textlines, keylinenum) -> flatten \\ toList \ markup(textlines, keylinenum)
     }
 
@@ -279,6 +280,9 @@ getExample = (textlines, keylinenum, canned) -> (
     EXAMPLE if canned then { PRE reassemble(getIndent textlines#0, textlines) }
     else apply(splitByIndent(textlines, false), (i, j) -> reassemble(getIndent textlines#0, take(textlines, {i,j}))))
 
+-- TODO: use keylinenum for error reporting
+getTeX = (textlines, keylinenum) -> reassemble(getIndent textlines#0, textlines)
+
 -- Checking for common errors in a processed documentation node
 nodeCheck = (processed, keylinenum) -> (
     -- TODO: add more checks

M2/Macaulay2/packages/SimpleDoc/doc.txt

@@ -225,15 +225,17 @@ Node
         { TOH Acknowledgement, BR{},
           TOH Contributors, BR{},
           TOH References,
+          TOH Citation,
             PARA {
                 "The text in these sections is parsed and rendered similar to the ",
                 TO Text, " subsection and can be used to acknowledge funding sources,
-                collaborators, and non-author contributors, or to provide references.
+                collaborators, and non-author contributors, or to provide references
+		or a preferred style citing the package in academic papers.
 		You can also use the ", TT "Tree", " keyword in the first line of this
 		section and use the nested tree structure described above." }},
         { TOH Caveat,
             PARA {
-                "The text in these sections is parsed and rendered similar to the ",
+                "The text in this section is parsed and rendered similar to the ",
                 TO Text, " subsection and can be used to inform users of potential
                 limits of the implementation."}},
         { TOH SeeAlso,

M2/Macaulay2/packages/SimpleDoc/example.m2

@@ -83,6 +83,8 @@ docExample = "doc ///
     Acknowledge contributors who are not listed as authors here.
   References
     Provide references for further reading.
+  Citation
+    Here is how to cite this package.
   Caveat
     This is not a particularly useful function.
   SeeAlso

M2/Macaulay2/packages/TerraciniLoci.m2

@@ -127,6 +127,17 @@ doc ///
 
       This package exports one method, @TO terraciniLocus@, for computing the
       ideals of these varieties.
+  Citation
+    @article{Galuppi_2025,
+      title={Geometry of First Nonempty Terracini Loci},
+      ISSN={1793-6683},
+      url={http://dx.doi.org/10.1142/S0219199725500531},
+      DOI={10.1142/s0219199725500531},
+      journal={Communications in Contemporary Mathematics},
+      publisher={World Scientific Pub Co Pte Ltd},
+      author={Galuppi, Francesco and Santarsiero, Pierpaola and Torrance, Douglas A. and Turatti, Ettore Teixeira},
+      year={2025},
+      month=apr }
 ///
 
 doc ///