On 8/14/06, Axel Liljencrantz <[EMAIL PROTECTED]> wrote:
> On 8/14/06, Martin Baehr <[EMAIL PROTECTED]> wrote:
> > On Mon, Aug 14, 2006 at 04:43:39PM +0200, Axel Liljencrantz wrote:
> > > The documentation is written in Doxygen
> > > [ ... ] there actually is an option to create
> > > man-pages from the documentation.
Hyperlinked help is great.  But I think it is more important that the
help system be the same for builtins and external commands.  Otherwise
new users get confused and returning users's habituation is broken.

So hyperlinking help should either be considered a separate project
from the shell itself, or done for the whole system (like Fish
completions are).  This can be an option when installing Fish.  Some
distributions, like Gobolinux, hyperlink the whole help system, as
well as wrapping all commands to provide informative help messages.

If there are no hyperlinks, the help can be navigated by string
search.  This may be quite usable, if the shell help is just one
document, like it is now.  Yes, links are better, but this is weighed
against the risk of not having a browser installed, the risk of the
user not seeing the browser window, the work the user must do to
navigate to the help window, the cognitive load of learning two
interfaces for help, and the frustration that his habituation for
navigating man pages does not work with help pages (and vice versa).

You could even be show the help inside the completion pager.  The
system would be more discoverable, require less typing, and have fewer
modes.  But the long man pages may get in the way.  Hey - how can
there be innovation without outlandish ideas?

> > > help is being displayed in x-www-browser
> > > is not helpful, IMO. I added this to help.fish:
> > >                set browser_name (_ 'your default browser')
> >
> > but "your default browser" by itself is not helpful either because it
> > does not tell me where this is defined. i never use such default
> > variables, but always just call the programs i want to run directly. so
> > when you tell me you are using my default browser, you will leave me
> > puzzled because i wonder where you got that from because i never defined
> > a default browser.
> It's not helpful, but at least it's not (very) confusing. Who's ever
> heard of the htmlview command? Some users may have noticed that there
> is a configuration option to choose the default browser in the
> preferences menu, however.

I think that if the help must be in HTML by default, the user should be told:
1. in which browser it is displayed, and
2. how to make help use another browser

For example,

Help is displayed in www-x-browser.  You can change the default help
browser by setting the variable "BROWSER" (example: "set BROWSER w3m")
or re-defining the function "help" (see

It's verbose, but it's informative.  I guess the first sentence is
only necessary for X browsers.

> It would be nicer if we know what browser htmlview and friends launch,
> but we don't. These applications are ugly hacks, future Unix versions
> should extend the .desktop files and the mimetype database to handle
> user configurable default application lookup. Once that happens, I'll
> be sure to update fish so that the users preferred browser will be
> explicitly named, but I'm not sure it's worth the effort right now to
> try and figure out where x-www-browser and htmlview stores their data.

Fish need not tell the user which browser "htmlview" launches.  For a
start, "htmlview" can be considered a browser.  As the user learns
more about Fish and Unix, he can reconfigure htmlview.  The most
important thing is for the user to get the initial help to get off the
ground; that he is not powerless.  So in case he is confused, like
Martin was, tell him where the help is showing, and just in case he
still does not see it, try to help him change the browser in order to
see it.

Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
Fish-users mailing list

Reply via email to