TITLE

manpath.PL - Perl implementation of the manpath (1) command

SYNOPSIS

manpath.PL
manpath.PL -help
manpath.PL -version

OPTIONS

-1

If this Boolean option is asserted, output is one path per line. If negated, output is all on one line, separated by the system's path separator. Yes, the name of the option is the digit 1, not a lower-case letter "ell". Think ls (1).

The default is -no-1 if output is to a terminal, or -1 otherwise.

-debug

If this Boolean option is asserted, debug information is sent to STDERR.

The default is -nodebug.

-help

This option displays the documentation for this script. The script then exits.

-version

This option displays the version of this script. The script then exits.

DETAILS

This Perl script attempts to implement the manpath (1) command. Originally it was a study in whether it was practical to look up man (1) pages directly rather than spawn the man (1) command.

By value of $^O, here are the results so far:

darwin

This script gets it nearly right, but I had to hammer the stuff in /Applications/XCode.app/ onto the end of the path, and I have felt constrained to make one of the XCode entries not version-specific.

freebsd

This script picks up /usr/share/openssl/man after /usr/share/man. The native manpath puts it after /usr/local/man, i.e. just before the stuff appended by processing /usr/local/etc/man.d/*.conf.

haiku

This script looks in the documented places per the documentation, but I have not been able to determine the actual contents of the manpath. I have been unable to come up with a manpath (1) command, and man -w is equivalent to man -w man.

The result of ./manpath.PL man differs from that of man -w man in that the output of the latter contains a symbolic link which is translated in the former.

linux

This script duplicates the output of manpath (1).

openbsd

This script looks in the documented places per the documentation, but I have not been able to determine the actual contents of the manpath. I have been unable to come up with a manpath (1) command, and man -w requires an argument.

It turns out that in some cases at least manpath is a symbolic link to man, but under this OS a manpath made that way just hangs.

If you give command-line arguments, this script behaves like man -w, That is, it displays the path to the given man page if any. You can specify more than one page; all pages found will be displayed. The exit status is true if the last-specified man page was found, and false if it was not. The exit status behavior is probably stupid, but it is also the observed behavior, at least under FreeBSD and macOS.

I concluded that a direct lookup of man (1) pages was not practical. The reasons for this are multifold:

Every system seems to do it differently.

This leads to complex code, as the above cruft shows. A production-quality implementation would have an entire class hierarchy devoted to sorting this stuff out, as a less-undesirable way to implement the above extremely ugly prototype code. More than that, I would have to have access to every system that supports the man (1) mechanism.

Documentation on how it is done is inadequate.

At least the following omissions were encountered:

Undocumented paths added to search (darwin)

Paths appear in order contrary to docs (FreeBSD)

Undocumented MANPATH functionality (multiple)

This refers specifically to the fact that a leading or trailing path separator prepends or appends (respectively) the default manpath to the contents of the environment variable, and an embedded double path separator inserts the default manpath at that point. This worked on every system where I tried it, but was undocumented in about half of them.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2019-2024 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.