Strange man file behavior

frankbell · 10-17-2014, 08:27 PM

This is not a complaint nor a question, just an observation. It might be a bug report.

I decided I wanted to learn a little more about suspend from the command line, so I went looking for a man page.

Here's what I turned up.

Code:

$ apropos power
(snip)
pm []                (8)  - powersave - Put your computer into low power mode
(snip)
$ man pm
No manual entry for pm
$ ls /usr/share/man/man8/pm*
/usr/share/man/man8/pm-action.8.gz     /usr/share/man/man8/pm-suspend-hybrid.8.gz
/usr/share/man/man8/pm-hibernate.8.gz  /usr/share/man/man8/pm-suspend.8.gz
/usr/share/man/man8/pm-pmu.8.gz        /usr/share/man/man8/pmap_dump.8.gz
/usr/share/man/man8/pm-powersave.8.gz  /usr/share/man/man8/pmap_set.8.gz
$ man 8 pm 
No entry for pm in section 8 of the manual

The command

Code:

$ man pm-suspend

displays the appropriate man page.

I got the same behavior on both Slackware --Current machines.

If there is a question, it's this: Why does apropos power report a man page that does not exist, while not reporting pages that do exist?

55020 · 10-17-2014, 09:45 PM

man makewhatis

(Once upon a time wasn't there a cron job for that in most Unixen? Did it go out of fashion, like smallpox?)

mancha · 10-18-2014, 01:16 AM

This one was fun...

When I saw your apropos output I thought: fugly! What are those empty brackets and why'd it split up the hyphenated command like that.

Also, why the $%#@ does makewhatis take longer than compiling Firefox?

Turns out both problems (brackets and hyphenation) are due to the same core issue. So, I prepared a patch that fixes Slackware's man-1.6g
package: man-1.6g_awk_like_a_boss.diff (add it to the slackbuild and re-build)

If you don't want to rebuild the package, apply the patch's change directly to your live system (i.e. to /usr/sbin/makewhatis).

After that, rebuild your db with:

Code:

# /usr/sbin/makewhatis

--mancha

======================
Pre-patch:

Code:

$ apropos power | grep "^pm"
pm []                (8)  - powersave - Put your computer into low power mode

$ apropos Abekas
ppmtoyuv []          (1)  - convert a portable pixmap into an Abekas YUV file
yuvtoppm []          (1)  - convert Abekas YUV bytes into a portable pixmap

Post-patch:

Code:

$ apropos power | grep "^pm"
pm-powersave         (8)  - Put your computer into low power mode

$ apropos Abekas
ppmtoyuv             (1)  - convert a portable pixmap into an Abekas YUV file
yuvtoppm             (1)  - convert Abekas YUV bytes into a portable pixmap

frankbell · 10-18-2014, 10:28 PM

Output after running makewhatis as root:

Code:

$ apropos power
(snip)
on_ac_power []       (1)  - test whether the computer is running on line power
pm []                (8)  - powersave - Put your computer into low power mode
pow []               (3)  - power functions
(snip)
$ ls /usr/share/man/man8/pm*
/usr/share/man/man8/pm-action.8.gz     /usr/share/man/man8/pm-suspend-hybrid.8.gz
/usr/share/man/man8/pm-hibernate.8.gz  /usr/share/man/man8/pm-suspend.8.gz
/usr/share/man/man8/pm-pmu.8.gz        /usr/share/man/man8/pmap_dump.8.gz
/usr/share/man/man8/pm-powersave.8.gz  /usr/share/man/man8/pmap_set.8.gz
$ man pm
No manual entry for pm

man pm-suspend displays the man page, but the list of manpages starting with "pm-" still does not display in the output of apropos.

Realize, this isn't a big issue for me. I consider it more a quirk.

Also, I doubt it would be much of an issue for newbies; I know, when I was a newbie, I did not place much reliance on man pages, even after I learned about them. Man pages usually lack something newbies need: examples. It is the rare man page that has examples.

I was a fairly experienced self-taught Linux user when I learned about apropos. Knowing that command led me to use man pages much more often.

I do find it curious that the pages shown by ls /usr/share/man/man8/pm* are not listed in the output of apropos when they do appear in response to ls command. When I run a straight ls /usr/share/man/man8/ in a terminal, there does not appear to be any difference in how they are displayed amongst the other items in the output (in other words, they aren't displayed in different colors or anything like that there).

Thanks to everyone who has looked at this.

MadMaverick9 · 10-18-2014, 11:02 PM

@frankbell

Quote:

Originally Posted by frankbell

Code:

$ apropos power
(snip)
on_ac_power []       (1)  - test whether the computer is running on line power
pm []                (8)  - powersave - Put your computer into low power mode
pow []               (3)  - power functions
(snip)

Did you apply the patch provided by Mancha? Obviously not - since the "[]" still show in your listing.

@Mancha - Thank you for that patch.

MadMaverick9 · 10-18-2014, 11:33 PM

@frankbell

Quote:

Originally Posted by frankbell

man pm-suspend displays the man page, but the list of manpages starting with "pm-" still does not display in the output of apropos.

Code:

bash $ man -k pm-
gpm-root             (1)  - a default handler for gpm, used to draw menus on the root window
pm-action            (8)  - Suspend or Hibernate your computer
pm-is-supported      (1)  - Test whether suspend or hibernate is supported
pm-pmu               (8)  - suspend the computer on machines using a Macintosh-style PMU
pm-powersave         (8)  - Put your computer into low power mode

Code:

bash $ man -k computer
(snip)
on_ac_power          (1)  - test whether the computer is running on line power
pm-action            (8)  - Suspend or Hibernate your computer
pm-pmu               (8)  - suspend the computer on machines using a Macintosh-style PMU
pm-powersave         (8)  - Put your computer into low power mode
tangram              (6)  - watch the computer solve tangram puzzles
xmatrix              (6)  - simulates the computer displays from the movie
(snip)

Of course with Mancha's patch applied and I simply ran "/opt/sbin/makewhatis -w" after that. I didn't want to update the original "/usr/sbin/makewhatis".

MadMaverick9 · 10-18-2014, 11:50 PM

@Mancha:

Interestingly "pm-suspend" does not show up in the "man -k pm-" listing. It's because of:

Code:

# default find arg: no directories, no empty files
findarg0="-type f -size +0"

Code:

/usr/man/man8/pm-suspend.8.gz -> pm-action.8.gz

Could "-o $ -type l -xtype f $" safely be added here or would that cause other problems?

mancha · 10-21-2014, 03:43 AM

Quote:

Originally Posted by MadMaverick9

@Mancha - Thank you for that patch.

You're very welcome.

Quote:

Originally Posted by MadMaverick9

@Mancha: Interestingly "pm-suspend" does not show up in the "man -k pm-" listing...Could "-o $ -type l -xtype f $" safely be added here or would that cause other problems?

Good find. Unfortunately, crawling symlinks with Slackware's makewhatis might cause more heartache than it solves. Unless you overhaul its
awk logic, you'll end up with a much larger whatis db and redundant apropos/whatis output.

For example, if /usr/man/man1/B.1.gz points to /usr/man/man1/A.1.gz and A's manpage has:

Code:

NAME
	A, B - the winner takes it all

you'll end up with the following in your whatis database (sorted differently):

Code:

A	1  - the winner takes it all
B [A]	1  - the winner takes it all
B	1  - the winner takes it all
A [B]	1  - the winner takes it all

Normally you'd only have the first two. Big problem when projects combine many commands into one manpage and symlink (e.g. OpenSSL).

I continued squashing bugs in makewhatis' awk parser until it became clear I was re-arranging deck chairs on the Titanic. Full stop.

At some point Slackware might switch to a more robust alternative but, until then, I've put together build materials for a package I'm
calling man-db-lite (based on man-db). It provides apropos-ng and whatis-ng (that gracefully co-exist with Slackware's man utils) and
makewhatis-ng (small script that produces a whatis db usable by Slackware's apropos, whatis, etc.).

Install the package and create a new Slackware whatis database:

Code:

# makewhatis-ng

Afterwards, Slackware's apropos and whatis work as usual though you'll notice a slightly different format. I personally find the format
cleaner and easier to read.

The issues identified so far seem to all be dealt with well by man-db, e.g.

Code:

$ apropos pm-suspend
pm-suspend (8)       - Suspend or Hibernate your computer
pm-suspend-hybrid (8) - Suspend or Hibernate your computer

You can use the -ng versions of apropos and whatis to take advantage of richer features (see their manpages for more details).

--mancha