On Wed, Dec 01, 2010 at 02:07 PM, Dylan Smith said:
> Currently the following doesn't work if we don't find the browser:
> > help funcsave
> > help git
>
> The problem is that we check for the browser and fail before
> checking if we have a html help topic.
>
> For internal commands (i.e. builtins and functions) that we
> have a man page for we should just use man. That way the above
> two examples are consistent, we remove extra dependence on the
> browser, and we could remove the fragile sed statement to find
> out if it is a command. This should all be done before checking
> for the browser.
I agree it makes little sense to error out due to no browser when
the browser is not needed to display the help the user requested.
One problem (which might be easy to solve) is the
__fish_print_help function does not use a pager. This is fine
for short pages but can cause a difficulty for long pages viewed
in the vconsole. I discuss this a bit in my reply to Grissiom's
message below yours. (posted after you posted this message)
Also, we look for the existence of an external (to fish) man page
by merely doing "if type -f $command > /dev/null". Maybe it
would be better to do something like:
if man -w $command ^ /dev/null | grep -q "^/"
which should only hit if an actual man page for $command exists.
> The browser may still be applicable for the help with no
> arguments, because html is easier to navigate than a man page
> (see man bash for an example). However, falling back on man
> pages would be ideal if no browser is installed.
It would also be applicable for the help topics I listed in that
same message, although it would probably be possible to create
man pages for these topics.
> But all of this can be saved for another patch. Keep patches
> simple so they can be easily reviewed through their commit
> diff.
It would be easier for me to make the changes now while the code
is still in my RAM. If we wait, it will have to be retrieved
from tapes in the back room of my head. I'm happy to do it now.
The major problem I see is that we have no "perfect" way of
displaying help. Using a browser is good, as long as we can find
a suitable one, because users are very familiar with the
interface and it provides hyper-linking. Also, browsers provide
visual clues (font size, color, etc) that can make the pages
easier to read). But if we can't find a browser we are dead in
the water.
The problem with text-based solutions (perhaps even
text-browsers) is that users can be unfamiliar with the interface
and the interface can be broken (either with character
corruptions or by scrolling information off screen with no easy
way to get it back).
Right now we have four different display mechanisms:
1) Graphical browser
2) Text browser
3) Fish man pages
4) System man pages
The information in numbers (1) and (2) completely overlap (the
HTML help pages). The information in (3) is a subset of what is
in the HTML help pages and might easily be expanded to cover more
or all of that material. The information in (4) is currently
orthogonal to the information in the HTML help pages. We might
be able to make man pages viewable in HTML via the man2html
program that comes with the standard man package, but let's leave
that discussion until another day.
My suggestion on dealing with all of this is to leave (4) aside
for the moment, and just continue to use it as a fallback if
nothing fish-specific is found. Then I'd like to see the
information in the fish man pages duplicate the information in
the HTML help pages (assuming this would be easy to do). That
way, we would have three different interfaces to the same
information which would make the system as robust as possible.
Another thought I've had, which might by slightly related to this
topic, is that I think it is a mistake to bring users to the
general help index page when they simply type "help". It is too
overwhelming and contains way too much information. I think
"help index" should lead to that page. Just typing "help" should
lead to a simple page, one screen-full at most, that gives the
user a small number of options in an un-alphabetized list, such
as:
Quick start
Help on help
Tutorial
Topics
Commands
Index
FAQ
Each item on that list would take you to another page that you
could get to directly with "help quick", "help help", etc. This
could be shown on that page along with a brief description of
each item.
> While we are on the topic of additional things to fix in help
> afterwards, I am wondering why we bother checking if $XAUTHORITY
> being a "$HOME/.Xauthority" OR "". Isn't it enough to just check if
> $DISPLAY is non-empty, or am I missing a case. Anyway $XAUTHORITY =
> "/var/run/gdm/auth-for-dylan-0k2JS2/database" for me on debian and
> ubuntu, so this condition doesn't work for me at all.
I don't know why that code is there. I had assumed they wanted
to be extra sure X-windows was available. If we think we are
able to display in X-windows and we can't then the help system is
broken (but can be fixed with the -t, --text flag). If it is
broken on Debian and Ubuntu, then I'm all for using only the
existence of $DISPLAY until/if something better comes along.
We could also check the return code from the browser, but eval
seems to be broken in a way that makes this impossible because it
substitutes its own error code for the code of the program it was
trying to run. Does anyone know a way of getting the error code
of the program eval tried to run?
Some of this, such as creating man pages for all the info in the
HTML documentation (unless it is trivial) should probably wait
for another version. But I think it would be pretty easy to add
code to fall back to looking for man pages (both fish and
system-wide) if the browser is not found. I think of it more
as a bug fix. Then if more fish man pages show up, help.fish
will be able to show those too without any changes to the code.
My plan is to add this functionality now, even if it means I will
have to maintain two different versions of fish.help. Also,
please be aware that the help completion file and the help man
page will have to be changed for any of these new versions of
help.fish. I've got candidates but I haven't posted them because
I think we should wait until the UI of help.fish function is
frozen so we don't have to keep re-editing the completion and
man files.
My plan is to make the simple changes suggested so far in
help.fish, probably adding another flag or two in the process
(such as --man to give priority to showing man pages). IMO
lack of robustness or clarity are bugs that need to be fixed.
I'll leave off, for now, from changing the help documentation
itself (except for the docs about help.fish) Then if all goes
well (no more bugs), we can look at the UI and remove or change
options. Then we can make final versions of the man and
completion pages for help.fish and we should be good to go.
Does this sound okay?
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
[email protected]
https://lists.sourceforge.net/lists/listinfo/fish-users
