NixOS: Tell Racket Mode where to look for docs

[scolobb]

Hello and thank you for the awesome work on Racket Mode. The new racket-xp-mode is quite a treat and I am looking forward to using it more.

I do have an issue, however: racket-xp-describe and racket-xp-documentation seem to have trouble finding the documentation. When I run the first one on, for example, map, I get a *Racket Describe* window telling me "(Found no documentation or signature." (the opening parenthesis is never closed). When I run racket-xp-documentation on map, I get pointed to the page file:///#f?q=map. This really looks like Racket Mode is looking for documentation in the wrong place. The #f in the URL I get from racket-xp-documentation looks like Racket Mode is invoking a Racket function for locating the documentation, which silently fails returning #f. But other than these two ideas, I have no clue as to what exactly is happening. I also glanced through the definitions of the two documentation functions in racket-xp.el. They seem to retrieve the paths to the documentation files from "text properties"; they may be broken in my Racket file, but I am not sure as to what could break them.

I am on NixOS, which uses install paths different from other distributions, but I can use packages quite normally (raco pkg works flawlessly, requiring modules from user or system-wide installed packages is never a problem, etc.). I run Racket 7.6 and Emacs 26.3.

Could you help me debug this issue? I am willing to contribute, but I have never programmed in Elisp seriously enough to be comfortable with racket-xp.el directly, nor am I very familiar with Racket package management. I should be fine we a couple pointers though, if you could provide some 🙂

[greghendershott]

Although I don't know what's going on let's try to narrow it down by seeing what happens in various scenarios.

Let's use a simple Racket program:

#lang racket/base
(map add1 (list 1 2 3))

Visit this file in Emacs.

1. Move point to "map". Do you see a tooltip and/or echo area message like "imported from racket/base"? What do you see when you racket-xp-describe?

2. Hit q to go back to the file buffer. Do M-x racket-xp-mode. With point again on "map", what do you see for racket-xp-describe?

3. Hit q to go back to the file buffer. Do C-c C-c, then C-c C-z to switch to the REPL. At the REPL prompt, type map but not yet RET, and with point after the "p", do racket-xp-describe -- what do you see?

4. In the REPL, enter (require racket/help) then (help map). What do you see?

[greghendershott]

It might also be interesting to try that little program in Dr Racket. Move the cursor to "map", right click, then choose the "documentation" item. What happens?

[scolobb]

Thanks a lot for your detailed and kind reply @greghendershott ! Here's a detailed journal of my observations.

Move point to "map". Do you see a tooltip and/or echo area message like "imported from racket/base"?

No, I don't see either either, but I do see exactly that if I do M-x racket-xp-mode.

For the following tests, I restarted Emacs to get a clean session in which I have never turned on racket-xp-mode.

What do you see when you racket-xp-describe?

I get this error message:

helm-M-x-execute-command: describe: broke its own contract
  promised: string?
  produced: #f
  in: the range of
      (->
       (or/c
        (or/c 'namespace path-string?)
        (cons/c path-string? string?)
        (list/c path-string?))
       string?
       string?)
  contract from: (function describe)
  blaming: (function describe)
   (assuming the contract is correct)
  at: /nix/store/bl24ygbhkc6yw1667rjfrayl08lkr25p-emacs-packages-deps/share/emacs/site-lisp/elpa/racket-mode-20200329.1841/racket/commands/describe.rkt:57.18

Hit q to go back to the file buffer. Do M-x racket-xp-mode. With point again on "map", what do you see for racket-xp-describe?

I get a *Racket Describe* window containing exactly the following:

map

(Found no documentation or signature.

Visit Definition   Documentation in Browser          [q]uit

"Visit Definitions" and "Documentation in Browser" are clickable links/buttons, as usual.

Hit q to go back to the file buffer. Do C-c C-c, then C-c C-z to switch to the REPL. At the REPL prompt, type map but not yet RET, and with point after the "p", do racket-xp-describe -- what do you see?

I get the following error message:

helm-M-x-execute-command: describe: contract violation
  expected: (or/c (or/c (quote namespace) path-string?) (cons/c path-string? string?) (list/c path-string?))
  given: '()
  in: the 1st argument of
      (->
       (or/c
        (or/c 'namespace path-string?)
        (cons/c path-string? string?)
        (list/c path-string?))
       string?
       string?)
  contract from: (function describe)
  blaming: /nix/store/bl24ygbhkc6yw1667rjfrayl08lkr25p-emacs-packages-deps/share/emacs/site-lisp/elpa/racket-mode-20200329.1841/racket/commands/describe.rkt
   (assuming the contract is correct)
  at: /nix/store/bl24ygbhkc6yw1667rjfrayl08lkr25p-emacs-packages-deps/share/emacs/site-lisp/elpa/racket-mode-20200329.1841/racket/commands/describe.rkt:57.18

Just in case, I also ran racket-repl-describe at the same point in the REPL, and I get *Racket Describe* window with the following contexts:

map

(Found no documentation, signature, type, or contract.)

Visit Definition   Documentation in Browser          [q]uit

In the REPL, enter (require racket/help) then (help map). What do you see?

my-test.rkt> (require racket/help)
my-test.rkt> (help map)
Loading help index...
; help: no documentation found for: map provided by: "/nix/store/za0k7s00bg3v5sasyqalv12ii7pxjbjn-racket-7.6/collects/racket/base.rkt"
; Context:
;  /nix/store/za0k7s00bg3v5sasyqalv12ii7pxjbjn-racket-7.6/collects/racket/repl.rkt:11:26

It might also be interesting to try that little program in DrRacket. Move the cursor to "map", right click, then choose the "documentation" item. What happens?

I don't have "documentation" in the context menu I get when I right-click on map in DrRacket. I only have "Search in Help Desk for "map"" which opens https://docs.racket-lang.org/search/index.html.

I actually tried looking at how DrRacket would show me the docs before, but since I didn't find any related menu item, I thought it just didn't have that functionality (and felt surprised).

I will try to find out why (help map) does not see the documentation. Also, the error messages I get clearly come from the Racket side of things, which helps me better localise the problem. I didn't actually know that Racket Mode had a Racket part 🙂 (even though now that I know it I don't see how you'd get all that functionality in pure Elisp 😄 ). I'll get back to you whenever I have some more information.

Thanks again for your feedback, it's extremely helpful!

[scolobb]

I spent the rest of my evening stepping through macro expansions and reading some Racket. I went down to xref-binding->definition-tag, but stopped there.

I also started a thread on Racket Users, just in case someone runs Nix and has some more ideas: https://groups.google.com/forum/#!topic/racket-users/VbGPHEMmyJA

I'll get back to playing with this problem tomorrow.

[greghendershott]

Sorry, yes, I'd meant to ask you to try racket-repl-describe in the REPL.

The details differ for how racket-xp-mode and racket-repl-mode get the help string. I thought the experiments might shed some light on this.

The last one where you use racket/help directly, is probably the most direct and simplest of them. The fact that it is confused about the location of the help file, is interesting. The Racket Users group is probably a good place to ask about that. If we can figure out how to get things like racket/help and raco docs working, then probably Racket Mode will start working, too.

[greghendershott]

Potentially also ask at https://github.com/NixOS/nixpkgs ?

The Racket config seems to be https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/interpreters/racket

[scolobb]

Yeah, I thought about asking the Nix community as well: they should probably know better. I'll try to do that today or tomorrow and I'll keep you posted.

UPDATE: Here's the thread I created on NixOS Discourse: https://discourse.nixos.org/t/racket-does-not-find-documentation-after-update/6712

I'll keep digging on my side as well and I'll keep you posted.

[scolobb]

OK, good news! Someone on the Racket Users Google Group explained where the problem with Racket not finding docs came from and gave a workaround/solution. Looks like it's a regression in Racket distribution.

I asked the author of the fix to submit it to Nixpkgs and I hope this regression will be corrected upstream for the next release of Racket.

In what concerns Racket mode, documentation started working again with the fix! Except for item (1) from your original checklist, racket-xp-describe and racket-xp-documentation (and their REPL counterparts) correctly show a new buffer with the doc page, and point the browser to the correct local documentation page, respectively.

I suppose item (1) was not supposed to work anyway, since racket-xp-describe seems to depend on racket-xp-mode being on.

Thanks a lot @greghendershott for your help!

[greghendershott]

Glad to hear it!

Yes, racket-xp-{describe documentation} are implemented by racket-xp-mode; my list of experiments for you to try was misleading (sorry!).