On Thu, Dec 02, 2010 at 01:04 AM, Grissiom said:
> I think one way to compromise this is write a help wraper that do not
> call browser. Here is the demo:
> > cat help.fish
>
> function help
> eval "$argv" --help
> end
>
> But is can cause errors:
I have an easy fix for this problem. We only use --help as a last
resort. First look for the function in /usr/share/fish/man/$function.1
(I realize we need to use $__fish_datadir). If that file exists then
we display it with the __fish_print_help $function. In most cases this
is exactly what the --help flag does internally.
This brings up another question. On my system, there is no pager
used in __fish_print_help so long pages get scrolled off the screen.
This is more of a problem in the vconsoles where it is hard to
remember or figure out how to scroll back the display.
I've modified my local __fish_prompt_help to use a colorizing pager.
I've also had problems getting these fish man pages to show up
correctly when I do use a pager, such as simply piping the output
through less. The bullets in bulleted lists seem like the most
frequent offenders.
I like the option of keeping the help display inside the terminal
(such as with "help --text"). I also think "help help" and "help
--help" should provide simple text-based help. If we can't get
a good solution to the scrolling problem then I think the output
of "help --help" or "help help" should be less than 24 lines.
I also like the option of being able to open up help in a browser
window. In fact, I my system I've implemented the commands:
wman, winfo, and wperldoc
that mimic the same commands without the leading w's but show the
results in a new browser window. I do the same thing with editing,
sometimes I edit inside the terminal and sometimes in a new window.
Oh yes, the downside of using man files or plain text files for help
is the lack of hyperlinks. This was one of the prime motivations I
had for creating my w* commands.
The problems with text-based help are:
1) It can be frustrating to users if we don't paginate.
2) It can be frustrating if we do paginate if the
output is corrupt or if the user doesn't know how to
navigate or quit.
3) The lack of hyperlinking can also be very frustrating
but not as a bad as the frustrations in (1) and (2)
above where the help system seems broken.
I thought tab-completion might save us on some of this frustration,
being a text-based alternative to hyper-linking, but it has limitations
that keep it from being the knight in shining armour. IMO, the
problem with tab-completion with functions like "help" or "funced" is
that there are way too many choices and the screen gets filled and we
circle back to the scrolling problem. In addition, the completions are
listed alphabetically so there is no way to order them or break them up
into sections.
For example, there is a list of help "topics" in help.fish that
the program groks but I haven't seen this list documented so I
made a "topics man page that says:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
HELP TOPICS
The following help topics are available:
bugs expand-variable
builtin-overview expand-wildcard
changes history
color job-control
completion killring
editor prompt
expand syntax
expand-brace title
expand-command-substitution todo
expand-home variables
expand-process
To seem more information about one of these topics type: help topic
Example
To see documentation about the fish command line editor type:
help editor
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Then I lamented the lack of hyper-links so I thought that we could hash
the help completion into bins called "topics" and "commands". That way
if they user typed:
help topic[s] <tab>
The would get the list of the topics above along with a brief
description of each. But the completion system didn't seem able
to do this. I next tried:
help --topic[s] <tab>
which would have eliminated the description of each topic but it wasn't
even able to do this, erroring out because there were too many options.
Without changing the completion C-code, the only way out I see is to
violate one of the design rules and create several similar functions
such as:
help help-topics help-commands
That way, tab completion becomes more useful because we are not
overwhelming the user with too much information. On the other hand,
if changing the C-code is a viable option, then I would like to be
able to have completion from "help topic[s]" that just gives a list
of topics (like that above) or "help commands[s]" that just gives
a list of commands and function we have built in help for.
We run into a similar problem with funced if we are going to give
it options about using an external editor, and if so which one.
The tab completion gets filled with all possible functions to edit.
In that situation, having a set of similar functions such as:
funced funced-vim funced-emacs and funced-external
make better use of tab-completion because:
funced<tab>
gives you the short list of the funced-* functions while:
funced <tab>
(space tab) gives you a list of functions that can be edited.
In other words, the current completion system is forcing us to always
mix apples and oranges, the short list of ways of how you can edit a
function is mixed up with the long list of functions to edit. Or the
short list of ways of getting help (on topics, on commands, in a
browsers, etc) is mixed up with a long list of all possible topics and
commands and the topics and commands are intermingled.
In general, when giving help, whether with tab-completion or some other
mechanism (such as "help --help") when there are more than a few
options, we want to give the user less than a screenful of information
giving them a few options on how to get more information of a more
specific nature. Anytime the user has to scroll an alphabetical list
of options, those options should be as homogeneous as possible.
Peace, James
------------------------------------------------------------------------------
Increase Visibility of Your 3D Game App & Earn a Chance To Win $500!
Tap into the largest installed PC base & get more eyes on your game by
optimizing for Intel(R) Graphics Technology. Get started today with the
Intel(R) Software Partner Program. Five $500 cash prizes are up for grabs.
http://p.sf.net/sfu/intelisp-dev2dev
_______________________________________________
Fish-users mailing list
Fish-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/fish-users
