Adds a browseable manual from the REPL

jpellegrini commented 10 months ago

Hi @egallesio !

This is probably not good, since it includes some fluff in the boot file, and I have written it without thinking about portability or error handling at all... But it's an idea for the future (post-2.0). :) Maybe we can enhance this.

Some Scheme implementations (Gauche and Gambit) will call an external pager for the user to read the manual. This patch brings something similar to STklos.

Added parameters:

(default-browser) is a string with the full path of the browser to be used.
(available-browsers) is a list of possible browsers (strings with executable names), that will be searched in the system PATH at boot time.

(manual-path) is the full path to the STklos manual. At boot time, this is searched in

(string-append
 (%library-prefix)
 "/share/doc/stklos/"
 (short-version)
 "/html/stklos-ref.html")

Two procedures are added in bonus.stk:

(open-in-browser url) Opens the URL given by the string url in the default browser, which is determined by the string contained in the parameter default-browser.
(manual) Opens the STklos manual in a browser.

egallesio commented 9 months ago

Hi @jpellegrini,

I'm sorry to be so slow to integrate your PRs. To be able to browse the manual is really a goof d idea. I'm working (too slowly) on it. I have added custom IDs to the documentation, so that you can possibly add a parameter/ Hence, ,m cadr permits to open the manual on the cadr function.

jpellegrini commented 9 months ago

I'm sorry to be so slow to integrate your PRs.

No problem! :) I'm also swamped currently...

To be able to browse the manual is really a goof d idea. I'm working (too slowly) on it. I have added custom IDs to the documentation, so that you can possibly add a parameter/ Hence, ,m cadr permits to open the manual on the cadr function.

Ah, that will be great! I'll wait for it to be included, and adjust this PR.

egallesio commented 8 months ago

Hi @jpellegrini ,

Some news: I'm not dead :smile:

Otherwise, I'm working on several enhancements of STklos, mostly your PRs and Issues as:

this one is now complete: you can ask for the manual of a given function, which will be searched in the local documentation (or the STklos website if the documentation is not installed).
PR #600 (which is resolved by another way (setting a non named lambda to a variable sets now its procedure name)
PR #559 for which I have defined a new primitive to customize REPL command (so that it is possible to have your own commands in your stklosrc file.
Issue 291 (resolved)
perhaps the Issue 477 (depends on the way I resolve THE BUG, see below)

All those points are simple but during the implementation of new REPL commands, I wanted to have special variables such as $, $$ and $$$ (or perhaps @ @@ and @@@) which are similar to the *, **, *** of CL's REPL). The idea is that those variables are defined in the REPL module and don't interact with eventual user variables with the same name. This exhibits THE BUG: when we import a variable, it is a read-only alias on the original variable. When we redefine it, we only unset the RO flag, but the aliasing still persists. So we have

stklos> (define-module M (export $ show) (define $ 100) (define (show) $))
;; M
stklos> (import M)
stklos> $
100
stklos> (define $ 'my$)
;; $
stklos> (show)
my$                             ; <= We broke the variable in the module M. So,
                                ; in M, setting a new value to $ change the
                                ; value in the REPL :-<

To resolve this problem, I have completely changed how global variables are implemented (they are no more in the module hash table, but in a global array). Things are complicated because, with checked variables optimizations in the VM, variables cannot move, once they have been used. Believe me, it was really epic to bootstrap the system!!!

I have a mostly satisfying system. Mostly, because I have not yet reinstalled the optimizations on checked globals (which must be changed since variables are now in an array, and that, hence, it is no more necessary to create the array checked_globals). Normally it should be simple (not so simple, since we must be thread-safe). What is sure, is that the system is really slow, without these optimizations.

However, the actual (slow) version doesn't pass the tests (and even segfaults when testing SRFI-216). Most of the problems are in tests of SRFI-232. It took me countless hours to see that this is due to the implementation of SRFI-27 (while its tests are OK!!!). I suspected a problem with threads, but the problem exists also when configured with --disabled-threads. For now, I have restored the old implementation I had in release 1.60 of random-integer and all the tests pass (except the one on SRFI-27 obviously).

I will finish the implementation of new variables, and I'll try to fix completely the problem with your implementation of SRFI-27. If I'm unable to fix the issue with SRFI-27, I'll temporarily commit with old implementation of random numbers. In this case, please, can you try to see if you understand what's going on? I'm on the problem for too long time and a new vision would probably help.

I hope to have something stable in a few days.

jpellegrini commented 8 months ago

Hi @egallesio !

It looks like there will be a lot of great enhancements! This is awesome! I have some work and personal problems currently, so I couldn't do much in STklos, but sure, I can take a look at SRFI 27 if needed. I'll wait for your commit.

egallesio commented 8 months ago

I have some work and personal problems currently, so I couldn't do much in STklos, but sure, I can take a look at SRFI 27 if needed. I'll wait for your commit.

I hope that you can resolve these problems swiftly.

Anyway, I'll try to do my best to resolve the issue by myself. In any case, we can live with old implementation for a while.

jpellegrini commented 8 months ago

SRFI-27

Maybe it's an extra thing I added to the SRFI (the shared array counter, which uses a mutex and libgc's finalizer). It's unnecessary complexity, and I think it can be removed. I'll do that.

jpellegrini commented 8 months ago

Maybe it's an extra thing I added to the SRFI (the shared array counter, which uses a mutex and libgc's finalizer). It's unnecessary complexity, and I think it can be removed. I'll do that.

Sorry, I wasn' thinking straight. The array counter is in SRFI-25, not 27. Anyway, I'll take a look in SRFI-27 when you commit the new code.

egallesio commented 8 months ago

Hello @jpellegrini,

That's a weird error. I had tried to put back your code with the new implementation, but it doesn't work. The problem seems to be that (srfi 27) cannot be re-imported (which is implied when doing a make test). It seems that we are lost between <...-rt> and <...> classes. I don't understand why, and I have not completely understood your code. If you have some time to take a look at it. Don't worry, we can live with current (slower) version.

For now, I'll try to understand why GitHub actions don't recurse anymore when making utils directory :cry: I will try to commit more often, to avoid these issues. I hope to be able to fix it quickly, otherwise I will not be able to fix it before a week

jpellegrini commented 8 months ago

Okay, it looks like we have a really nice help system now!

stklos> (default-browser)
"xdg-open"
stklos> (default-browser "lynx")
stklos> (open-in-browser "stklos.net")             ;; Opens stklos.net
0
stklos> ,m display                           ;; opens manual entry for display
stklos> ,m class-of                          ;; opens manual entry for class-of

Seems perfect to me! I think this PR is not needed anymore. :)

egallesio / STklos

Adds a browseable manual from the REPL #598