quick doc

[mfelleisen]

Would it be possible to add tool tips for the scripts so that new users or old ones who forget quickly :-] can see a reminder of what a script does/expects? Some names are obvious, some not. I guess what I am thinking of is a "blue quarter circle for scripts" .. but I will say I am not sure about the design.

[Metaxal]

Which ids do you find not mnemonic enough?

One possibility (apart from making the names clearer) would be to add default comments to the script template, at least maybe for the output?

I wouldn't want a big comment though, as I want the template to look simple at first sight to not discourage new users.

Something like: ;; Returns a replacement string for the selected string selection ("" if no text is selected), or #f to leave the selection as is.

On Fri, May 8, 2020, 13:26 Matthias Felleisen notifications@github.com wrote:

Would it be possible to add tool tips for the scripts so that new users or old ones who forget quickly :-] can see a reminder of what a script does/expects? Some names are obvious, some not. I guess what I am thinking of is a "blue quarter circle for scripts" .. but I will say I am not sure about the design.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/Metaxal/quickscript/issues/23, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAMU2HFLQ6FGAKIB2Z764QLRQP3A7ANCNFSM4M4EIPWQ .

[mfelleisen]

On May 8, 2020, at 10:00 AM, Laurent Orseau notifications@github.com wrote:

Something like: ;; Returns a replacement string for the selected string selection ("" if no text is selected), or #f to leave the selection as is.

This is precisely what I was thinking of.

[Metaxal]

Done. Thanks!

[mfelleisen]

How will this documentation show up in the MENU? That was my original question.

[Metaxal]

If you click on Scripts | New script, the template now has a signature in the comments, right above (define-script ..., so in direct sight of the new/old user. More precisely, when creating a new script, the user sees:

#lang racket/base

(require quickscript)

;; Returns a replacement string for the selected string `selection`
;; ("" if no text is selected), or `#f` to leave the selection as is.
(define-script my-script
  #:label "my-script"
  (λ (selection)
    #f))

[Metaxal]

Does this work for you?

[mfelleisen]

I think we’re cross-communicating.

Your proposal addresses the creation of “tip” documentation.

I asked for both creation and display for existing scripts. For example, I’d expect a “tool tip” or something to appear next to the names of existing scripts.

Does this make more sense?

[Metaxal]

I see. I would love to have tooltips for all of racket, but I'm not going to start doing this just for quickscript---we need a more global solution.

The blue box on define-script already gives some info (tell me if there's something you'd like to change), and complete info can be found on the help desk of course (F1 on define-script).

[I just realized that replacement-string is also not entirely accurate if the #:output-to property is used with message-box or clipboard, but since it's for more 'advanced' use, the more advanced user has probably read the docs.]

[mfelleisen]

We are still not communicating.

1 . tool tips is a metaphor not a literal word. Initially I'd display the comments as plan texts probably.

2. I am also not concerned with define-script. I can read the docs. I am concerned with the people who wish to use, for example, the scripts installed by your "extra" package.

[Metaxal]

Oh, you mean ' what does this script do?' by contrast to 'what do the arguments mean?'; sorry for being slow. Then you can navigate the scripts from the library: A help string for scripts in quickscript-extra is displayed at the bottom of the frame when you click on the script. Is that what you mean?

I had started using help-strings in menus a long time ago, but iirc it wasn't working consistently.

[Metaxal]

Did I understand you right this time?

(Btw, the #:help-string property to define-script is meant to be used just for displaying help strings when hovering over a menu item, but that doesn't work at least on Ubuntu AFAICT.)

[mfelleisen]

( Sorry 3 papers due this week. No time yet to check.)

[Metaxal]

Of course, no worries at all, good luck with your papers!

[mfelleisen]

I updated both packages. I selected Script -> Utils -> Open File Directory. I hoped to see some hint at what it would, its doc string essentially. Nothing. So i clicked to see whether this would show me a doc string. Nope:

Error in script file "/Users/matthias/plt/racket/share/pkgs/quickscript-extra/scripts/open-dir.rkt":
 path-only: contract violation
  expected: (or/c path-string? path-for-some-system?)
  given: #f

[spdegabrielle]

I think this was closed by mistake

[Metaxal]

It's my turn to have a deadline for a few papers. I'll pick this up in a couple of weeks probably.

[Metaxal]

So, first I agree that something is missing to help the user know what each menu item does.

The main problem is that tooltips don't work in menus, and least not on Linux and OS X. (Note that there's a #:help-string property in scripts, which is the same as for menu-item%s, which is supposedly meant just for that.) That's an issue with Racket GUI in general, not with Quickscript.

That's why my next idea was to provide a script-help-string, but it only works at the script level and is only displayed in the library, not in the menu.

Did you have a particular solution in mind?

[mfelleisen]

Here is an idea though it may require the re-organization of your menu.

The sub-menus could simply show explanatory messages, perhaps just the doc string and selecting the menu entry would run it. I forgot whether this is possible (menus are a faded memory) but I have a hunch that it is.

[Metaxal]

That's an interesting idea, albeit very unconventional, but I don't think it's going to work.

• The demand-callback seems to be triggered at the time the submenu is created, and there's no callback for when the menu is clicked. There doesn't seem to be any method to override in menu% to check for events.
• There would be twice as many items in the menus, and the help-string items would take a lot of visual space, leading to a high visual/cognitive load and making navigation cumbersome.

The right way to go would be to make #:help-string actually works in Racket GUI (apparently it currently works on no OS after asking on slack). If tooltips are hard to get working, the help string could be displayed in the message panel at the bottom of DrRacket for example, but this still requires Racket GUI to recognize hovering on a menu-item% (which currently it doesn't).

See https://github.com/racket/gui/issues/16

[Metaxal]

Saddly, from https://github.com/racket/gui/issues/16, it appears that having tooltips in menus is not straightforward.

One possibility is to have a 3rd panel in the library, for the script functions, and display the function-specific help-string there. A script function could also be callable from the library, making navigation/trial smoother. It's a little redundant with the menus though.

How does this sound?

[mfelleisen]

(Yes, I had figured out that menus can't come with tooltips. And I followed gui#16 too.)

When you say 3rd panel, what do you mean? If it's in the srcipt, it's too late for someone who just wants to use it. Let me know whether I misunderstand.

[Metaxal]

I'm thinking of extending the library to obtain more information when navigating the scripts:

When clicking on a script file, it displays in the message field at the bottom the file's help-string. when clicking on a script function, it displays the function's help-label.

Would that mitigate the issue?

[mfelleisen]

Yes, I think that would help.