Date: Tue, 29 Apr 2014 02:57:44 +0200 From: Polytropon <freebsd@edvax.de> To: "illoai@gmail.com" <illoai@gmail.com> Cc: "freebsd-questions@freebsd.org" <freebsd-questions@freebsd.org>, "Ronald F. Guilmette" <rfg@tristatelogic.com> Subject: Re: missing man pages Message-ID: <20140429025744.5cab7f04.freebsd@edvax.de> In-Reply-To: <CAHHBGkowe3LtCrncHMUfC9GDUwPfnXXgT0UaKLqb=dSdh21cQA@mail.gmail.com> References: <43930.1398634658@server1.tristatelogic.com> <CAHHBGkowe3LtCrncHMUfC9GDUwPfnXXgT0UaKLqb=dSdh21cQA@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, 28 Apr 2014 20:18:07 -0400, illoai@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. :-) -- Polytropon Magdeburg, Germany Happy FreeBSD user since 4.0 Andra moi ennepe, Mousa, ...
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20140429025744.5cab7f04.freebsd>