Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add an official way for users to define custom help viewers #4677

Open
fingolfin opened this issue Oct 22, 2021 · 0 comments
Open

Add an official way for users to define custom help viewers #4677

fingolfin opened this issue Oct 22, 2021 · 0 comments
Labels
kind: enhancement Label for issues suggesting enhancements; and for pull requests implementing enhancements topic: library

Comments

@fingolfin
Copy link
Member

Inspired by an email by Bill Allombert to the GAP mailing list:

Right now, we provide a fixed list of help viewers for users. In principle, this list canbe extended by users, but this is undocumented. For example. this is the definition for the "chrome" help viewer:

   # html version with chrome
   HELP_VIEWER_INFO.chrome := rec(
   type := "url",
   show := function(url)
     Exec(Concatenation("chromium-browser \"file://", url,"\" >/dev/null 2>&1 &"));
   end
   );
``

But there really should be a documented way for users to add help viewers. We could just document what is there. But perhaps we can do better?

E.g. assuming that
many (?) browsers can just be started via "COMMANDNAME URL", one could add something like
```gap
BindGlobal("DefineBrowserHelpViewer", function(name, exec)
   HELP_VIEWER_INFO.(name) := rec(
   type := "url",
   show := function(url)
     Exec(Concatenation(exec, " \"file://", url,"\" >/dev/null 2>&1 &"));
   end
   );
end);

A slightly more elaborate version would (optionally) allow adding a placeholder where the URL should be placed; e.g. if we use %, then a user could specify mycommand % --some-arg-that-must-come-after-URLs.

More things that should be improved:

  • we could use Process instead of Exec ; that avoids troubles with shell quoting of arguments
    • however, we then also need a way to background such a process
  • it's weird that the argument is called "url" but apparently doesn't receive an URL, just a file path. That should be changed.
  • perhaps we could filter the list of offered help viewers, by adding a test to each that checks whether it is actually available
  • there are other types of help viewers, ideally we'd also offer nicer interfaces for those? From helpview.gi:
##  "text":   a format as allowed by `Pager' (usually rec(lines:=text,
##            start:=linenr, formatted:=true))
##  
##  "url":    an URL (usually local `file://' URL)
##  
##  "dvi":    a filename or a record rec(file:=filename, page:=pagenr)
##            where pagenr is the first page to show
##  
##  "pdf":    same as for "dvi"

A somewhat related issue is #4272.

@fingolfin fingolfin added kind: enhancement Label for issues suggesting enhancements; and for pull requests implementing enhancements topic: library labels Oct 22, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: enhancement Label for issues suggesting enhancements; and for pull requests implementing enhancements topic: library
Projects
None yet
Development

No branches or pull requests

1 participant