missing man pages

Polytropon freebsd at edvax.de
Tue Apr 29 00:59:06 UTC 2014

On Mon, 28 Apr 2014 20:18:07 -0400, illoai at gmail.com wrote:
> It's up to a maddening combination of third-party developers
> (who may be prejudiced against useful tools like man(1)) and
> port maintainers (who may be confused, uncaring, jaded, or
> wrong) to provide the man pages for third-party applications.

Note that there are exceptions. Even software which isn't
actually open source can provide useful manpages. Here are
some of my favourite examples:

	% man mplayer
	% man opera
	% man audacity
	% man gimp
	% man X

And now compare:

	% man firefox
	% man thunderbird
	% man k9copy

Sure, you'll say "You can't compare those!" and you're probably
right. But _even_ GUI-only applications _can_ provide a manpage.
And in worst case, you'll be happy about local documentation,
especially when you're working in "worst settings" (no Internet
connection possible, no "private" Internet connection allowed,
just "work with what you've got").

Relying on users to write documentation, or at least have them
search for it in arbitrary places (somewhere scattered across
the local file system, a command line option, the web, a wiki,
user pages, web forums or blogs) is, in _my_ opinion, not a
"good" solution.

> It used to be that debian did man pages for a lot of things that
> (misguided) linux kids didn't want to document well (info(1) is
> such a lame attempt, guys.  Stop already), but you'd have to
> count on the maintainer to pull those in.

This is Linux-specific, as Linux distribution designers and
maintainers compose the "default installation" out of packages
(as there is no "base system" per se), and sometimes documentation
is kept in separate packages which are not included in the
default install. This is problematic when you rely on them,
especially when you already _know_ that the Linux tool you're
going to use does things a little bit differently and you need
to look up that specific option you need...

> For stuff from the ports tree, I'd suggest a polite question to
> the maintainer before you fire off a PR: there may be good
> reasons they don't come with decent documentation.

This is a good suggestion. Maybe for a specific version, the
documentation is still "in the flow" of upgrading to meet
conditions that have changed.

> Fr'instance, the obnoxious devel/dbus installs no man pages,
> so you have to guess at its true purpose.  Maybe it makes hot-
> dogs, maybe it just e-mails the NSA when you utter profanities,
> maybe it does something else.  Good luck!

There is something in /usr/local/share/doc/dbus-glib, but I'm
not sure if it walks the dog, disassembles the car, or just
flies out of the window. :-)

Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...

More information about the freebsd-questions mailing list