From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <9front-bounces@9front.inri.net> X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) 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,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 Received: from 9front.inri.net (9front.inri.net [168.235.81.73]) by inbox.vuxu.org (Postfix) with ESMTP id 4B81E29D67 for ; Sun, 10 Mar 2024 20:18:26 +0100 (CET) Received: from orthanc.ca ([208.79.93.154]) by 9front; Sun Mar 10 15:16:33 -0400 2024 Received: from orthanc.ca (localhost [127.0.0.1]) by orthanc.ca (OpenSMTPD) with ESMTP id cd05cdf8; Sun, 10 Mar 2024 12:16:32 -0700 (PDT) From: "Lyndon Nerenberg (VE7TFX/VE6BBM)" To: 9front@9front.org, sirjofri In-reply-to: <845a3bf2-df8b-45f7-8f1a-4d09f2688a77@sirjofri.de> References: <845a3bf2-df8b-45f7-8f1a-4d09f2688a77@sirjofri.de> Comments: In-reply-to sirjofri message dated "Sat, 09 Mar 2024 12:01:21 +0100." MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-ID: <77499.1710098192.1@orthanc.ca> Content-Transfer-Encoding: quoted-printable Date: Sun, 10 Mar 2024 12:16:32 -0700 Message-ID: List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: WEB2.0 cloud database-aware session locator Subject: Re: [9front] 9front man pages Reply-To: 9front@9front.org Precedence: bulk sirjofri writes: > I also like the idea of having an additional program that parses the sou= rce f > ile for everything in between ARGBEGIN/ARGEND, combined with comments fo= r des > cription. Flags without comment could be omitted to have the option of o= mitti > ng debug functionality, and it's easy enough to document with that. On t= he ot > her hand, that puts part of the documentation into the source code, whic= h is = > very much different from how man pages work. The trouble with this approach is it only works with the languages it knows about. What if I write something in Fortran? Or Go? Or whatever other language I port across. Whatever this is, it needs to be universal, and I don't see a practical solution. I don't really believe the argument that people will read only the flags documentation and ignore the manpage. Someone that lazy is likely not reading the manpage at all. And anyway, that argument is purely speculation. Whenever you read technical documentation, those sorts of enumerated lists are almost always called out separately. There are several reasons for that, readablilty being paramount. While I'm a firm believer in precedent, it's shouldn't be cast in granite. I firmly believe documenting command flags inline was a mistake. We should be able to admit that and fix it. --lyndon