Citation updates

[d-torrance]

A few updates after our discussion at M2internals yesterday:

• Add "The Macaulay2 Authors" after Dan & Mike to both the output of cite and to the "Cite this repository" button here on GitHub:

  i1 : cite
  
  o1 = @misc{M2,
         author = {Grayson, Daniel R. and Stillman, Michael E. and The Macaulay2 Authors},
         title = {Macaulay2, a software system for research in algebraic geometry},
         howpublished = {Available at \url{https://macaulay2.com/}}
       }
  

• Add citation information (with syntax highlighting!) to the documentation page for packages:
• I went back and forth how best to implement this and I'm not married to the current proposal, but a new citeAs method has been added to PackageCitations that allows package authors to override the default output of cite and provide their own BibTeX. (In M2internals, we'd discussed maybe a new documentation keyword or option to newPackage, but this seemed simpler maybe?)

[d-torrance]

Files not reviewed (4)

• M2/Macaulay2/editors/prism/package.json: Language not supported
• M2/Macaulay2/m2/help.m2: Language not supported
• M2/Macaulay2/packages/PackageCitations.m2: Language not supported
• M2/Macaulay2/packages/TerraciniLoci.m2: Language not supported

I was intrigued by this Copilot review thing, but I guess it isn't going to be super useful for us yet!

[mahrud]

I just realized that, for packages, this command specifically points to the master branch. Another reason to change the branch name. (the old name will still redirect to the new one)

[MichaelABurr]

I really like the way that citations are displaying on Paul's M2 server. I asked for the citation for my package and got both my package and the JSAG citation. I like seeing both citations on the cite call.

[MichaelABurr]

It might be good to include version numbers in the citation for M2 (or a year). In the case there's a bug in some computation, it is possible to identify if that might affect a paper.

[d-torrance]

After our discussion at M2internals this afternoon, here's what I'm thinking as far as implementing how to set the citation info for a package:

• Add a Citation documentation keyword, replacing citeAs in the current proposal. So package authors could pass the BibTeX code either using the old school:

  document(..., Citation => "....")
  

  or with SimpleDoc:

  doc ///
    ...
    Citation
       ..
  ///
  

• The cite method from PackageCitations would first check if the top doc node for a package contains a Citation entry, and if it does, use that. Otherwise, fall back on the current behavior.
• Include the citation information on every packages's main doc page, either straight from the Citation key or by using cite.
• (Maybe?) If another doc node has a Citation key, then include the citation information on its page. This would accommodate documenting citation information for specific algorithms, etc.

Any thoughts?

[mahrud]

You can cherry-pick the last commit of this branch, which adds a Citation key and section in the documentation. What's left is populating this section with your autogenerated citation guide when it is empty.

[d-torrance]

I played around with this some more (see this branch), and I'm still not a fan of putting the citation info in the documentation if we're planning on using it for cite. A couple reasons:

• We'd need to ensure that the package is loaded with LoadDocumentation set to true to get the citation info.
• It's circular. When generating the documentation, we'd call cite when the citation info isn't provided and we need a default value. But cite would also need check to see if the package documentation provided citation info.

I think I'd prefer to either keep the current proposal (a new citeAs method in PackageCitations) or perhaps add a Citation option to newPackage.

[mahrud]

Can I give it a shot? Since I pushed for it, seems unfair to leave it to you.

[d-torrance]

Please do!

[d-torrance]

Since #3797 dealt with the issues of adding citation information to package docs and overriding the default citation info, all that remains in this PR is updating the authors of Macaulay2 itself.

At the last M2internals meeting, we discussed "Dan, Mike, and M2 authors" v. just "M2 authors". There was a very close vote, and I forget what the result was. @antonleykin, do you remember?

[antonleykin]

At the last M2internals meeting, we discussed "Dan, Mike, and M2 authors" v. just "M2 authors". There was a very close vote, and I forget what the result was. @antonleykin, do you remember?

It was 4 to 5 in slight favor of "just M2 authors".

[mahrud]

It was 4 to 5 in slight favor of "just M2 authors".

Didn't we discuss posting a poll on Zulip?

(To be clear, I voted "just M2 authors")

[d-torrance]

We did, but just Anton and I voted. It was a 1-1 tie lol :)

[mahrud]

We did, but just Anton and I voted. It was a 1-1 tie lol :)

Did you also advertise it?

[d-torrance]

Apparently not! It's under the "Citation" topic in "M2 Internals Discussions". I'll see if I can drum up some more votes by tagging "everyone".

[d-torrance]

Based on the feedback, I've switched this to the "The Macaulay2 Authors" option.

One potential disadvantage is that the "alpha" bibliography style gives us [The] for the citations. We could drop the "The" and then it would give us [Mac], which might be nicer. Any thoughts?

[antonleykin]

Based on the feedback, I've switched this to the "The Macaulay2 Authors" option.

One potential disadvantage is that the "alpha" bibliography style gives us [The] for the citations. We could drop the "The" and then it would give us [Mac], which might be nicer. Any thoughts?

I support dropping "The".

[antonleykin]

I've played with five variations of the citation and discovered that in the alpha bib-style

• the proposed "The Macaulay2 Authors" actually gives [Aut]
• "The {Macaulay2 Authors}" gives [Mac]
• my favorite "{The Authors of} M2" gives [M2]

[antonleykin]

[pzinn]

should we switch to Anton's version?

[d-torrance]

Sounds good -- I went ahead and switched to "{The Authors of} M2". Some BibTeX styles will give us "T. M2" as if M2 is a person whose first name begins with T lol. But I'm not sure if there's a perfect solution.

Also, GitHub's CITATION.cff converter doesn't seem to support curly braces in the author field. But its BibTeX exporting feature already gave us different results (e.g., @software instead of @misc), so I guess that's not a huge deal.