missing documentation from other packages when installing Macaulay2Doc

[mahrud]

Macaulay2Doc installs many documentation nodes from Core, but, strangely, it also gives warnings for missing docs from SumsOfSquares, LLLBases, IntegralClosures, and null. I managed to get rid of the SOS ones by removing Macaulay2Doc from ImportedPackages in SumsOfSquares.m2, but these persist:

--warning: tag has no documentation: Macaulay2Doc :: .Macaulay2/, key ".Macaulay2/", package null
--warning: tag has no documentation: Macaulay2Doc :: integralClosures(Ideal), key (integralClosures,Ideal), package IntegralClosure
--warning: tag has no documentation: Macaulay2Doc :: gramm(Matrix), key (gramm,Matrix), package LLLBases
--warning: tag has no documentation: Macaulay2Doc :: hermite(Matrix), key (hermite,Matrix), package LLLBases
--warning: tag has no documentation: Macaulay2Doc :: kernelLLL(Matrix), key (kernelLLL,Matrix), package LLLBases

Why is this happening? I can't find any reference to any of these nodes in Macaulay2Doc. Is it because LLLBases and IntegralClosure are preloaded? Even so, why would they tag along when Macaulay2Doc is being installed?

[DanGrayson]

The first of those is the one you just fixed for me by adding quotation marks.

[DanGrayson]

... ".Macaulay2/" is the value of the symbol "applicationDirectorySuffix".

[mahrud]

I fixed? When?

[DanGrayson]

Oops, not you, sorry. It was @d-torrance at https://github.com/Macaulay2/M2/pull/1178#discussion_r428387580

[DanGrayson]

See https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2-1.15/share/doc/Macaulay2/Macaulay2Doc/html/___Ideal.html , where it shows this:

I think what's happening is that the "document" function is building the documentation node for "Ideal", and to do so, it endeavors to list all the methods that use an ideal. The IntegralClosure package is preloaded, so it finds that one. It's a bug -- it should figure out that the proper package to house the documentation for it is the IntegralClosure package, and omit the entry altogether. (or not?)

The others are probably similar.

But why aren't there hundreds of these?

[DanGrayson]

To figure out that the proper package for the documentation of "integralClosure(Ideal)" is "IntegralClosure" presents a problem. From

i4 : package integralClosures

o4 = IntegralClosure

o4 : Package

i5 : package Ideal

o5 = Core

o5 : Package

it knows which packages the two items come from, but then it needs to determine which package is "youngest", as determined by the tree of dependencies between packages. Maybe the "endPackage" function should deposit a "time stamp" inside the package when it finishes up, so comparisons can be made. After all, when "endPackage" is running, any packages the current package could depend on have already been loaded. This code is wrong:

     /Applications/Macaulay2-1.15/share/Macaulay2/Core/packages.m2:470:23-470:44: --source code:
     package Sequence := s -> youngest (package\s)

because it depends on the hash code of the package object. Hash codes always increase as time goes on, but objects of type Package may not be created in dependency order, chronologically. The Package object is created by "newPackage", and after that, other packages may be loaded by the code inside the package, or by the newPackage function taking care of the PackageExports and PackageImports options.

If "endPackage" had the line

   pkg#"time stamp" = new MutableHashTable;

in it, then the code above could be changed to

    package Sequence := youngest ( apply ( s, x -> (package x)#"time stamp" ))

[DanGrayson]

Here's a puzzle: referring to the image in https://github.com/Macaulay2/M2/issues/1181#issuecomment-631836325 , why is the documentation for "integralClosure(Ideal)" found, but the documentation for "integralClosures(Ideal)" is not found?

[mahrud]

Here is the full list:

--warning: tag has no documentation: Macaulay2Doc :: .Macaulay2/, key ".Macaulay2/", package null
--warning: tag has no documentation: Macaulay2Doc :: changeMatrixField, key "changeMatrixField", package null
--warning: tag has no documentation: Macaulay2Doc :: changeRingField, key "changeRingField", package null
--warning: tag has no documentation: Macaulay2Doc :: checkLowerBound, key "checkLowerBound", package null
--warning: tag has no documentation: Macaulay2Doc :: checkSolveSOS, key "checkSolveSOS", package null
--warning: tag has no documentation: Macaulay2Doc :: checkSosdecTernary, key "checkSosdecTernary", package null
--warning: tag has no documentation: Macaulay2Doc :: checkSosInIdeal, key "checkSosInIdeal", package null
--warning: tag has no documentation: Macaulay2Doc :: getImageModel, key "getImageModel", package null
--warning: tag has no documentation: Macaulay2Doc :: getMultipliers, key "getMultipliers", package null
--warning: tag has no documentation: Macaulay2Doc :: informAboutTests, key "informAboutTests", package null
--warning: tag has no documentation: Macaulay2Doc :: isExactField, key "isExactField", package null
--warning: tag has no documentation: Macaulay2Doc :: isZero, key "isZero", package null
--warning: tag has no documentation: Macaulay2Doc :: kernelGens, key "kernelGens", package null
--warning: tag has no documentation: Macaulay2Doc :: liftMonomial, key "liftMonomial", package null
--warning: tag has no documentation: Macaulay2Doc :: linsolve, key "linsolve", package null
--warning: tag has no documentation: Macaulay2Doc :: makeMultiples, key "makeMultiples", package null
--warning: tag has no documentation: Macaulay2Doc :: pointsInBox, key "pointsInBox", package null
--warning: tag has no documentation: Macaulay2Doc :: readSdpResult, key "readSdpResult", package null
--warning: tag has no documentation: Macaulay2Doc :: roundSolution, key "roundSolution", package null
--warning: tag has no documentation: Macaulay2Doc :: sdpResult, key "sdpResult", package null
--warning: tag has no documentation: Macaulay2Doc :: testsString, key "testsString", package null
--warning: tag has no documentation: Macaulay2Doc :: truncatedSVD, key "truncatedSVD", package null
--warning: tag has no documentation: Macaulay2Doc :: verbose1, key "verbose1", package null
--warning: tag has no documentation: Macaulay2Doc :: verbose2, key "verbose2", package null
--warning: tag has no documentation: Macaulay2Doc :: zeros, key "zeros", package null
--warning: tag has no documentation: Macaulay2Doc :: integralClosures(Ideal), key (integralClosures,Ideal), package IntegralClosure
--warning: tag has no documentation: Macaulay2Doc :: gramm(Matrix), key (gramm,Matrix), package LLLBases
--warning: tag has no documentation: Macaulay2Doc :: hermite(Matrix), key (hermite,Matrix), package LLLBases
--warning: tag has no documentation: Macaulay2Doc :: kernelLLL(Matrix), key (kernelLLL,Matrix), package LLLBases
--warning: tag has no documentation: Macaulay2Doc :: parameterVector, key "parameterVector", package null
--warning: tag has no documentation: Macaulay2Doc :: roundQQ, key "roundQQ", package null
--warning: tag has no documentation: Macaulay2Doc :: toRing, key "toRing", package null
--warning: tag has no documentation: Macaulay2Doc :: chooseMons, key "chooseMons", package null
--warning: tag has no documentation: Macaulay2Doc :: createSOSModel, key "createSOSModel", package null
--warning: tag has no documentation: Macaulay2Doc :: rawSolveSOS, key "rawSolveSOS", package null
--warning: tag has no documentation: Macaulay2Doc :: HighPrecision, key "HighPrecision", package null
--warning: tag has no documentation: Macaulay2Doc :: LowPrecision, key "LowPrecision", package null
--warning: tag has no documentation: Macaulay2Doc :: MedPrecision, key "MedPrecision", package null
--warning: tag has no documentation: Macaulay2Doc :: MaxRoundTol, key "MaxRoundTol", package null

[DanGrayson]

It would be great to get all this fixed.

[mahrud]

I think all the ones in Macaulay2Doc are resolved in one of my PRs (not sure which one). Here are the other errors of the same kind from other packages:

Graphs :: weaklyConnectedComponents, key "weaklyConnectedComponents", package null
PruneComplex :: LocalRings, key "LocalRings", package null
GradedLieAlgebras :: image(LieDerivation, key "image(LieDerivation", package null
gfanInterface :: Marked Groebner Basis Example, key "Marked Groebner Basis Example", package null
Complexes :: DDD, key "DDD", package null
Complexes :: (Ext, ZZ, Matrix, Matrix), key "(Ext, ZZ, Matrix, Matrix)", package null
Complexes :: (Ext, ZZ, Matrix, Module), key "(Ext, ZZ, Matrix, Module)", package null
Complexes :: (Ext, ZZ, Module, Matrix), key "(Ext, ZZ, Module, Matrix)", package null
Complexes :: (Tor, ZZ, Module, Matrix), key "(Tor, ZZ, Module, Matrix)", package null
Complexes :: (Tor, ZZ, Matrix, Module), key "(Tor, ZZ, Matrix, Module)", package null
Complexes :: (Tor, ZZ, Matrix, Matrix), key "(Tor, ZZ, Matrix, Matrix)", package null
Complexes :: (tensor, ComplexMap, ComplexMap), key "(tensor, ComplexMap, ComplexMap)", package null
Complexes :: symmetry of Tor, key "symmetry of Tor", package null
Complexes :: (prune,Complex), key "(prune,Complex)", package null

Some are typos, and some would be easily fixed by replacing (f, B) into Macaulay2Doc :: f(B), or the respective package.

@DanGrayson Should we make this into an error?

[DanGrayson]

Yes, good idea, but why does it say "package null"? -- that's not informative.

[mahrud]

Actually, I was wrong, there are still these tagging along with Macaulay2Doc:

Macaulay2Doc :: minprimes(Ideal), key (minprimes,Ideal), package MinimalPrimes
Macaulay2Doc :: newIsPrime(Ideal), key (newIsPrime,Ideal), package MinimalPrimes
Macaulay2Doc :: gramm(Matrix), key (gramm,Matrix), package LLLBases
Macaulay2Doc :: hermite(Matrix), key (hermite,Matrix), package LLLBases
Macaulay2Doc :: kernelLLL(Matrix), key (kernelLLL,Matrix), package LLLBases

[mahrud]

Yes, good idea, but why does it say "package null"? -- that's not informative.

If I could figure out why those calls to document are being processed, then I would figure out why currentPackage is null, but I can't figure out either.

On a related note, should "Headline" have a length limit? Pages like this look funny: https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2-1.16/share/doc/Macaulay2/IntegralClosure/html/_idealizer_lp..._cm_sp__Index_sp_eq_gt_sp..._rp.html

[DanGrayson]

Oh, my goodness, yes, let's set a length limit. The headline is intended to be a brief subheading used in menus and lists of links.

[mahrud]

I think adding --no-preload when installing packages is the solution to this issue.

[DanGrayson]

I think adding --no-preload when installing packages is the solution to this issue.

Even if it doesn't solve this issue, it's probably worth doing anyway, since the preloaded packages are there for the convenience of the ultimate user, not for the other packages.