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?)

[mahrud]

This seems recursive to me, and I would almost prefer not changing it.
Also, it should probably be written as {the {M}acaulay2 authors}, but you should test that it appears correctly.

[d-torrance]

Yeah, I'm not a huge fan of it either. Specific person, specific person, very general group of people. I just seem to remember maybe that's what we agreed on in M2internals? 🤷

[mahrud]

I don't really like this implementation, specifically because it splits the source of user-defined information that goes into the package. e.g. if I want to change something user-defined that appears in the documentation, I want to just do locate makeDocumentTag [pkgname] to find what I need to change. Why did you not like having a user defined section in the documentation of the package?

[d-torrance]

That was my first attempt, actually. It required a fair amount of coaxing to get SimpleDoc to do what I wanted (keep the indentation, don't strip the newlines, etc.) And in the end, having it defined as one of the documentation keywords felt a bit strange.

In particular, we could theoretically add citation information for any documentation node, and not just the package itself. It also made it so that we wouldn't be able to place the citation information in the main package documentation page where it seemed like it should go -- near the authors, certification info, etc. All the stuff that's provided by newPackage.

[mahrud]

Did you mean to update this before the release?

[d-torrance]

I'll update it again at the release, yes. But the current update is to add BibTeX syntax highlighting.

[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.

[antonleykin]

I have a split opinion on this.
At the moment, I don't think it matter hugely how Macaulay2 is cited as long as the title is the same. Perhaps it is a good idea to mention somewhere that people are free to alter the rest to their liking.

In my last three articles I used the following (moderately altered) version:

@MISC{M2,
	author = {Grayson, Daniel R and Stillman, Michael E and {other Macaulay2 authors}},
	title = {{Macaulay2, a software system for research in algebraic geometry}},
	howpublished = {Available at \url{www.macaulay2.com}}
}

It mentions Macaulay2 three times for good measure 😄