Macaulay2
`exportFrom` documentation misfeature
Don't try to document functions exported from other packages. It can cause problems.
$ cat Goo.m2
newPackage ( "Goo", Headline => "goo" )
exportFrom_Core {"sin"}
$ M2
Macaulay2, version 1.19.1
with packages: ConwayPolynomials, Elimination, IntegralClosure, InverseSystems, LLLBases, MinimalPrimes, PrimaryDecomposition, ReesAlgebra, Saturation, TangentCone
i1 : installPackage ("Goo", Verbose=>true)
-- installing package Goo in /Users/dan/Library/Application Support/Macaulay2/local/ with layout #1
-- using package sources found in ./
-- storing raw documentation in /Users/dan/Library/Application Support/Macaulay2/local/lib/Macaulay2/Goo/cache/rawdocumentation-dcba-8.db
-- closed the database
-- running tests that are functions
-- making example result files in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Goo/example-output/
-- processing documentation nodes...
-- processing Goo :: sin
-- processing Goo :: Goo
-- assembling table of contents
-- warning: found 1 documentation node(s) not listed as a subnode
-- making info file /Users/dan/Library/Application Support/Macaulay2/local/share/info/Goo.info
-- making html pages in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Goo/html/
-- html page exists: /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Goo/html/index.html
-- html page exists: /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Goo/html/master.html
-- html page exists: /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Goo/html/toc.html
-- making html page for Goo :: sin
-- warning: missing node: Goo cited by sin
-- making html page for Goo :: Goo
-- making "Goo : Index" in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Goo/html/master.html
-- making "Goo : Table of Contents" in /Users/dan/Library/Application Support/Macaulay2/local/share/doc/Macaulay2/Goo/html/toc.html
-- not making documentation in PDF format
-- warning: 1 warning(s) occurred in documentation for package Goo
-- file created: /Users/dan/Library/Application Support/Macaulay2/local/lib/Macaulay2/Goo/.installed
-- installed package Goo in /Users/dan/Library/Application Support/Macaulay2/local/
o1 = Goo
o1 : Package
M2 picks up the example code for the symbol from the documentation of the other package and tries to rerun it. Running the code may fail with an error, because not all the symbols exported by the other package are present.
Somehow we should record the fact that a symbol exported from another package is not part of this package.
Or maybe we should just get rid of exportFrom -- does anyone really need it, when they can export the entire package?
Running the code may fail with an error, because not all the symbols exported by the other package are present.
Can you demonstrate this with an example?
Somehow we should record the fact that a symbol exported from another package is not part of this package.
When exportFrom is used, it means that symbol is now part of this package.
does anyone really need it.
Yes, I do.
Running the code may fail with an error, because not all the symbols exported by the other package are present.
Can you demonstrate this with an example?
I'll forward you the files from Greg Smith.
Somehow we should record the fact that a symbol exported from another package is not part of this package.
When
exportFromis used, it means that symbol is now part of this package.
We should never have a symbol belonging to two packages.
does anyone really need it.
Yes, I do.
For what?
We should never have a symbol belonging to two packages.
It should only belong to the new package. Maybe you want a check that the symbol isn't exported in the first package.
For what?
In LocalRings, Saturation, and PrimaryDecomposition. Why does it matter? It would be a breaking change.
I'm interested in this discussion. But I don't really understand what either of you are saying...
I'm interested in this discussion. But I don't really understand what either of you are saying...
A dictionary is a hash table that converts strings to symbols. When a package exports a symbol, it adds a new entry to the global dictionary of the package, so other code can see it. When a package exports a symbol using exportFrom, it takes a symbol from another package's internal dictionary and adds an entry for it to the global dictionary of the current package. This may result in the symbol occurring in the global dictionaries of two packages. A symbol should be owned by a single package, and thus should occur in the global dictionary of just one package, since that's how ownership is determined. Mahrud's idea is that we can just verify that no other package has exported the symbol, but then we'd have to check every other package, loading them all to make the test. Loading all the packages doesn't seem to be a good idea. Nevertheless, that's what caused Greg Smith's problem -- the other package also exported and documented the symbols.
Maybe what we should do is to add a field to symbol closures, in which the package the symbol has been exported from could be stored. Then we could easily prevent it from happening twice.