Documentation refresh - Atlanta workshop (rebased) by aalmousa · Pull Request #4345 · Macaulay2/M2

aalmousa · 2026-05-21T19:15:07Z

This draft PR supersedes #4341 without rewriting the shared aalmousa:doc-updates branch.

Changes from the original cleanup pass:

rebased the documentation refresh branch onto current development
preserved the shared original branch by publishing the rebased result on doc-updates-rebased
restored the legacy doc-node form for map(GaloisField,GaloisField) so Style documentation checks no longer fail during package installation

Please use this PR for review instead of #4341 while the shared branch remains in place.

Doc work

Remove some todos and dead methods

Enrich the Macaulay2 debugging docs (ov_debugging.m2) with a detailed, step-by-step example session: load a demo file, show available symbols (listUserSymbols), display function source (code), trigger the debugger and inspect locals (listLocalSymbols), and demonstrate debugger commands (step, break, end) and the errorDepth setting. Also documents non-interactive error handling using try and trap and includes illustrative REPL output to make debugging workflows clearer for users.

Replace Kisun Lee's contact email in NumericalCertification.m2 package metadata from kil004@ucsd.edu to kisunl@clemson.edu to reflect the author's updated contact information.

Add TO entries for the debugging commands 'continue' and 'trap' in M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 so they appear in the module's exported TO list.

Add a trailing space after "deeper." in M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 to ensure correct spacing when the documentation strings are concatenated/printed. This is a minor whitespace-only formatting fix to improve output readability.

mahrud · 2026-05-22T16:17:28Z

+        Example
+            R = ZZ/101[s,t];
+            C = res ideal(t);
+            isVirtual(ideal(s,t), C, Strategy=>"Determinantal")


Since this is a single graded resolution, it seems not in the spirit of Mike Loper's paper. I believe this node doesn't have an example because this option already has an example about 20 lines above, so I suggest just merging this node into the node above.

If it's easier for you, I can do this in a separate PR later or can push directly to your branch if you prefer.

mahrud · 2026-05-22T16:21:09Z

 	PARA{}, "Here are some examples illustrating some uses of this
 	package.",
+	EXAMPLE {
+	     "R = matrix(QQ, {{1,0},{0,1}})",


Making this slightly more interesting:

Suggested change

"R = matrix(QQ, {{1,0},{0,1}})",

"R = matrix(QQ, {{1,0},{-2,1}})",

mahrud · 2026-05-22T16:22:27Z

+--document { Key => {(gin,Ideal)}, }
+--document { Key => {(gin,QuotientRing)}, }


Not a big deal but feel free to just remove these lines.

mahrud · 2026-05-22T16:25:14Z

     SUBSECTION "Combinatorial properties of the Kunz cone",
     UL{
-	TO coneEquations,
+		TO coneEquations,


Not sure what happened with the indentation here (and about 30 lines below) but would be good to avoid this. Again, not a huge deal in a 4000-line PR.

mahrud · 2026-05-22T16:26:49Z

    Headline => "Methods for virtual resolutions on products of projective spaces",
    Authors =>{
-        {Name => "Ayah Almousa",       Email => "aka66@cornell.edu",   HomePage => "http://pi.math.cornell.edu/~aalmousa "},
+        {Name => "Ayah Almousa",       Email => "aalmousa@uky.edu",    HomePage => "http://pi.math.cornell.edu/~aalmousa "},


Did you want to update your website too?

mahrud · 2026-05-22T16:30:00Z

+newPackage ("Tutorials",
+    Version => version#"VERSION",
+    Headline => "tutorials and teaching materials for Macaulay2",
+    HomePage => "https://macaulay2.com/",
+    Authors => { -* see the contributors listed on the main page *- },


It would be good to:

add a date or version to indicate last update

list at least one person as maintainer and reference for who should be contacted for updates.

mahrud · 2026-05-22T16:31:25Z

Was this file meant to be committed? The wiki might be more appropriate for it, or at least in the packages/Macaulay2Doc/ subdirectory rather than here.

mahrud · 2026-05-22T16:32:42Z

+This fork may still be used to stage documentation-refresh work through
+`aalmousa/M2` issues and project items, but upstream contributions land through
+`Macaulay2/M2:development`.


I understand this PR is still a draft, just leaving a comment here so we don't forget to remove this when it's ready.

mahrud · 2026-05-22T16:35:02Z

-Subnodes => {
-"T-spread managing",
-    TO "tLastMon",
+Key => {TSpreadIdeals},


It would be good to fix the indentation as you edit. Perhaps at some point we will have a proper linter to fix this problem.

mahrud · 2026-05-22T16:38:18Z

The helpers isVectScalar and convertScalarVect should not be exported, so this documentation likely will be removed once I update the package.

mahrud · 2026-05-22T16:39:52Z

 quotient(Ideal,  RingElement) := Ideal  => opts -> (I, f) -> quotient(I, ideal f, opts)
 Ideal  : Ideal                := Ideal  =>         (I, J) -> quotient(I, J)
-Ideal  : Number               :=
+Ideal  : Number               := Ideal  => opts -> (I, f) -> quotient(I, ideal f, opts)


This is going to break as Ideal : Number can't accept options. The other change above is also unnecessary, so I suggest reverting changes to this file.

mahrud · 2026-05-22T16:41:52Z

I suspect this will conflict with @joel-dodge's pending PR.

Ty for calling this out. It's fine with me for this monster to be merged before mine and I'll deal with resolving conflicts in my PR.

It would probably be easy to revert the changes to this one file and leave it to you to fix it in your PR, but up to you. If you're okay with waiting, it would be good to mark yours as draft so it doesn't get accidentally merged.

excellent ty i am going to push a PR targeting this branch to do this.

mahrud · 2026-05-22T16:43:41Z

-    TT "SubringLimit => n", " -- an option for ", TO "kernel", " which
-    causes the computation of the kernel of a ring map to stop after ", TT "n", "
-    elements have been discovered."
+  Key => {(kernel,Matrix),


Not sure what happened here but this indentation seems strange. It would be preferable to translate to SimpleDoc form if every line of this node is being edited.

👍 ack this makes sense. i will switch to simple doc format.

mahrud · 2026-05-22T16:45:31Z

+     (wedgeProduct, ZZ, ZZ, Module)
+     wedgeProduct     


FYI: the order of the keys determines which one is the "PrimaryKey", which in turn results in the choice of url, e.g. in this case it'll be .../_wedge__Product_lp__Z__Z_cm__Z__Z_cm__Module_rp.html. I tend to put the main method above to simplify this link.

excellent. will update to switch the order.

mahrud · 2026-05-22T16:46:45Z

I presume the changes here will conflict with pending documentation changes from the debugging team.

mahrud

I left some comments to hopefully help with the final push before this PR is ready. Let me know if you have trouble with getting the builds to succeed, I can take a look.

mahrud · 2026-05-22T16:53:15Z

Oh, also, AI disclosure, if applicable, would be appreciated :)

eisenbud and others added 30 commits September 26, 2023 09:30

Frank's changes in DGAlgebras

a9f26ad

merging

91254fb

new AInfinity

600376e

merge

74a9ff3

Merge branch 'master' into development

ea6e756

Merge branch 'development' of github.com:Macaulay2/M2 into development

c02abe4

Merge branch 'development' of github.com:Macaulay2/M2 into development

96008ee

Merge branch 'development' of github.com:Macaulay2/M2 into development

4d1616d

Add documentation workflow scaffolding

dba0809

Update docs workflow guidance and labels

050e58f

Add documentation contributor guides

fdc74f6

Align documentation guides with upstream docs style

94583e7

Shorten documentation style guide

267d05f

Add remaining docs refresh backlog gaps

2e42f75

Merge remote-tracking branch 'M2/stable' into sync-doc-updates

40c39a8

Add Macaulay2Doc landing page refresh plan

fe4190b

Merge documentation guide and style guide

81c33d0

remove installMinPrimes method that doesnt do anything

62373ca

document default startegy and add links

5624dbe

example that breaks with a likely bug

37289a7

remove empty docs page boilerplate

c2ed715

cleanup tensor docs

c79b081

document strategy for primary decomposition

b072c60

add some examples

5fbb8b6

spell

6d5d287

Merge branch 'development' of github.com:Macaulay2/M2 into development

6e538d2

worked on local rings and primary decomposition

30bbacb

Merge pull request #385 from eisenbud/DocWork

aa1df39

Doc work

Merge pull request #384 from joel-dodge/documentation-refresh

dc988ab

Remove some todos and dead methods

fixes

e68a027

aalmousa and others added 9 commits May 21, 2026 15:11

docs: fix Macaulay2Doc doc tree and map docs

7e3ad40

Merge branch 'doc-updates' of github.com:aalmousa/M2 into doc-updates

6a1aa27

Update author email in package metadata

881887a

Replace Kisun Lee's contact email in NumericalCertification.m2 package metadata from kil004@ucsd.edu to kisunl@clemson.edu to reflect the author's updated contact information.

Add 'continue' and 'trap' entries to ov_debugging

047243a

Add TO entries for the debugging commands 'continue' and 'trap' in M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 so they appear in the module's exported TO list.

Fix spacing in debugger doc string

2ebf720

Add a trailing space after "deeper." in M2/Macaulay2/packages/Macaulay2Doc/ov_debugging.m2 to ensure correct spacing when the documentation strings are concatenated/printed. This is a minor whitespace-only formatting fix to improve output readability.

docs: add beginner Shidoku tutorial

86ca2a3

docs: fix front page tutorial links

aa40fc4

docs: restore GF map node for package install

41b86b7

aalmousa mentioned this pull request May 21, 2026

Documentation refresh - Atlanta workshop #4341

Closed

aalmousa added 3 commits May 21, 2026 15:39

docs: move GF map docs to ConwayPolynomials

80963ec

Merge pull request #400 from joel-dodge/module-tutorial

35c324c

Merge pull request #401 from joel-dodge/subquotient-docs

6cf4531

mahrud reviewed May 22, 2026

View reviewed changes

	"R = matrix(QQ, {{1,0},{0,1}})",
	"R = matrix(QQ, {{1,0},{-2,1}})",

		--document { Key => {(gin,Ideal)}, }
		--document { Key => {(gin,QuotientRing)}, }

Conversation

aalmousa commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joel-dodge May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mahrud left a comment

Choose a reason for hiding this comment

Uh oh!

mahrud commented May 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aalmousa commented May 21, 2026 •

edited

Loading

joel-dodge May 22, 2026 •

edited

Loading