On 8/15/06, Philip Ganchev <[EMAIL PROTECTED]> wrote: > 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.
I agree with every one of your objections to using html-based documentation. That said, I'll repeat what I said in my original mail: Having hyperlinks [...] is a very large benefit, bigger than all the associated downsides. That is of course only my opinion, and yours differ. When it comes to consistency, I feel I have to mention that we already have info and man for the commandline (Remember that a lot of GNU programs have a rather stripped man-page and the rest of the information is only in the info database). The desktops use docbook or something else, I don't know exactly. Various packages use either html or .txt files in /usr/share/doc. I didn't create this mess, I just made it even worse. :-/ > > 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. Fixing this properly is definitely a separate project. Fish will not be the combined shell and man-replacement. :-) That said, there might be a solution. If I'm not mistaken the KDE help browser (Konqueror) can display man-pages, info-pages, html and pretty much any other form of documentation. It might be worthwhile to try and use such a command _if_ the user is using KDE. The same for Gnome help, any XFCE help browser, etc. if applicable. Though you would first have to figure out which desktop is used. > > 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). Keep in mind that a lot of documentation is not man-based these days. API references, online books, wikis and a lot of other types of documentation are usually html-based. While commandline programs more often use man-pages for obvious reasons, there is a lot of documentation that you are likely to use together with fish that is html-based. In the end 'set BROWSER links' will give you a pretty man-like user experience, including using '/' to do search, etc., so it's not like it's very hard to get a more man-ly help experience. > > 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? Definitely a good concept. The idea to describe completions in fish comes from exactly this thought. Instead of using 'man ls' to find out how to sort by size, you use 'ls -<TAB>'. Faster, easier to remember and the only thing you need to know is how to use tab to perform completion. You once suggested that when only one completion for a string is known, that one would write it out in an understaded color, which is a sound idea that I hope to get implemented one day. New ways to use completions as a context-sensitive help system are welcome. > > > > > > 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. The bit about BROWSER is mentioned in the help section for the help command. Is it really motivated to display this message every time the user uses the help? I realise this is akin to the error messages for various Posix-isms, but the difference, to me is that the Posix messages suggest a solution that might be hard to simply guess, e.g. use 'set FOO BAR' instead of 'FOO=BAR', whereas using 'help help' to figure out how to use help could be reasonably guessed. Opinions are welcome. > > > > 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. I wouldn't consider htmlview a brower. It's a tiny script to launch the browser of your choice. I feel it would be confusing to say that help is opened in 'htmlview' when the browser window clearly is that of Firefox or Epiphany. But I can see how one would see this differently, it is only a matter of opinion. In the end, I have some hope that freedesktop.org will get a configurable default application spec out soon enough, and this whole question will be moot. When that happens, you can simply use 'open' to show manual pages or html documentation, and the users preferred way of browsing the specified documentation type is used automatically. Problem solved. -- Axel ------------------------------------------------------------------------- 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 Fish-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/fish-users
