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 0a176ef1 for ; Thu, 19 Sep 2019 18:11:38 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id 083F59BBEA; Fri, 20 Sep 2019 04:11:37 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 199D19B906; Fri, 20 Sep 2019 04:11:04 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 668F89B906; Fri, 20 Sep 2019 04:11:02 +1000 (AEST) Received: from oclsc.com (oclsc.com [206.248.137.164]) by minnie.tuhs.org (Postfix) with SMTP id 8E396947B9 for ; Fri, 20 Sep 2019 04:10:59 +1000 (AEST) From: Norman Wilson To: tuhs@tuhs.org Date: Thu, 19 Sep 2019 14:10:45 -0400 Message-ID: <1568916649.17313.for-standards-violators@oclsc.org> Subject: Re: [TUHS] earliest Unix roff X-BeenThere: tuhs@minnie.tuhs.org X-Mailman-Version: 2.1.26 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" Larry McVoy: If you have something like perl that needs a zillion sub pages, info makes sense. For just a man page, info is horrible. ===== This pokes me in one of my longest-standing complaints: Manual entries, as printed by man and once upon a time in the Programmers' Manual Volume 1, should be concise references. They are not a place for tutorials or long-winded descriptions or even long lists of hundreds of options (let alone descriptions of why the developer thinks this is the neatest thing since sliced bread and what bread he had in his sandwiches that day). For many programs, one or two pages of concise reference is all the documentation that's needed; no one needs a ten-page tutorial on how to use cat or rm or ls, for example. But some programs really do deserve a longer treatment, either a tutorial or an extended reference with more detail or both. Those belong in separate documents, and are why the Programmers' Manual had a second volume. Nowadays people think nothing of writing 68-page-long manual entries (real example from something I'm working with right now) that are long, chatty lists of options or configuration-file directives with tutorial information interspersed. The result makes the developer feel good--look at all the documentation I've written!!--but it's useless for someone trying to figure out how to write a configuration file for the first time, and not so great even for someone trying to edit an existing one. Even the Research system didn't always get this right; some manual entries ran on and on and on when what was really needed was a concise list of something and a longer accompanying document. (The Tenth Edition manual was much better about that, mostly because of all the work Doug put in. I doubt there has ever been a better editor for technical text than Doug.) But it's far worse now in most systems, because there's rarely any editor at all; the manuals are just an accreted clump. And that's a shame, though I have no suggestions on how to fix it. Norman Wilson Toronto ON