From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from minnie.tuhs.org (minnie.tuhs.org [45.79.103.53]) by inbox.vuxu.org (OpenSMTPD) with ESMTP id b657a005 for ; Mon, 19 Nov 2018 22:09:46 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id E8FA99474D; Tue, 20 Nov 2018 08:09:44 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id BBF18945F5; Tue, 20 Nov 2018 08:09:12 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 84916940FA; Tue, 20 Nov 2018 08:09:04 +1000 (AEST) Received: from imap.thunk.org (imap.thunk.org [74.207.234.97]) by minnie.tuhs.org (Postfix) with ESMTPS id 152C6940F8 for ; Tue, 20 Nov 2018 08:08:59 +1000 (AEST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=thunk.org; s=ef5046eb; h=In-Reply-To:Content-Type:MIME-Version:References:Message-ID: Subject:Cc:To:From:Date:Sender:Reply-To:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=nbtRYNLzSMeR+/5tZqFjkfTHZ5jLQr4OZdlsXZ/kPCM=; b=IjvWPPd2Rcm/MtN4EdZvaC7vUG gThWWca0rDUpvV5vxa0XIiG2Ga5ytaH7pB3sBWlDXkCJcJYZ7IkkB+igf3yaizxrLqKqp81PRS5NY OvdAYKS3F2gzQMY+ZupOdmDcjN3vKgDb69/QqMw9pt64hihTHvTx+z42KWbOaSvjAqDU=; Received: from root (helo=callcc.thunk.org) by imap.thunk.org with local-esmtp (Exim 4.89) (envelope-from ) id 1gOriy-00020t-IE; Mon, 19 Nov 2018 22:08:56 +0000 Received: by callcc.thunk.org (Postfix, from userid 15806) id B3E6E7A046D; Mon, 19 Nov 2018 17:08:55 -0500 (EST) Date: Mon, 19 Nov 2018 17:08:55 -0500 From: "Theodore Y. Ts'o" To: Clem Cole Message-ID: <20181119220855.GB17374@thunk.org> References: <4c36b2b2-76df-435f-27bc-e1feb0647f36@case.edu> <201811162113.wAGLDGiQ031455@darkstar.fourwinds.com> <201811190311.wAJ3BDHR028154@darkstar.fourwinds.com> <20181119173952.GA19377@thunk.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.10.1 (2018-07-13) X-SA-Exim-Connect-IP: X-SA-Exim-Mail-From: tytso@thunk.org X-SA-Exim-Scanned: No (on imap.thunk.org); SAEximRunCond expanded to false Subject: Re: [TUHS] man-page style X-BeenThere: tuhs@minnie.tuhs.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: The Unix Heritage Society mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: tuhs@tuhs.org Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" On Mon, Nov 19, 2018 at 01:40:43PM -0500, Clem Cole wrote: > As is often in these disagreements, I suspect agree more than disagree. > But some of the absolute edges/where you start or stop is where we pick > different things. > > > For what it's worth, that's a Debian packaging standard. All > > executables are supposed to have a man page. > > Right, thank you and I applaud them for that... As you and others have > pointed out, Debian != Gnu Well, technically Debian's Linux is named "Debian GNU/Linux". It's not recognized by the FSF as free (Debian cares about allowing users to have Laptops which aren't paperweights, even if it does mean making available firmware for which source is not available), so they recommend distributions such as gNewSense, which is a Debian-based fork that is now inactive. Personally, I find debates about whether or not Debian != GNU to be much like the bickering between the Judean People's Front versus People's Front of Judea, the latter of which sends a crack squad to commit mass suicide at the end of the movie "Life of Brian". :-) Unless the claim is the only thing which is GNU is HURD? > > In some cases it may be > > no more than a short summary of the options and then a reference to > > the info manual if you want to learn more. > > I think that's somewhat backwards in he spirit of 'UNIX'... the man and > info pages should reference the manual in /usr/doc/foo/ > I think the question really comes to what we see 'info' as. It >>seems<< > to me that you look at info as the 'manual' for the program which many of > us do not; to me info, like man is a quick reference. The info pages are *in* /usr/share/doc/... on a Debian system. And if you were to take a look at the info files for, say, GNU Make, it very much is a full manual. Note: In Debian, "info make" will show the man page if you don't have the info pages installed, which are part of the make-doc package. Perhaps this is why you think info is a quick reference? > Ah, I think this is were you not hearing what I'm saying... the 'primary > manual' as you call it is the document in /usr/doc/make in this case. But > [as others have pointed out, writing that >well<< can be hard]. FWIW: > Feldman's description of make in /usr/doc of Seventh Edition pales compared > to Steve Talbots - but Talbiot was a professional tech writer and while > Feldman's writing is better than my own, he does not write as well as > Talbot IMO. In the case of the info pages for make, the FSF may very well have been able to engage a professional tech writer to help with writing the GNU make manual. The FSF does make money selling dead-tree editions of the make manual. It doesn't make a lot of money, since the exact same version is installed in /usr/share/doc/... as as an info file, but there are those who prefer thumbing through a dead-tree copy of a manual instead of reading it a screen. > info should just be a different interface to man. No more, not less -- the > reference - not the manual. Info is optimized for significantely large pieces of documentation than man pages. So for example, Perl tries to document everything via multiple man pages, but since man uses a simple text pager, and it deosn't have hyperlinks, I don't actually find Perl's attempt to be either a reference *or* a manual to be terribly useful. I would much *prefer* if the perl manual were available as a set of info pages, since having internal hypertext links and a real indexing mechanism would make it far superior than trying to navigate perl's man page hierarchy. As it is, I tend to just give up and use Google plus various web pages, including StackExchange, but that doesn't work well if I'm off-line. Info pages work just *fine* off-line. Or, as you've pointed out many people do, I'll take existing perl scripts and copy snippets out of them, using the cargo-cult school of programming. But using perl's man pages is mostly an exercise in frustration. - Ted