Opened 11 years ago

Last modified 8 years ago

#12421 new enhancement

make it so the prompt at the end of a docstring on the Sage command line is more newbie friendly

Reported by: William Stein Owned by: Minh Van Nguyen
Priority: minor Milestone: sage-6.4
Component: documentation Keywords:
Cc: Karl-Dieter Crisman Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description

If on startup of Sage we set the LESS environment variable as follows (only setting it if it isn't already set), then the prompt at the end of docstring will be "(END - press q to quit) " instead of the cryptic "(END)":

   export LESS="-P?n?f%f .?m(file %i of %m) ..?e(END - press q to quit) ?x- Next\: %x..%t"

Change History (13)

comment:2 Changed 11 years ago by Karl-Dieter Crisman

Cc: Karl-Dieter Crisman added

comment:3 in reply to:  description Changed 11 years ago by Simon King

Replying to was:

... (only setting it if it isn't already set), ...

That may be too simple. For example, my LESS variable is set:

> echo $LESS
-M -I -R

However, that setting does not define the prompt (options starting with -P, if I understand correctly).

So, if the LESS variable is set, then one should still test which of the different -P options (-Ps, -Pm, -PM, etc) is defined, and only change the others.

comment:4 Changed 11 years ago by William Stein

SimonKing? -- I think that if the user has already set LESS, then they are by definition not a "total newbie", so we simply leave LESS alone.

I was talking about this issue in my Sage class yesterday, and realized (by accident) that "h" gives the help for LESS, and it is extremely useful help. The first line explains that "q" quits, and the rest of the help gives lots of other useful information. So instead of changing the prompt to "(END - press q to quit)", we should instead change it to "(END - press h for help)". Despite decade(s) of using less, *I* didn't even know it had an "h" for help until yesterday.

comment:5 in reply to:  4 ; Changed 11 years ago by Simon King

Replying to was:

SimonKing? -- I think that if the user has already set LESS, then they are by definition not a "total newbie", so we simply leave LESS alone.

That doesn't totally convince me. First of all, it wasn't I who defined the LESS variable on my laptop - it seems it was already there when I bought it. So, a total newbie can very well have LESS defined.

And moreover, I don't find it totally obvious that "less" is running when Sage displays the documentation, and thus even a user who knows "less" might wonder what to do. Of course, non-newbies know that one usually has to type q or x to quit any application, and I would expect that people simply try either q or x.

Hence, I still think it Sage defining a meaningful "less" prompt is a good idea - even if LESS is defined, unless it also defines a prompt.

comment:6 in reply to:  5 Changed 11 years ago by William Stein

Replying to SimonKing:

Replying to was:

SimonKing? -- I think that if the user has already set LESS, then they are by definition not a "total newbie", so we simply leave LESS alone.

That doesn't totally convince me. First of all, it wasn't I who defined the LESS variable on my laptop - it seems it was already there when I bought it. So, a total newbie can very well have LESS defined.

Ahh, that is different. I hadn't realized that Linux distros redefine LESS by default. OK, so I guess we should append the new prompt to the end if "-P" isn't already in the LESS? I predict this is going to be a painful can of worms that will never get done though if we complicate it too much, or cause confusion later... I hope I'm wrong.

-- William

comment:7 Changed 11 years ago by John Palmieri

I think only defining LESS if it isn't set makes the most sense. We should also add information about this in the tutorial. I also wonder the Sage banner should be changed or expanded: it currently says

----------------------------------------------------------------------
| Sage Version 5.0.beta1, Release Date: 2012-01-22                   |
| Type notebook() for the GUI, and license() for information.        |
----------------------------------------------------------------------

license() is obviously important, but it's not something that people will need to run very much, and it's not much help for newbies. We could eliminate its mention in the banner, or we could say

----------------------------------------------------------------------
| Sage Version 5.0.beta1, Release Date: 2012-01-22                   |
| Type 'notebook()' for the GUI and 'license()' for licensing.       |
| Type 'tutorial()' for a tutorial and 'help()' for more help.       |
----------------------------------------------------------------------

The message printed by help() could also say something about what to do after you type something like matrix_plot?.

comment:8 in reply to:  7 Changed 11 years ago by William Stein

Replying to jhpalmieri:

I think only defining LESS if it isn't set makes the most sense. We should also add information about this in the tutorial. I also wonder the Sage banner should be changed or expanded: it currently says

----------------------------------------------------------------------
| Sage Version 5.0.beta1, Release Date: 2012-01-22                   |
| Type notebook() for the GUI, and license() for information.        |
----------------------------------------------------------------------

license() is obviously important, but it's not something that people will need to run very much, and it's not much help for newbies.

+1 -- I would be happy to get rid of that.

We could eliminate its mention in the banner, or we could say

----------------------------------------------------------------------
| Sage Version 5.0.beta1, Release Date: 2012-01-22                   |
| Type 'notebook()' for the GUI and 'license()' for licensing.       |
| Type 'tutorial()' for a tutorial and 'help()' for more help.       |
----------------------------------------------------------------------

The message printed by help() could also say something about what to do after you type something like matrix_plot?.

In class yesterday some students strongly suggested that having a big mention of a useful help command would be well worth doing. The first thing help() mentions is the tutorial command, so we would not need to explicitly mention tutorial.

While we're on the topic, another student complaint is that the notebook server doesn't tell the user to type control-c to exit it, which is very confusing and dangerous.

By the way, the tutorial() command has no doctest:

    def tutorial(self):
        """
        The Sage tutorial.  To get started with Sage, start here.
        """
        self._open("tutorial")

I think it could be tested by at least making sure that this isn't going to happen (which is what I got on my laptop, since I was building sage-5.0 on 10.7 and the html docs I guess didn't build, since I had to restart things):

...
OSError: The document 'tutorial' does not exist.  Please build it.

comment:9 Changed 11 years ago by John Palmieri

See #12445 for a revised banner and help message. Regarding a doctest for the tutorial() command, the problem is that the command opens up a file in a web browser, and that's not something we want to happen during doctesting. In the patch at #12445, I've added doctests which are marked "not tested". If the tutorial (or other piece of documentation) is missing, it should be caught by other doctests in the same file, in particular by the doctest for _search_src_or_doc.

comment:10 Changed 9 years ago by Jeroen Demeyer

Milestone: sage-5.11sage-5.12

comment:11 Changed 9 years ago by For batch modifications

Milestone: sage-6.1sage-6.2

comment:12 Changed 9 years ago by For batch modifications

Milestone: sage-6.2sage-6.3

comment:13 Changed 8 years ago by For batch modifications

Milestone: sage-6.3sage-6.4
Note: See TracTickets for help on using tickets.