On Fri, Dec 03, 2010 at 07:22 PM, Grissiom said:
> Besides what Dylan have said, I think we should do "man
> $__fish_datadir/man/$fish_help_item.1" instead of __fish_print_help
> here, since we are in man mode.
Yes, of course. Thank you.
> Hmm, what is the difference between --nb and --man? We have to output
> something eventually...
The --man flag gives priority to man mode (over html) for cases
where we have both a fish man page and an html page. Right now,
these are only the commands. If you request one of the following
topics:
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
then even with the --man flag, we will still launch a browser to show
the help. The point of the -nb flag was to make it easy to test the
browser-not-found error messages. So with the -nb flag, we would
instead give the "Could not find a web browser" error message. Try
"help --man" vs. "help -nb". IMO, ideally, someday, we would have
a man page for every help topic.
I don't believe this list of valid help topics is available
anywhere to the user. I've created a man page for it and ideally
we would also make an HTML page. It would also be great if this
list was available via tab completion, but as I've mentioned
before, I don't think our current completion system is able to do
that without creating a new command such as help-topics.
You can get a longer list by doing (no intended line wrap):
sed -n < $__fish_help_dir/index.html -e "s/.*<a class=\"anchor\"
name=\"\([^\"]*\)\">.*/\1/p"
And you can get a shorter list by doing:
sed -n < $__fish_help_dir/index.html -e "s/.*<h2><a class=\"anchor\"
name=\"\([^\"]*\)\">.*/\1/p"
but AFAIK, the only place the list above appears is in a variable
in the help.fish function. IMO, giving users access to this list
would be make the help system more useful and would fit in with
the law of discovery. My solution to this problem would go one
step further. I believe "help" with no args should give a shorter,
top-level list of help topics:
Quick start
Help on help
Tutorial
Topics
Commands
Index
FAQ
both in man format and html.
o "Quick start" would be a page about using a shell, like the
current "Introduction" but aimed more at beginners so it
would not delve into topics such as redirection.
o "Help on help" would be a more detailed explanation of the
help command, choosing a $BROWSER, etc.
o "Tutorial" would be a set of things for a user to try to get
familiar with the shell. This could be long and delve into
redirection, etc.
o "Topics" is the list of topics above, perhaps with a brief
description of each.
o "Commands" would take you to a list of the fish commands we
have help on, an index to commands.html. For now, maybe it
could go to the commands section of the current index.
o "Index" would go to where "help" with no args goes now.
o "FAQ" would, of course, go to the FAQ page.
IMO, when a beginning user types "help<return>", giving them a
short list of choices that fits on one page is much more friendly
then taking them to the TOC of the current index.html which IMO
is way too much information. Giving users access to a short list
of about 20 help topics (via "help topics") would go a long way
to making the entire fish system follow the law of discovery.
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
