Re: Emulating apropos/man.cgi behaviour.

[Ingo Schwarze <schwarze@usta.de>]

Hi Kristaps,

Kristaps Dzonsons wrote on Fri, Dec 09, 2011 at 01:25:54AM +0100:

> I'm trying to duplicate the behaviour of OpenBSD's apropos(1) and
> man.cgi.  I find they're somewhat inconsistent, but enclosed is a
> patch that does so.  My notes follow.
> 
> First, OpenBSD's apropos(1) accepts `-S' in that it prints manuals
> that have no architecture alongside those that have specified the
> same one. Try apropos -S amd64 intro for an example.  I'd think an
> architecture would select ONLY those manuals with that architecture,
> but...

Well, that behaviour makes some sense: -S amd64 gets you all
manuals valid for amd64.

> Second, man.cgi outright throws away architecture and section when
> running apropos.  Er...?

That sounds like a bug, i don't think we need to copy that.
There *are* bugs in man.cgi, you know.  ;-)

> In this patch, I first implement (1) in apropos_db.c,

That looks good.

> adding a note to whatis.1 and apropos.1.

I'm not sure that's needed.  When you search for a specific arch,
it is not that surprising that you get everything valid there,
not just the few things *only* valid there.  And even if you
don't expect that, it's obvious as soon as you run it.

What's worse, your wording "only applies to manuals specifying
an architecture" is dangerously close to "only returns manuals
specifying an architecture", so it might add to the confusion.

> Then for (2) in cgi.c, I detect "legacy"
> mode (if the "apropos" query key is passed in) and do the same,
> otherwise I pass the architecture and section to apropos as might be
> expected.  I print out a "legacy mode" message if applicable.  I'm
> afraid the patch has some churn in cgi.c (sorry).
> 
> Does this approach sound reasonable?

I'm confused.
I guess before understanding that, i will have to first study
man.cgi in general.

> Note that my man.cgi is a bit different from OpenBSD's.  Mine has a
> "whatis" or "apropos" search type, which return the same results of
> the command-line of the same.  If, however, there's only one result,
> that result is displayed.  My reasoning was behind a personal
> distaste for how man(1) unintuitively handles multiple manuals
> matching the same query (e.g., man intro): it seems intuitive to
> display all matches and let the user decide, instead of picking the
> first one and hoping it matches PATH order.

Sounds reasonable on first sight, in particular on the web.
A clickable list on the web is easy to use.

Regarding apropos(1), i think staying rather close to established
behaviour is relevant.  But for man.cgi, what matters is not breaking
links; if we can present information in a better way, that's not
necessarily a problem, i don't thing people will request slavishly
following the old way - in particular since the old script has so
many deficiencies.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv