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.6 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED,
	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 EDDF8220AE
	for <ml@inbox.vuxu.org>; Fri,  8 Mar 2024 10:02:35 +0100 (CET)
Received: from wopr.sciops.net ([216.126.196.60]) by 9front; Fri Mar  8 04:01:10 -0500 2024
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sciops.net; s=20210706;
	t=1709888459;
	h=from:from:reply-to:subject:subject:date:date:message-id:message-id:
	 to:to:cc:mime-version:mime-version:content-type:content-type:
	 content-transfer-encoding:content-transfer-encoding:  in-reply-to:in-reply-to;
	bh=pxeOKqTQ/FDpL3qa2a+IeqvmyvnGwMlNv7gi26HGqZk=;
	b=eJa+XX8snbQmJ3SqGae47/+ciwAvtxw6yd/s6tPeCaTwMwfZvfPUy6PJwW2Bg7so3XcWr6
	Mv0RehVPAZD75Y1itnH1bS12q0aLd+mCmkZzLWqIgtP0F8SLZcGOsaKCf4uUzgf4aMmvm0
	0TXCrrCr/Xx/OVkgm5vrV9I/YBUJi7Y=
Received: 
	by wopr.sciops.net (OpenSMTPD) with ESMTPSA id 25a5eeef (TLSv1.2:ECDHE-RSA-CHACHA20-POLY1305:256:NO)
	for <9front@9front.org>;
	Fri, 8 Mar 2024 01:00:59 -0800 (PST)
Message-ID: <EA8E7DD33E1DC38BE5AB791865BDA5F1@wopr.sciops.net>
Date: Fri, 08 Mar 2024 10:01:04 +0100
From: qwx@sciops.net
To: 9front@9front.org
In-Reply-To: <ZeqiEWu01G2SoTkT@simple-cc.openbsd.amsterdam>
MIME-Version: 1.0
Content-Type: text/plain; charset="US-ASCII"
Content-Transfer-Encoding: 7bit
List-ID: <9front.9front.org>
List-Help: <http://lists.9front.org>
X-Glyph: ➈
X-Bullshit: SSL over XML method event 
Subject: Re: [9front] 9front man pages
Reply-To: 9front@9front.org
Precedence: bulk

On Fri Mar  8 06:28:55 +0100 2024, k0ga@shike2.com wrote:
> 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.

This has been argued over before and I personally disagree with the
notion of having to read the entire manpage just to find the one flag
I'm interested in.  I would much prefer (with much bias) the
style/format in ipconfig(8) or wadfs(4), combining both.  Then again
that's simply not practical in some cases, so as Ori said it should be
dealt on a case by case basis.


On Fri Mar  8 05:47:24 +0100 2024, eso@self.rodeo wrote:
> 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 there's no point in trying to come up with a general directive
which everyone agrees on; just between us with Ori, moody and k0ga, we
agree on most points, but not all.  I suggest that you just pick
manpages you would like to improve, and write a patch, so something
more specific could be discussed.

Cheers,
qwx