From owner-freebsd-questions@FreeBSD.ORG Tue Apr 29 00:59:06 2014 Return-Path: Delivered-To: freebsd-questions@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 0BADDD0F for ; Tue, 29 Apr 2014 00:59:06 +0000 (UTC) Received: from mx02.qsc.de (mx02.qsc.de [213.148.130.14]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id C11E3182B for ; Tue, 29 Apr 2014 00:59:05 +0000 (UTC) Received: from r56.edvax.de (port-92-195-108-40.dynamic.qsc.de [92.195.108.40]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx02.qsc.de (Postfix) with ESMTPS id 98F8827701; Tue, 29 Apr 2014 02:58:55 +0200 (CEST) Received: from r56.edvax.de (localhost [127.0.0.1]) by r56.edvax.de (8.14.5/8.14.5) with SMTP id s3T0vipi002544; Tue, 29 Apr 2014 02:57:44 +0200 (CEST) (envelope-from freebsd@edvax.de) Date: Tue, 29 Apr 2014 02:57:44 +0200 From: Polytropon To: "illoai@gmail.com" Subject: Re: missing man pages Message-Id: <20140429025744.5cab7f04.freebsd@edvax.de> In-Reply-To: References: <43930.1398634658@server1.tristatelogic.com> Organization: EDVAX X-Mailer: Sylpheed 3.1.1 (GTK+ 2.24.5; i386-portbld-freebsd8.2) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Cc: "freebsd-questions@freebsd.org" , "Ronald F. Guilmette" X-BeenThere: freebsd-questions@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list Reply-To: Polytropon List-Id: User questions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 29 Apr 2014 00:59:06 -0000 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, ...