1

Example:

man -awK "typeset"

This was confirmed by piping to grep:

search=typeset
man -awK -- "$search" | xargs -I {} sh -c "echo '{}'
    man --no-hyphenation --no-justification -- {} | grep -iF -- '$search'"

Result:

/usr/share/man/man1/lcf.1.gz
/usr/share/man/man1/memusagestat.1.gz
/usr/share/man/man1/mtrace.1.gz
/usr/share/man/man1/nm-applet.1.gz
/usr/share/man/man1/nm-connection-editor.1.gz
/usr/share/man/man1/nroff.1.gz
       GROFF_TYPESETTER environment variable nor the -T command-line option
       GROFF_TYPESETTER
              and GROFF_TYPESETTER is unset.
/usr/share/man/man1/tfmtodit.1.gz
       To do a good job of math typesetting, groff requires font metric
/usr/share/man/man1/ptx.1.gz
       -t, --typeset-mode               - not implemented -
/usr/share/man/man1/chrt.1.gz
/usr/share/man/man1/taskset.1.gz
/usr/share/man/man1/chem.1.gz
              for Typesetting Chemical Structure Diagrams [CSTR #122].
       cm.bell-labs.com/netlib/typesetting/chem.gz⟩.  Its README file was used
       Typesetting Chemical Structure Diagrams [CSTR #122] ⟨http://
/usr/share/man/man1/chacl.1.gz

Note that the first five results don't actually contain "typeset" at all. Other search terms behave similarly.

I'm running Ubuntu 20.04.4 LTS (5.15.0-43-generic) with man 2.9.1. This seems to also be an issue on macOS 12.5 with man 1.6g, which has me wondering if I'm doing something wrong?

Jonathan Wheeler
  • 167

2 Answers2

1

man -K searches through everything, including comments in the man page source file.

The string typeset appears as part of the GNU GPL license header present in many GNU and otherwise GNU-GPL-licensed programs.

.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
…

I have no convenient workaround to offer. But man pages don't tend to have a lot of comments, so the problem is limited to a few words.

Gilles 'SO- stop being evil'
  • 829,060
0

On my Ubuntu system, the problem is what Gilles' answer on this same page details. I'm accepting his answer for lending his expertise with this. Thank you, Gilles!

On my macOS system, it's also because the piped man page still contains control characters within the search term in the document, as confirmed by man man | sed -n l.

One solution is to first filter out the control characters using col -b, which removes formatting:

search=typeset
man -awK -- "$search" | xargs -I {} sh -c "echo '{}'
    man --no-hyphenation --no-justification -- {} | \
    col -b | grep -iF --color=always -- '$search'"

Another solution is to use MAN_KEEP_FORMATTING=1 and pipe to ul, which preserves formatting:

search=typeset
man -awK -- "$search" | xargs -I {} sh -c "echo '{}'
    MAN_KEEP_FORMATTING=1 man --no-hyphenation --no-justification -- {} | \
    ul | grep -iF --color=always -- '$search'"

(More detail on the ul solution: Specifying MAN_KEEP_FORMATTING=1—as indicated by man man—doesn't seem necessary for Ubuntu 20.04.4, but it does seem to be necessary for macOS, and it may be for other OSs as well, so just include it to be sure. Yet another solution is detailed by Stéphane Chazelas in my related question, but that solution only works for Ubuntu, not macOS.)

In either case, the only robust* solution seems to be to perform a second pass filtering using grep:

* Assuming your search term doesn't include more than one word that spans more than one line (most likely just a word at the end of a line, and the next word at the beginning of the next line). If so, perhaps filter using pcre2grep -M 'search\s+term instead.

search=typeset
man -awK -- "$search" | \
    xargs -I {} sh -c "man --no-hyphenation --no-justification -- {} | \
    col -b | grep -qiF -- '$search' && printf '%s\n' '{}'"

If you want a more detailed code solution that searches man pages and highlights the results while also retaining man page formatting (colors/etc), please refer to my related question.

Jonathan Wheeler
  • 167