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 23391291C5 for ; Sat, 9 Mar 2024 01:43:47 +0100 (CET) Received: from gaff.inri.net ([168.235.71.243]) by 9front; Fri Mar 8 19:40:55 -0500 2024 Message-ID: Date: Fri, 08 Mar 2024 19:40:55 -0500 From: sl@stanleylieber.com To: 9front@9front.org In-Reply-To: MIME-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: distributed encrypted DOM base Subject: Re: [9front] 9front man pages Reply-To: 9front@9front.org Precedence: bulk some questions: - why are the man pages the way they are - which ones are new to 9front some answers: - one of the aims of the original authors was to keep the man pages short, preferrably to one page, if possible. - we've imported or added a lot of new stuff, many of the man pages that appeared alongside that new stuff either disregarded or never promised to adhere to the intentions of plan 9's original authors. some suggestions: - i agree, evaluating one page at a time is the only way forward. read and edit for content, but only if necessary. - i prefer the "table of flags" approach, myself, but have been rebuffed on this point in the past. there is no consensus, so it is what it is. i like ori's suggestion of creating a special macro, but then that implies a massive effort to update every single man page that features flags, and some mechanism for enforcing its use in future (otherwise the effort would be kind of useless), both of which seem unlikely to happen. - "read the source" as an alternative to documenting flags seems to obviate the need for man pages at all, which is quite a bit more radical than editing the man pages that already exist. probably the source and the man pages should be arranged to compliment each other, since neither can really replace the other's intended function. - uriel's suggestion way back when to dive into editing man pages as a way of contributing when you don't know how to do anything else was more geared towards spellcheck and grammar, if i understood him correctly. early in my plan 9 career i stumbled over pretty much this same debate. there was even an argument to omit some debug flags i unearthed because if we documented them then we would have to maintain them (or so the argument went). sl