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 3B5B322E1B for ; Sun, 10 Mar 2024 22:07:44 +0100 (CET) Received: from sirjofri.de ([5.45.105.127]) by 9front; Sun Mar 10 17:06:02 -0400 2024 Received: from dummy.faircode.eu ([31.16.254.30]) by sirjofri.de; Sun Mar 10 22:05:57 +0100 2024 Date: Sun, 10 Mar 2024 22:05:55 +0100 (GMT+01:00) From: sirjofri To: 9front@9front.org Message-ID: In-Reply-To: References: <845a3bf2-df8b-45f7-8f1a-4d09f2688a77@sirjofri.de> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Correlation-ID: List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: firewall YAML over WEB2.0 high-performance event database Subject: Re: [9front] 9front man pages Reply-To: 9front@9front.org Precedence: bulk 10.03.2024 20:18:25 Lyndon Nerenberg (VE7TFX/VE6BBM) : > 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?=C2=A0 Or Go?=C2=A0 Or whatever othe= r > language I port across.=C2=A0 Whatever this is, it needs to be universal, > and I don't see a practical solution. That's a valid point. I was also briefly thinking about rc programs, and th= at has the same problem, basically (although we have a standard there). > I don't really believe the argument that people will read only > the flags documentation and ignore the manpage.=C2=A0 Someone that lazy > is likely not reading the manpage at all.=C2=A0 And anyway, that argument > is purely speculation. > > Whenever you read technical documentation, those sorts of enumerated > lists are almost always called out separately.=C2=A0 There are several > reasons for that, readablilty being paramount. I also sometimes see man pages with both practices on the same page. While = one part discussed the arguments inline, another section has a list/table o= f arguments that's suitable for a look-up table. That would of course lengt= hen the man pages, but also be helpful. I often find myself looking for all the print(2) arguments. I know how prin= t works, so I don't need all the page, but the table only. Sometimes it wou= ld be nice to just open that part of the page and skip everything else, but= there can't be a single solution for everything. > While I'm a firm believer in precedent, it's shouldn't be cast in > granite.=C2=A0 I firmly believe documenting command flags inline was a > mistake.=C2=A0 We should be able to admit that and fix it. I don't believe it's a mistake. I think "mistake" is a strong word for deci= sions like that. I'm sure the inventors invested lots of thought and discus= sion to get to this decision, although it doesn't seem like that in the mod= ern light. Coming from a hypertext perspective, the format of the content is never "co= rrect" for all use cases. You can present something as a list, as paragraph= s, as a table, as a guided tour or even graphics. Just ask ChatGPT to tell = you about the command line flags written as a poem. Useful? Probably not at= all. Though that discussion leads to nothing and I know people don't like = AI (for reasons). Better find a way to write documentation that helps most = people in most cases. sirjofri