Can we refer to package functions from core documentation?

I found that Matlab’s factor documentation (Factorization - MATLAB factor) describes how to handle inputs larger than flintmax (they convert to sym). Since it was not clear in Octave’s factor documentation how to handle inputs larger than flintmax, I updated the doc here to describe uint64 and sym inputs: https://hg.savannah.gnu.org/hgweb/octave/rev/cd33d20283f4

When the user calls factor (sym ('12345')), it’s actually calling @sym/factor not the core factor, but pointing the user to that function felt more useful to me than not mentioning how to solve that case at all, even though it’s not the same function.

I couldn’t find a guideline as to whether it’s OK to refer to external package functions from core documentation, so I’m describing what I did here if anyone wants to weigh in.

Seems ok to me as long as its clear its requires a package.

minor: I suggest capital “S” in “Symbolic package”.

I wonder if it should include pkg installation instructions? (not sure)

@example
@group
pkg install -forge symbolic
pkg load symbolic
factor (sym ('9444733049654361449941'))
...

Thanks @cbm. I’ve capitalized Symbolic here: octave: 658cce403bc7

I would prefer not adding the pkg install and pkg load lines to focus on the factorization itself. When I tried copy-pasting that line, it told me that sym was from an external package and how to load the package, so it should be OK to not mention it.

1 Like

Makes sense! Anyway, if anyone objects in principle, I suppose you could remove the example and just make the reference. That might be better from a maintainence point of view.

This an excellent example and the symbolic package has been longer around with Octave than me :sweat_smile: I am fine with keeping it :+1:

1 Like