Open orlitzky opened 3 years ago
I'm using
info
in the exact same way that singular itself does.
Not true. Singular runs info
as an interactive program (when no other help facility configured in help.cnf
is available).
Ok, I should have said executing instead of using. You're choosing to focus on irrelevant details in the arguments I've made instead of the arguments themselves.
Also, info
is in no way "more official" than other parsers of the format. The format was invented for Emacs in the 1980s. The standalone info browser is much younger.
What I meant is that calling info
with the name of the node is the closest thing there is to an official way to get to the correct documentation, because that's what singular itself does. The hand-rolled parser makes mistakes (see the original description), and while launching info --node
might feel a little unprincipled compared to a well-written parser, the fact that we're using what singular uses makes up for it.
I don't think a "well-written parser" for info would look much different. The format is designed to be trivial to read by line-by-line text scanning. Sure, some of our regexes are ad hoc and not using the spec - https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Info-Format-Specification.
But like, there's already a well-written parser installed on everyone's machines, and it already transparently decompresses gzip, xz, bzip2, lzip, and lzma files. Why write another one and then ship it with sage to avoid making the first one a dependency of sage?
Our Singular interface currently contains a hand-written parser for Singular's "info" file. In this ticket, we add an optional GNU Info package to parse this file instead.
Relative to running "info", the hand-written parser has several drawbacks:
The extra code is a maintenance burden. We should not be wasting our time (poorly) reimplementing standard tools.
The custom parser is buggy. For example, it is supposed to raise a
KeyError
when documentation for a non-existent function is requested. However, the parser does not keep track of what section it's in, so, for example,get_docstring("Preface")
will happily return the contents of the preface even though "Preface" is not a Singular function.The first time documentation is requested, the entire info file (see above) is loaded into a dictionary. With the Singular info file currently weighing in at around 11MiB, this is wasting a good chunk of memory.
The
singular_console()
itself tries to launch GNU Info to display its interactive help, and cannot use our hand-written parser.The one downside to requiring "info" is that it would add a new runtime dependency to sagelib. To avoid that, we make GNU Info optional, and suggest to the user that he install it when he tries to read Singular's documentation.
GNU Info (or its superset, Texinfo) are widespread, portable, and easy to install on all of the systems we support, so in most cases this should be a "free" improvement.
Depends on #32302
Component: packages: standard
Author: Michael Orlitzky
Branch/Commit: u/mjo/ticket/32242 @
137a918
Issue created by migration from https://trac.sagemath.org/ticket/32242