Re: [9front] 9front man pages

[qwx@sciops.net]

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