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=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 e5ab216d for ; Tue, 18 Feb 2020 01:06:17 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id A85439B958; Tue, 18 Feb 2020 11:06:16 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id 5F1119B92E; Tue, 18 Feb 2020 11:05:59 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 45F539B92B; Tue, 18 Feb 2020 11:05:58 +1000 (AEST) Received: from mail.bitblocks.com (ns1.bitblocks.com [173.228.5.8]) by minnie.tuhs.org (Postfix) with ESMTP id CE4D39B92A for ; Tue, 18 Feb 2020 11:05:57 +1000 (AEST) Received: from bitblocks.com (localhost [127.0.0.1]) by mail.bitblocks.com (Postfix) with ESMTP id 7AA48156E411 for ; Mon, 17 Feb 2020 17:05:50 -0800 (PST) To: The Eunuchs Hysterical Society In-reply-to: Your message of "Mon, 17 Feb 2020 16:17:18 -0800." <202002180017.01I0HI0I1415945@darkstar.fourwinds.com> References: <202002171520.01HFKqKi026749@tahoe.cs.Dartmouth.EDU> <4d252035b323b7583c5760c952d1982c@firemail.de> <202002171839.01HId8FT1358073@darkstar.fourwinds.com> <202002180017.01I0HI0I1415945@darkstar.fourwinds.com> Comments: In-reply-to Jon Steinhart message dated "Mon, 17 Feb 2020 16:17:18 -0800." From: Bakul Shah MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-ID: <89942.1581987950.1@bitblocks.com> Content-Transfer-Encoding: quoted-printable Date: Mon, 17 Feb 2020 17:05:50 -0800 Message-Id: <20200218010557.7AA48156E411@mail.bitblocks.com> Subject: Re: [TUHS] man Macro Package and pdfmark 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" On Mon, 17 Feb 2020 16:17:18 -0800 Jon Steinhart wrote= : > Richard Salz writes: > > > > > 'The problem is that the ecosystem has been fragmented by people doi= ng > > their "documentation" in their preferred formats instead of in a commo= n > > (man) format. > > > > Damn those unauthorized developers. How dare they write code that doe= sn't > > meet standards. > > > > Get off my lawn. > > The relevant TUHS part of it that maybe some folks here can speak to is = how > did UNIX remain so cohesive for so long? How were decisions made? Of c= ourse, > this started to fall apart with System III and such as things got more c= lunky. Agree. I don't mind additional documentation but a man page is strongly preferred. > Noel Chiappa writes: > > I am _sooo_ tempted to say 'What do you think source is for?' :-) > > I think that this is part of the problem, have you looked at the source = for > any modern package? It's pretty impenetrable. I see a lot of overly co= mplex, > poorly written code with no documentation. That makes it really difficu= lt for > someone to extend or otherwise modify it. It's probably easier to creat= e a > new universe than understand an existing one. There is just so much more code now and the S/N ratio is definitely worse but there is more good stuff as well. My problems with using the source as documentation: a) there is usually no or insufficient documentation about even what it is implementing let alone *how* it should be used, b) you don't know if some behavior is an accident of the way the code behaves or actually part of some required (but unwritten) specification. c) even if there some function header comments often there is no top level comment tying together eveyrthing. = d) harder to see missing functionality. e) impossible to grok large programs.