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=-1.0 required=5.0 tests=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 9b761e44 for ; Wed, 28 Nov 2018 00:09:52 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id 583E5A1CFC; Wed, 28 Nov 2018 10:09:51 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 98843A1CE2; Wed, 28 Nov 2018 10:09:15 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 2668CA1CE4; Wed, 28 Nov 2018 10:09:14 +1000 (AEST) Received: from knecht.neophilic.com (knecht.neophilic.com [70.36.157.234]) by minnie.tuhs.org (Postfix) with ESMTPS id 24FCBA1CE2 for ; Wed, 28 Nov 2018 10:09:13 +1000 (AEST) Received: from rieux.neophilic.com (rieux.neophilic.com [10.0.2.35]) (authenticated bits=0) by knecht.neophilic.com (8.15.2/8.15.2) with ESMTPSA id wAS09CKI085599 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128 verify=NO) for ; Tue, 27 Nov 2018 16:09:12 -0800 (PST) (envelope-from eric@neophilic.com) From: Eric Allman To: tuhs@tuhs.org References: <201811160003.wAG03mlF139232@tahoe.cs.Dartmouth.EDU> <20181116045016.GK3341@mcvoy.com> <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> Openpgp: preference=signencrypt Autocrypt: addr=tuhs@eric.allman.name; prefer-encrypt=mutual; keydata= xsDiBDu8yuARBADuTa8bzS4Er9urm7XPu5vtrRRJMoY2/mvuQeRHpvHF6ncUF2ZC9nAkIYb6 Upl9UOCZxG6uwxzzzSnxeHg7aAVY/TEN4FukuN1X1aGvol/V8PM1nV5vyLFk/Tf/Q/yoN/w8 tK9dp/O2EflChD/i/J9vWIppg3rVKK6FPW4CuqqaiwCg/ytVY7yJHZCCrhRioLBtKaCGUB0D /20dzSKBUdOxSvfg3NKt7gojiqulxmNbRkkjuhbKMRiQ0jjt16L9h+zlS1mXNT91/Ds08WtF 99Z3YffTflcbU9uBea6AJhzIaYVHwCJsNyP+rGE+9CM1YZpwm5k/ZBr7iOr0tkI1o39JRg75 Ih18gnPVXovH+VhsXRGtxTqn7+dmBADmmsHL8u/qbBWKIC3TYpXH8rJBIJXHwvOrI4HbEvAh xzD/Zy6yGMgiTZ8quGHzmdm1kD53s/TVcgEo/XWlgy9Cr05tU16UGEx/Q38K4IetCTGjhOvY a0+I012p5ZK1KqnIjUuCAy7VgGy75sBPKzYeUjJ1yAO7+EMXaZP6Olejn80iRXJpYyBQLiBB bGxtYW4gPGVyaWNAU2VuZG1haWwuQ09NPsJOBBARAgAOBAsDAQICGQEFAju8yuEACgkQMRmA Uc8aTSwR/gCfcq/84OdF6e6hkUQQbVFPqsxS6N0An13gLkFVkPJrMs+5PK5ogl0k7yW8zsFN BDu8yuAQCAD2Qle3CH8IF3KiutapQvMF6PlTETlPtvFuuUs4INoBp1ajFOmPQFXz0AfGy0Op lK33TGSGSfgMg71l6RfUodNQ+PVZX9x2Uk89PY3bzpnhV5JZzf24rnRPxfx2vIPFRzBhznzJ Zv8V+bv9kV7HAarTW56NoKVyOtQa8L9GAFgr5fSI/VhOSdvNILSd5JEHNmszbDgNRR0PfIiz HHxbLY7288kjwEPwpVsYjY67VYy4XTjTNP18F1dDox0YbN4zISy1Kv884bEpQBgRjXyEpwpy 1obEAxnIByl6ypUM2Zafq9AKUJsCRtMIPWakXUGfnHy9iUsiGSa6q6Jew1XpMgs7AAICB/0d vsPKvMXcKls8RHeYcleBEQEgXovGaTNo8R3ZVjPcDUKcQbfWMP8w5qJKf36hvBsjEgfVJW7r lKUtA82H66ivnAgAqWZMgfROKSHwaTFScFWLR8lG5e7sd2OZ4xqDe6+BpYlmJocR2riughz8 B7p1RhINqpfslZ0QEdB/fscntjoBvohtjG80BwB/tB6gnWHsjd9Cv6QfiNYOzAWaQo+BmcFq kmTYwrXFFNWHjOWfCUyjg2kqztl0DHjmZ7AzgHgTEnPku2TlMXwaGbHZKDOwLP/dteywinK6 SEOW2HrQBMxkMQGEZWtOH6hjszJtkqn+V4O0c92d4FjaQhvleSL7wj8DBRg7vMrgMRmAUc8a TSwRAklEAJ44uotW5aUoI1uMu94xIkLeCI6iWACg1IbChgU5suH4a+T68hfH8Jwa140= Message-ID: <6a179556-322c-8ba5-b957-5ae7a03ec610@neophilic.com> Date: Tue, 27 Nov 2018 16:09:12 -0800 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 8bit Subject: [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: , Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" [I sent this almost a week ago, but it never showed up, probably because my From address didn't match my subscription address. Apologies if this is a dup.] On 2018-11-19 07:35 , Clem Cole wrote: > 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.  On 2018-11-19 09:39 , Theodore Y. Ts'o wrote: > 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. The /usr/doc//... convention started at least as far back as 7th Edition (and I think 6th as well). There was no attempt to make the man page for yacc or troff document everything you needed to know --- they basically listed the command line arguments and gave you a pointer to the real manual, which went into far more depth than would be feasible in a man page, sometimes including things like tables and figures (using tbl and fig, of course). Speaking of troff, that was interesting documentation. Ossanna's documentation told you exactly what all of the commands did, but didn't say why they did it. Many of the features seemed absolutely crazy at first. I probably read that document 50 times when writing the -me macros, every time having a light bulb go off in my head. I finally concluded that _everything_ was needed to do something useful, and you could do pretty much _anything_ with the available tools (including things like page balancing). A master work of design, and blissfully complete documentation (even if a bit obscure to the newbie). eric