Re: [Groff] man pages (tangential to Future Redux)

[Ingo Schwarze]

Hi Colin,

Colin Watson wrote on Sat, Mar 01, 2014 at 09:41:02PM +0000:
> On Fri, Feb 28, 2014 at 07:53:34PM +0100, Ingo Schwarze wrote:
>> Eric S. Raymond wrote on Fri, Feb 28, 2014 at 12:15:35PM -0500:

>>> Where I want us to be is that when users call man(1) the normal
>>> behavior is to render through the browser.

>> That is most definitely not going to happen in OpenBSD, and i would
>> be very surprised if any other BSD would follow.  Not all environments
>> are running X, not all environments are fit for running a browser,
>> but you want manuals everywhere.  And i doubt that any people even
>> *want* to see manuals in a browser.

> I think it makes more sense to make sure man:foo and similar URLs do
> sensible things in all the browsers people use.  While there are
> exceptions, if you want to see something in a browser, it's usually
> more natural to start from that browser's URL bar.

Oh yes.  That does certainly make sense to me.  If somebody types
"man:foo" in a browser, it would certainly be nice if the browser
could try to do something sensible with it, for example show a html
rendering of a matching locally-installed manual, maybe even fall
back to the web if no matching local page is found.

But note that an URL scheme is not really ideal to provide even
the central functionality of man(1), which i would say includes:

 - Select the wanted section with -s.

 - Select the wanted machine architecture with -S.
   Sure, one could support syntax like "man:cpu(4/hppa)",
   but there is a limit how far one can reasonably go with
   an URL scheme.

 - Display just the first matching page found (per default),
   but all matching pages if the -a option is given.
   The latter is needed rarely, but is sometimes useful
   when pages with conflicting names are installed in
   different sub-trees.

 - Use an alternate manual path given with -M;
   that's another way to solve the above issue
   which is occasionally useful.

 - Show a list of installed pages with the -w option.

An URL scheme certainly need not support all the man(1) options,
but if you just want to support the five most important ones
given above, the scheme is already likely to get ugly.

If somebody types "man foo" at a shell prompt, however, the man(1)
utility should not fire up a browser, unless the user explicitly
provides the -H option (which is a good choice, by the way, it
doesn't appear to conflict with a similarly-named option somewhere
else doing something else) or unless the user explicitly configured
man(1) to imply -H by default.

Yours,
  Ingo