From owner-freebsd-questions@FreeBSD.ORG Wed Aug 6 21:59:10 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 EF9A4E49 for ; Wed, 6 Aug 2014 21:59:10 +0000 (UTC) Received: from mail-qa0-f44.google.com (mail-qa0-f44.google.com [209.85.216.44]) (using TLSv1 with cipher ECDHE-RSA-RC4-SHA (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority G2" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id AB95B2F63 for ; Wed, 6 Aug 2014 21:59:10 +0000 (UTC) Received: by mail-qa0-f44.google.com with SMTP id f12so3095698qad.17 for ; Wed, 06 Aug 2014 14:59:09 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:subject:mime-version:content-type:from :in-reply-to:date:cc:content-transfer-encoding:message-id:references :to; bh=dTWKUDcwHIXSq+3MMsrJA9X/20Y/UYi+4Ep/Ph1GSIA=; b=LQaumTOv93r/L1K1RPsDVqNBbhKHyz6uobdMMvVuZlFDzeFtTQHjcqDhIl/e71KNdS TY4XQmYTQE4zjkfeDa90/eAdmx2zL96nTCHvUp7DGmzVqaoQWcjAW9wZphCBH+qmuSeu KHeyrV0naKAwbrreBUxU2PmycYuqTe1hm1bhfeDuZ/dv3dAw51UCTHN5w/AWXX1DvJS4 Fi6Ty9QAxWvLjevU7Tz0iCFeAF44CzrRItDZ2mpaQMxX9Hv2oFxXpzye7oSS3nPaQIwF JZCKDpf31/QlhA1RxXZ4E5gQhJeSMs6YGSToVljLKppyA1EKTLASGWClBguAebdkEVMg mAcA== X-Gm-Message-State: ALoCoQkREZbeI0vki1gx+1ZY3FSCibLFQYYM45awlGGpcAyc3u21DEOl/2g9YlmVmBD7yqNGqJ6+ X-Received: by 10.224.69.136 with SMTP id z8mr20893789qai.60.1407362349351; Wed, 06 Aug 2014 14:59:09 -0700 (PDT) Received: from [192.168.1.127] (c-71-234-255-65.hsd1.vt.comcast.net. [71.234.255.65]) by mx.google.com with ESMTPSA id w3sm3677710qap.37.2014.08.06.14.59.08 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 06 Aug 2014 14:59:08 -0700 (PDT) Subject: Documentation WAS: pkg question .... Mime-Version: 1.0 (Mac OS X Mail 7.3 \(1878.6\)) Content-Type: text/plain; charset=windows-1252 From: Paul Kraus In-Reply-To: <20140805225107.ccf9944a.freebsd@edvax.de> Date: Wed, 6 Aug 2014 17:59:07 -0400 Content-Transfer-Encoding: quoted-printable Message-Id: <10FF0A4F-F96E-4A68-BA25-56B57AFD4B2E@kraus-haus.org> References: <53E0D2B7.9060402@hiwaay.net> <20140805131910.GA72939@slackbox.erewhon.home> <53E0E281.9030306@hiwaay.net> <20140805225107.ccf9944a.freebsd@edvax.de> To: FreeBSD Questions !!!! X-Mailer: Apple Mail (2.1878.6) Cc: Polytropon X-BeenThere: freebsd-questions@freebsd.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: User questions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 06 Aug 2014 21:59:11 -0000 On Aug 5, 2014, at 16:51, Polytropon wrote: > Please understand that "modern" software does not come with > manpages anymore. Thank you for putting =93modern=94 in quotes. > Documentation, _if_ it actually exists, is > scattered across the web. And we know how much we can trust what we find =93on the web=94. > You'll find it in discussion forums, > blogs, user home pages, and wikis. Sometimes, there's something > in /usr/local/share, but don't bet your money on it... :-) And that was (and is) one the reasons I have chosen FreeBSD for my = production systems. And I mean that is a very positive way. The = documentation, all of it, not just the man pages, for FreeBSD is very = much supper to what one can find for many other =93modern=94 operating = systems . I originally cut my teeth on SunOS / Solaris (not counting the time I = spent with C/PM, Basic, Cromix, AmigaDOS, =85) where man pages were all = available but NOT part of the core installation, they were included in = the =93Developer=94 tier :-) So I am used to being able to type =93man = =94 and getting useful information (often way too much, = try `man sh` sometime). So I am spoiled in that regard. On concrete example of how the FreeBSD documentation beats the pants off = of Linux (I forget the distro right now). I had a server running FreeBSD = with VirtualBox for virtualization. I had both FreeBSD and Linux VMs. = There was a problem where the boot block on the VM was damaged. By = looking in the FreeBSD Handbook I was able to find the boot process = documented, this enabled me to reconstruct the boot block fairly = painlessly. I had the same issue happen with a Linux and VM and finding = the details of *how* the system boots was like pulling teeth. One = document just referred to another and round and round. The documentation = for GRUB, especially GRUB2, is particularly cryptic *if* something is = going *wrong*. Of course the short answer is always to just =93read the = source code=94, which, as anyone who is not intimately familiar with = that particular piece of code can tell you, is almost useless. In my opinion, documentation is one of the signs of professional, mature = software. Thank you to all the varied FreeBSD people who have = contributed to the stores of official (or at least semi-official) = documentation available. > No, seriously: Most desktop environments don't have manpages. > Few programs have, because nobody reads them. Still there are > some exceptions, like "man opera", "man openoffice", "man xmms" > or "man gmplayer". On the other hand, try "man firefox", "man kde" > or "man grip=94. There can be good reasons to *not* include a FULL man page for a = graphical tool, but at the very least the command line options and = arguments ought to be documented. Even if the man page is not more than = a glorified version of =97help. But putting the FULL = documentation in a man page is really silly (see my earlier reference to = the man page for sh; or bash, or see or awk or =85) There have been = entire *books* written on the use of sed, awk, and even sh (see the = O=92Reilly Nutshell books for great examples), putting *all* you can do = with sed in a man page is overkill. > On one of my older systems where I have XFCE 3 installed, when > I type "man xfce", do you know what happens? A manpage appears! > You can see: Sometimes, someone made a decision not to maintain > manpages anymore and instead concentrate on software features, > look & feal, following the most recent Linux development and > just coding along. This is a _valid_ decision, even though a > minority of 0.01% of the users might not appreciate it. ;-)=20 I understand that developers want to develop and not write manuals. And = since most of this is being done for fun, they concentrate on the fun = parts. I actually think that for many man pages the number of people who = use that function (program, configuration file, etc.) that would like a = good man page is much higher than your 0.01% number. I am thinking = mainly of system admin functions that most end users never even think = about, but let the automated install scripts handle for them. -- Paul Kraus paul@kraus-haus.org