Re: [9front] 9front man pages

["Roberto E. Vargas Caballero" <k0ga@shike2.com>]

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,