From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout.scc.kit.edu (scc-mailout.scc.kit.edu [129.13.185.202]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id pB92D7pb018608 for ; Thu, 8 Dec 2011 21:13:07 -0500 (EST) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-02.scc.kit.edu with esmtp (Exim 4.72 #1) id 1RYpxS-0002OL-DZ; Fri, 09 Dec 2011 03:13:06 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1RYpxS-00060L-Hz for tech@mdocml.bsd.lv; Fri, 09 Dec 2011 03:13:06 +0100 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1RYpxS-0006ZE-Gs for tech@mdocml.bsd.lv; Fri, 09 Dec 2011 03:13:06 +0100 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1RYpxS-00004f-Fz for tech@mdocml.bsd.lv; Fri, 09 Dec 2011 03:13:06 +0100 Date: Fri, 9 Dec 2011 03:13:06 +0100 From: Ingo Schwarze To: tech@mdocml.bsd.lv Subject: Re: Emulating apropos/man.cgi behaviour. Message-ID: <20111209021306.GB26581@iris.usta.de> References: <4EE15592.6020401@bsd.lv> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4EE15592.6020401@bsd.lv> User-Agent: Mutt/1.5.21 (2010-09-15) 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