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 /usr/local/share/fish/functions/help.fish). 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 http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642 _______________________________________________ Fish-users mailing list Fishfirstname.lastname@example.org https://lists.sourceforge.net/lists/listinfo/fish-users