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,UNPARSEABLE_RELAY 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 3E23A258D6 for ; Fri, 8 Mar 2024 06:29:41 +0100 (CET) Received: from simple-cc.openbsd.amsterdam ([46.23.94.210]) by 9front; Fri Mar 8 00:28:52 -0500 2024 Received: from localhost (simple-cc.openbsd.amsterdam [local]) by simple-cc.openbsd.amsterdam (OpenSMTPD) with ESMTPA id 7db482d7 for <9front@9front.org>; Fri, 8 Mar 2024 06:28:49 +0100 (CET) Date: Fri, 8 Mar 2024 06:28:49 +0100 From: "Roberto E. Vargas Caballero" To: 9front@9front.org Message-ID: References: <682a654116e2456730491ae1f0f0e326@self.rodeo> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: leveraged lifecycle template out-scaling self-signing layer Subject: Re: [9front] 9front man pages Reply-To: 9front@9front.org Precedence: bulk Hi, On Thu, Mar 07, 2024 at 11:07:14PM -0600, Jacob Moody wrote: > I am also not sure what you mean by "Runtime options are listed for > readability", do you mean to have a table layout for all command line > options consistently? If so I also would not personally be a fan of that. I agree with Moody here. The 9front man pages are written from the point of view of a full lecture of the page, giving a good organization of the text and relating options between them. Moving to have a table of options will enforce a bad documentation culture where the full overall reason of the options is lost because they are dealt individually. I think the SYNOPSIS section is already providing a good summary. > > I'd like to hear what others think. Also I was thinking this would just > > cover system usage sections like userland, system administration, file > > servers, etc. But if it goes well, maybe we can go beyond that. The last > > patch I submitted, for acmed(8), Ori had some objections about my > > phrasing. So it seems I could use some advisement. But for the record, I > > have experience with technical writing. > > I think what you want would be better suited to something besides the manual > pages. It sounds like a majority of your grips are with examples. Maybe you > could make a git repo full of examples, or perhaps something for the wiki or > the fqa. > > If you feel strongly about some manual page examples I'd say point those out > specifically and we can discuss specific replacements and examples, but a more > general "modernize the manpage examples" is going to be hard to agree to. Indeed. I think there are more important problems with man pages currently, like for example some pages that don't give enough context, pages that miss important limitations or hidden knowledge, or pages that are clearly outdated. Regards,