Today an discussion rised up in #debian-devel on the OFTC IRC Network. It started because someone noted the bug report #501318 which is, to summarize it, just a user mistake, because someone obviously read the man page (time(1)) for the /usr/bin/time command, while time is also a shell builtin (which does not accept the same arguments as the time command. Certainly this bug reports appears to be funny at the first sight, but on the other hand, there is a suboptimal situation that leads to this.
- There are some builtin commands that also have binary equivalents (like time, printf, echo). Its quiet easy to tell weither the one or the other is used, by using the which command, but thats not really a realistic workflow, so its better to know this. The difference between these commands is often causing problems, which we have to cope with. For example bashs builtin echo behaves different as /bin/echo and people who use the bash as their default shell tend to use what bash provides, which in turn causes problems if other people who use a different default shell try to work with these scripts. But this is another problem, because…
- … every program, utility and function in Debian has to provide a manpage, as said by our policy: „Each program, utility, and function should have an associated manual page included in the same package.“ I guess that the rationale behind that is that ‚man‘ is a very common tool in the Un*x world, which is wide-spread and which usage is much recommended to find out how specific tools behave. It is always referred to in Documentation, weither it is Debian specific or not, e.g. in books.
The time package, which is of priority Standard and which includes /usr/bin/time, does conform to that policy by providing a manpage for the time command. The various shells don’t do that, because they usually don’t have a man page for each and every command (usually they have a more generic manpage which includes the builtins or in some seldom cases a special manpage for such and similar things (as for zsh, which has zshmisc(1)) and because its not that easy, because the man command cannot (AFAIK) distinguish between the user joey_average calling ‚man time‘ in a bash, while the user schoenfeld calls the command ‚man time‘ in a zsh, or if joey_foobar calls ‚man read‘ in a shell which does not have a builtin time command and uses /usr/bin/time instead.
So whats wrong about this situation? Would you say that users that expect ‚man time‘ (or similar examples) to do the right thing are making wrong assumptions? I disagree. Its what they’ve always been told to do. And if it does not show anything eventually run info, or look at HTML documentation or what else. But they haven’t been prepared for the case where the manpages does show something, something wrong. The good thing is that the manpage for time includes a sentence:
„Users of the bash shell need to use an explicit path in order to run the external time command and not the shell builtin variant.“
The bad thing about it is, that it is at approx. 70-80% of the manpage.
Clint, the maintainer of zsh, mentioned run-help which seems to be a part of the zsh, but not of any other shell, and does more or less the right thing (at least for the builtins) but not for external commands and not even for itself (it opens the code of the function instead of something user-readable like a manpage). I guess „one tool for a specific need“ is a good maxime, but is it really a good maxime for finding documentation?
But how could the situation be bettered? I could think of a wrapper for man, similar to run-help but as a more generic solution. Any ideas for it? Is it the right way at all to better the users experience? Any other ideas? Other opinions?