OpenBSD Journal

Faster and more capable whatis(1)/apropos(1)

Contributed by tbert on from the search me, man! dept.

Not one to get lost in the OpenSSL/m2k14 shuffle, Ingo Schwarze (schwarze@) has, after much work and improvement, updated the man page search functionality: 

Date: Fri, 18 Apr 2014 04:00:48 -0600 (MDT)
From: Ingo Schwarze 
To: source-changes@cvs.openbsd.org
Subject: CVS: cvs.openbsd.org: src

CVSROOT:        /cvs
Module name:    src
Changes by:     schwarze@cvs.openbsd.org        2014/04/18 04:00:48

Modified files:
        etc            : weekly
        libexec        : Makefile
        usr.bin        : Makefile
        usr.bin/mandoc : Makefile
        usr.sbin/pkg_add/OpenBSD: Add.pm Delete.pm Paths.pm PkgCreate.pm
        share/man      : Makefile
        share/man/man8 : daily.8

Log message:
Switch to the new makewhatis(8)/apropos(1)/whatis(1) combo.
"commit the switch now" espie@  "go for it" deraadt@

See the apropos(1) manual for a description of what's new.
On machines where you want the full functionality,
run "sudo makewhatis" and put "MAKEWHATISARGS=' '" into weekly.local(8).
Otherwise, when upgrading via source, run "sudo makewhatis -Q".

Users now have a powerful tool with which to more easily find information in the already-superb documentation. To quote the apropos(1) man page:

The apropos utility queries manual page databases generated by makewhatis(8), evaluating [the search] expression for each file in each database...Queries evaluate over a subset of mdoc(7) macros indexed by makewhatis(8).

The EXAMPLES section displays some of the wealth of possibilities: 

     Search for ".cf" as a substring of manual names and descriptions:

           $ apropos .cf

     Include matches for ".cnf" and ".conf" as well:

           $ apropos .cf .cnf .conf

     Search in names and descriptions using a regular expression:

           $ apropos '~set.?[ug]id'

     Search for manuals in the library section mentioning both the "optind"
     and the "optarg" variables:

           $ apropos -s 3 Va=optind -a Va=optarg

     Do exactly the same as calling whatis(1) with the argument "ssh":

           $ apropos -- -i 'Nm~[[:<:]]ssh[[:>:]]'

     The following two invocations are equivalent:

           $ apropos -S arch -s section expression

           $ apropos \( expression \) -a arch~^(arch|any)$ -a sec~^section$

For those of you attending BSDCan, Ingo will be presenting a talk that goes into much more depth about the improvements he's been making.

(Comments are closed)

Comments

  1. By sneaker (204.11.200.61) on

    Thanks!

  2. By thomasw_ (108.172.20.101) thomas.wildeman@gmail.com on

    this sounds useful, effective and eloquent to use. look forward to giving it a spin; thanks heaps, Ingo.

  3. By jdv (216.16.224.222) jdv@clevermonkey.org on http://clvrmnky.org/

    So, I can't quite tell from the documentation, but it looks like mandoc(1) is a replacement and improvement for man(1).

    Or is mandoc(1) expected to be used to generate various document renditions from source (including legacy man)? I'm unclear on the relationship between classic man and mandoc, and the roadmap ahead.

    Except running the actual mandoc command seems to imply that you need to know the section you are interested in. e.g., to get traditional:

    $ mandoc mandoc.1

    So, you can "format and display" documents, but I gather mandoc is more about the former than the latter.

    Furthermore, if I want these benefits, I should retrain my muscle memory to use "apropos ..." instead of "man -k ..." Is that right?

    Hopefully the slides from the BSDCan presentation will be published next month, as I could probably use the homework.

    Comments

    1. By Anonymous Coward (84.163.38.152) on

      mandoc(1) is not a replacement for man(1), but for "groff -mandoc"; see man.conf(5) to learn how man(1) uses it. There isn't much of a roadmap regarding plain mandoc(1), i mostly completed that work three years ago. Oh well, i still have some ideas, yeah...

      There is no need to change any muscle memory. man(1) invokes mandoc(1) and apropos(1) as needed by default. For example, "man -k An=Gray -a Xr=pci" works just fine and does the same as "apropos An=Gray -a Xr=pci".

      Your questions are a bit basic to find answers in my slides; i didn't even explain much of what you are asking in my first talk three years ago: http://www.bsdcan.org/2011/schedule/events/230.en.html
      http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html

      Comments

      1. By jdv (216.16.224.222) jdv@clevermonkey.org on http://clvrmnky.org/

        > mandoc(1) is not a replacement for man(1), but for "groff -mandoc"; see man.conf(5) to learn how man(1) uses it. There isn't much of a roadmap regarding plain mandoc(1), i mostly completed that work three years ago. Oh well, i still have some ideas, yeah...
        >
        > There is no need to change any muscle memory. man(1) invokes mandoc(1) and apropos(1) as needed by default. For example, "man -k An=Gray -a Xr=pci" works just fine and does the same as "apropos An=Gray -a Xr=pci".
        >
        > Your questions are a bit basic to find answers in my slides; i didn't even explain much of what you are asking in my first talk three years ago: http://www.bsdcan.org/2011/schedule/events/230.en.html
        > http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html

        Actually, this was the hint I needed. Seeing how we got to here from there is the best way I could grok this.

        I'm not a manual producer, but a manual consumer. So now I know better where this fits in that relationship. This was my guess, but I am ignorant of most aspects of the manual producer end (I fuzzily know that tbl, groff, etc. are invoked at various times to read various formats of files to mumble mumble mumble).

        For now, I'm good. But I see that I will have to pay closer attention if I ever get around to the little port I want to do.

Latest Articles

Credits

Copyright © - Daniel Hartmeier. All rights reserved. Articles and comments are copyright their respective authors, submission implies license to publish on this web site. Contents of the archive prior to as well as images and HTML templates were copied from the fabulous original deadly.org with Jose's and Jim's kind permission. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]