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 65a8141a for ; Mon, 19 Nov 2018 17:40:33 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id 766C894986; Tue, 20 Nov 2018 03:40:32 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id C3D40940FA; Tue, 20 Nov 2018 03:40:10 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id BD7A9940FA; Tue, 20 Nov 2018 03:40:03 +1000 (AEST) Received: from imap.thunk.org (imap.thunk.org [74.207.234.97]) by minnie.tuhs.org (Postfix) with ESMTPS id 3CD4F940F8 for ; Tue, 20 Nov 2018 03:39:57 +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=uAuTzvjczkoRm6bW10nWk+fyQ4ylFOCh3SXjyoGUP38=; b=RRMiVJpSNey9CTU4WeN2zZ7y3/ 1ru7rby38/mDWKptDxHYPaaz5w9JLLDScNYs5q5tokCcXWOO1Ra5WtdHEYdO5y7/1N2mMFibf96oa 4zzPDsHYkmc30v1Zy6VmTlXxXwwk4ptPCfElmMAgOFg591fgXtvoi/y9gzGwGNiyUgfg=; Received: from root (helo=callcc.thunk.org) by imap.thunk.org with local-esmtp (Exim 4.89) (envelope-from ) id 1gOnWb-0007kn-Nq; Mon, 19 Nov 2018 17:39:53 +0000 Received: by callcc.thunk.org (Postfix, from userid 15806) id 067E17A046D; Mon, 19 Nov 2018 12:39:52 -0500 (EST) Date: Mon, 19 Nov 2018 12:39:52 -0500 From: "Theodore Y. Ts'o" To: Clem Cole Message-ID: <20181119173952.GA19377@thunk.org> References: <7a632484-cdc7-7c59-7077-7a2c752045da@spamtrap.tnetconsulting.net> <4c36b2b2-76df-435f-27bc-e1feb0647f36@case.edu> <201811162113.wAGLDGiQ031455@darkstar.fourwinds.com> <201811190311.wAJ3BDHR028154@darkstar.fourwinds.com> 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: The Eunuchs Hysterical Society Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" On Mon, Nov 19, 2018 at 10:35:05AM -0500, Clem Cole wrote: > And Ted is not that I don't use the unix documents (full papers) - hey I > do. That is how I learned to use 'make' when it appeared (or C for that > matter) from documents in /usr/doc. \ > > What started this whole thread was Doug's comment about how succinct and > to the point man was. If was a fine interface for >>UNIX<<. Man (using > roff) was what people expect. It's not about better or worse -- it worked > and worked well. For what it's worth, that's a Debian packaging standard. All executables are supposed to have a man page. 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. If the upstream package does not provide a man page, Debian maintainers are supposed to create a man page, and hopefully contribute it back upstream. This isn't always the case; but if there isn't a man page, that's always grounds for filing a Debian bug report. > As I said, if man had been maintained as the primary >>manual<< style > interface and /usr/doc//foo.ms as the primary scheme (which >>IS<< > what BSD did), then you don't fail the rule of least astonishment. Then > create a *roff -Tinfo | info_create backend, that produced the info files; > those that want it, get it and love it. Those that >>expect<< man to work > because its UNIX, get what they expect. No one is 'astonished.' I'm not convinced the original BSD man page for, say, "make" is really sufficient to learn how to use make effectively w/o the expanded, non-man page write up in BSD Unix's Programmers Supplementary Documents. So I dare say the goal that the man page should be the primary manual was a bit of an aspiration goal as well. That being said, I'm not convinced nroff is powerful enough to be a source language for info files and HTML files. For one thing, it doesn't have the ability to specify hyperlinks. The GNU an-ext.tmac extensions does define macros to provide *external* hyperlinks to WWW URL's. However, even that doesn't have the ability to specify *internal* hyperlinks to other sections of the document. Cheers, - Ted