[9front] 9front man pages

[9front] 9front man pages

[eso]

I would like to improve 9front's documentation. We all know it's not 
great. But those who are in the best position to rewrite them (those 
most knowledgeable) see it as not worth their time, which is more than 
justified. I am not a computer science professional, I'm just a writer. 
Technology is a hobby for me. I cannot write you a filesystem, but maybe 
I can write the documentation for it?
I'm willing to try and rewrite the documentation, and I can occasionally 
check in with the heavy hitters to see if I'm straight. But first I want 
to get some feedback on the objectives of a man page redux.
- Runtime options are listed for readability, like OpenBSD. You 
shouldn't have to grep for the most basic information.
- Explanations of software usage should represent a typical 9front user 
setup. You could argue that'd be a standalone machine, but I think the 
appropriate model would be a local fs+auth server. No more Bell Labs 
examples. None of us have that many gateways and nameservers. Nobody has 
a gnot terminal. Nobody has a jukebox. And who is emelie? This would be 
most relevant to section 8, system administration.
- Usage examples should not be exhaustive, but should cover the most 
well-tread paths as far as usage. The first tar(1) man page example 
should be extracting a tarball, because that’s what most people use tar 
for day-to-day. And if you can imagine a crazy world where you aren't a 
powerful technomancer, and thus don't have the tar options memorized, 
you could imagine that would be what you'd go looking for in the manual 
if you weren't sure. A dd(1) example should be something like cloning 
drives, something people often use dd for.

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.

My Best,

Verbose

Re: [9front] 9front man pages

[Jacob Moody]

On 3/7/24 22:47, eso@self.rodeo wrote:
> I would like to improve 9front's documentation. We all know it's not 
> great. But those who are in the best position to rewrite them (those 
> most knowledgeable) see it as not worth their time, which is more than 
> justified. I am not a computer science professional, I'm just a writer. 
> Technology is a hobby for me. I cannot write you a filesystem, but maybe 
> I can write the documentation for it?
> I'm willing to try and rewrite the documentation, and I can occasionally 
> check in with the heavy hitters to see if I'm straight. But first I want 
> to get some feedback on the objectives of a man page redux.
> - Runtime options are listed for readability, like OpenBSD. You 
> shouldn't have to grep for the most basic information.
> - Explanations of software usage should represent a typical 9front user 
> setup. You could argue that'd be a standalone machine, but I think the 
> appropriate model would be a local fs+auth server. No more Bell Labs 
> examples. None of us have that many gateways and nameservers. Nobody has 
> a gnot terminal. Nobody has a jukebox. And who is emelie? This would be 
> most relevant to section 8, system administration.
> - Usage examples should not be exhaustive, but should cover the most 
> well-tread paths as far as usage. The first tar(1) man page example 
> should be extracting a tarball, because that’s what most people use tar 
> for day-to-day. And if you can imagine a crazy world where you aren't a 
> powerful technomancer, and thus don't have the tar options memorized, 
> you could imagine that would be what you'd go looking for in the manual 
> if you weren't sure. A dd(1) example should be something like cloning 
> drives, something people often use dd for.

This would be touching the artwork for me honestly. I personally love
some of those more historical examples(Kremvax is my favorite). I think
our manual pages overall are pretty great and I don't think the examples
need to be min-maxed for most common deployment. We're here to have some
fun as well.

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'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.

Just my 2 cents.


Thanks,
moody

Re: [9front] 9front man pages

[ori]

Overall, this sounds reasonable to me (though I'd argue that 9front docs
are pretty good, there's certainly room to improve them).

I'd just suggest going one manpage at a time, and getting feedback
as you go; you'll probably get a feel for what the docs should be as
we discuss. There's a lot to improve, but I think you'll find there's
a lot we quite like about the current style.

Quoth eso@self.rodeo:
> I would like to improve 9front's documentation. We all know it's not 
> great. But those who are in the best position to rewrite them (those 
> most knowledgeable) see it as not worth their time, which is more than 
> justified. I am not a computer science professional, I'm just a writer. 
> Technology is a hobby for me. I cannot write you a filesystem, but maybe 
> I can write the documentation for it?

I disagree. There's room to improve, but I think the
system is relatively well docuemnted. It also seems
that we do think it's worth our time, but nobody has
stepped forward to do a thorough review.

If you want to do that, this would be welcome.

> I'm willing to try and rewrite the documentation, and I can occasionally 
> check in with the heavy hitters to see if I'm straight. But first I want 
> to get some feedback on the objectives of a man page redux.
> - Runtime options are listed for readability, like OpenBSD. You 
> shouldn't have to grep for the most basic information.

I'm assuming by this, you mean a table of flags? I'm
in favor of that.

> - Explanations of software usage should represent a typical 9front user 
> setup. You could argue that'd be a standalone machine, but I think the 
> appropriate model would be a local fs+auth server. No more Bell Labs 
> examples. None of us have that many gateways and nameservers. Nobody has 
> a gnot terminal. Nobody has a jukebox. And who is emelie? This would be 
> most relevant to section 8, system administration.

"typical" varies, but we can discuss on a case by case
basis.

> - Usage examples should not be exhaustive, but should cover the most 
> well-tread paths as far as usage. The first tar(1) man page example 
> should be extracting a tarball, because that’s what most people use tar 
> for day-to-day. And if you can imagine a crazy world where you aren't a 
> powerful technomancer, and thus don't have the tar options memorized, 
> you could imagine that would be what you'd go looking for in the manual 
> if you weren't sure. A dd(1) example should be something like cloning 
> drives, something people often use dd for.
> 

I think we could use more examples, but I don't think we
should turn manpages into tutorials.

> 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 the biggest missing thing in the 9front documentation
is is a set of "theory of operation" type documents that sit
between manpages and the fqa, and walk through how the pieces
of the system are meant to interact.

I attempted something in that style here:

   https://wiki.9front.org/upas-theory

Re: [9front] 9front man pages

[Roberto E. Vargas Caballero]

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,

Re: [9front] 9front man pages

[qwx]

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

Re: [9front] 9front man pages

[hiro]

"We all know it's not great"
This is the second sentence in this thread.
Yeah, do we then? How do you know?

Re: [9front] 9front man pages

[hiro]

Also, generally, I think *not* having a disparate "documentation team"
is a feature, so far.
I prefer it when people change code (and relevant documentation)
gradually. If you add a new feature, this will require obvious
additions to the documentation. If this entitles you to touch the
documentation anyways, I understand you might rework the surrounding
sentences slightly to make more sense. But redoing everything from the
ground up is not something we generally do here just for the sake of
keeping busy.
If the documentation has a bug, send a patch. People regularly make
errors, forget things, etc. But keep the changes minimal.

Re: [9front] 9front man pages

[hiro]

verbose is a real name, or an attribute?

Re: [9front] 9front man pages

[eso]

Hiro:
> Redoing everything from the ground up is not something we generally
> do here just for the sake of keeping busy
I was not thinking of a ground-up kind of thing. Just a pass-through
with the ideas in my original email in mind.
> Yeah, do we then? How do you know?
I'm sorry for the ambiguity. By "not great" I do not mean "bad" but
just not great, excellent, exceptional. I was talking with 9fans the
day before and I got the feeling that "needs improvement" was an apt
consensus from all those I spoke with. But I apologize for projecting
my narrow slice of perspective on the larger community.
> verbose is a real name, or an attribute?
Both.

Moody:
> This would be touching the artwork for me honestly. I personally love
> some of those more historical examples(Kremvax is my favorite).
I appreciate this perspective. It will not be ignored.

> our manual pages overall are pretty great and I don't think the 
> examples
> need to be min-maxed for most common deployment. We're here to have 
> some
> fun as well.
My perspective is simply that the purpose of manuals should be to help 
the users.
I don't think you need to redact kremvax or rewrite the docs to do that, 
but in
my opinion there is some room for improvement.

> 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.
I would like that actually, I can do this in supplement to whatever work 
on the
manuals gets done. And having this supplementary resource in mind would 
keep
more examples and explanation out of the man pages, which is something 
others
have expressed concern over.

> 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.
See next quote...

Ori:
> I'd just suggest going one manpage at a time, and getting feedback
> as you go; you'll probably get a feel for what the docs should be as
> we discuss. There's a lot to improve, but I think you'll find there's
> a lot we quite like about the current style.
I'm going to move forward with this. My initial email was trying to get 
some
feedback before I start sending patches, and I've gotten plenty. So I 
will start
sending patches. And I will lose the mentality of a grand effort. Sorry, 
I am
naturally a more idealist head-in-the-clouds kind of person which I 
understand
is inappropriate for this project.

> I think we could use more examples, but I don't think we
> should turn manpages into tutorials.
I agree, that's what I meant by "Usage examples should not be 
exhaustive."
I do value tutorials, but those should stay out of the manuals.

> I think the biggest missing thing in the 9front documentation
> is is a set of "theory of operation" type documents that sit
> between manpages and the fqa, and walk through how the pieces
> of the system are meant to interact.
I agree.

Roberto:
> 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.
I'm not in the best position to fill in hidden information, but I think 
the
limitations and context are in the same vein as what Ori said above.

qwx:
> just pick manpages you would like to improve, and write a patch,
> so something more specific could be discussed.

Will do. People seem very split on the table of flags vs how it is 
currently.
I'll give others more time to discuss that, and focus on lower hanging 
fruit in
the mean time. Thanks for your messages, and apologies if my formatting 
is crap,
since I'm doing it manually without knowing how wide 80 columns actually 
is on
this email client. Just eyeballing it. Anyways, happy Friday.

verbose

Re: [9front] 9front man pages

[qwx]

On Fri Mar  8 17:02:32 +0100 2024, eso@self.rodeo wrote:
> Thanks for your messages, and apologies if my formatting 
> is crap,
> since I'm doing it manually without knowing how wide 80 columns actually 
> is on
> this email client. Just eyeballing it. Anyways, happy Friday.

Just a tip, but you can use fmt(1) for this.  My F [1] rc script
starts hold(1) then formats the text I typed in when I end it and
pushes that to the snarf buffer so I can directly paste it in
nedmail(1).  I'm certain others have better approaches as well.

Cheers,
qwx

[1] http://shithub.us/qwx/rc/HEAD/bin/F/raw

Re: [9front] 9front man pages

[Lyndon Nerenberg (VE7TFX/VE6BBM)]

My biggest concern with these sort of well meant attempts to help
with documentation is this:

  Writing *good* documentation about a piece of software
  requires you to have an intimate understanding of that
  software, down to its core.

Without that, you will make mistakes.  And quite often what sets
apart an amazing manpage from a good one is how it expresses the
subtleties of the software it is describing.  That requires a deep
understanding of the subject matter.

For the most part, the Plan 9 manpages are well written as they
stand.  A few suffer from ESL syndrome and could use some copy
editing to remove ambiguity.  But a wholesale drive-by edit of
everything is wrong, IMO.

My major gripe with all the manpages is how the options are documented.
I will disagree with Rob Pike until the day I die that they should
be described in-line as they currently are.  Just like he has
red-green colour blindness problems, I suffer from diplopia (very
bad double vision) that makes spotting those flag definitions nearly
impossible.  I firmly believe options should be explicitly called
out in a single section in tagged paragraph form (i.e. the idiomatic
format used in all the BSD manpages).  But that's a bikeshed for
another day.

In summary, I encourage you to find ways to contribute to the
community.  If you want to help with documentation, I would start
out by picking one or two manpages you feel need an update, then
proposing your changes.  I suspect you will learn a lot from the
ensuing discussion.  There is a lot of history behind the style and
conventions used; you can't ignore that.

--lyndon

Re: [9front] 9front man pages

[hiro]

> impossible.  I firmly believe options should be explicitly called
> out in a single section in tagged paragraph form (i.e. the idiomatic
> format used in all the BSD manpages).  But that's a bikeshed for
> another day.

they are. in the source-code.

Re: [9front] 9front man pages

[umbraticus]

> they are. in the source-code.

indeed. you could have a tool called usage that greps for lines like

case 'f': /* explanation of f flag */

within ARGBEGIN{}ARGEND, with a matching style convention.

and whatever the equivalent for rc scripts is.

or maybe src(1) is good enough.

umbraticus

Re: [9front] 9front man pages

[ori]

Quoth umbraticus@prosimetrum.com:
> > they are. in the source-code.
> 
> indeed. you could have a tool called usage that greps for lines like
> 
> case 'f': /* explanation of f flag */
> 
> within ARGBEGIN{}ARGEND, with a matching style convention.
> 
> and whatever the equivalent for rc scripts is.
> 
> or maybe src(1) is good enough.
> 
> umbraticus

We could also add a semantic tag to the manpage macro
set for tags, so they render inline, but can be found
with some tool.

	The flag
	.FL -a sends all output to stderr

and the flags can be indexed/searched from this.

	wtf grep -a

(wtf, of course, stands for 'whats the flag')

Re: [9front] 9front man pages

[sl]

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

Re: [9front] 9front man pages

[hiro]

since you bring up uriel, the requirement to edit the man page should
obviously be to have first studied strunk&white's for any aspiring
editor.

Re: [9front] 9front man pages

[Stanley Lieber]

On March 8, 2024 8:08:04 PM EST, hiro <23hiro@gmail.com> wrote:
>since you bring up uriel, the requirement to edit the man page should
>obviously be to have first studied strunk&white's for any aspiring
>editor.
>

and dr slump in the original catalan (rip toriyama san).

sl

Re: [9front] 9front man pages

[sirjofri]

Hi all,

as one who did some man page editing earlier and who likes writing documentation in general, I also have to raise my voice at some point.

I personally see two use cases for man pages, both are drastically different:

(1) You read a man page to understand how a program is working and how you should use it. For this use case it's important to read the man page, not only skim for arguments. Of course, some details can still be in the list/table layout, for example all the flags and attributes for print(2). For this use case, I also prefer to have most things as prose, only to prevent new people from using the program before reading the man page thoroughly (users tend to pick the flags, run the program, and wonder why nothing works, only to ask other users who can respond with rtfm).

(2) If you already know how a program works and how to use it, but you just want to know about a single flag or something. In this case, you usually don't want to read a full book, a simple list with description is often enough.

I don't think the man pages as they currently are fit both use cases to perfection, and I don't think they can. We have docs that are more towards (1) (or even surpassing that case), and some programs have a usage function which is just too little for (2).

I like the idea of having an additional .FL troff macro for flags, though I think it's still impossible to get a good format using it, because of the nature of how the man pages are written. It can be much easier to find the flag though.

I also like the idea of having an additional program that parses the source file for everything in between ARGBEGIN/ARGEND, combined with comments for description. Flags without comment could be omitted to have the option of omitting debug functionality, and it's easy enough to document with that. On the other hand, that puts part of the documentation into the source code, which is very much different from how man pages work.

I would probably use both solutions, but both are a lot of work on existing files. Regarding the flag macro, I think it's still a question of how to use it. Page can't jump to a specific line, and how would you parse the whole thing? The naive solution would probably be to only print this paragraph, or (in case of troff) highlight it differently in some case to make it easier to find.

I would certainly help edit the man pages to fit the new scheme, and I'd also help adjust the comments in ARGBEGIN/ARGEND as far as I can. I can also write a src-like program that extracts the details from the programs (wtf), but that's probably so trivial that any developer could do that.

Another point that ori mentioned: the theory of how things work. I see that there's lots of stuff missing in that regard. It would certainly be nice to have some documents in the sense of /sys/doc, though I can perfectly see that we don't want to change the historical artwork there and clutter it with thousands of modern pages. I can imagine some separate repo for that (similar to how fqa is separate), something that can be seen as a part of the system, but is separate. On the other hand, we won't have too much so we could as well include it into /sys/doc, extending the historical artwork. Nevertheless, the biggest issue is: who's gonna write all that? It's a lot of work.

I know there's the wiki, but tbh many people don't know about it, and the quality is ... varying. Also, the current implementation is very flat (unlike wikifs), so it's also hard to structure it in the sense of what's commonly known as a wiki.

sirjofri

Re: [9front] 9front man pages

[Lyndon Nerenberg (VE7TFX/VE6BBM)]

sirjofri writes:

> I also like the idea of having an additional program that parses the source f
> ile for everything in between ARGBEGIN/ARGEND, combined with comments for des
> cription. Flags without comment could be omitted to have the option of omitti
> ng debug functionality, and it's easy enough to document with that. On the ot
> her hand, that puts part of the documentation into the source code, which is 
> very much different from how man pages work.

The trouble with this approach is it only works with the languages
it knows about.

What if I write something in Fortran?  Or Go?  Or whatever other
language I port across.  Whatever this is, it needs to be universal,
and I don't see a practical solution.

I don't really believe the argument that people will read only
the flags documentation and ignore the manpage.  Someone that lazy
is likely not reading the manpage at all.  And anyway, that argument
is purely speculation.

Whenever you read technical documentation, those sorts of enumerated
lists are almost always called out separately.  There are several
reasons for that, readablilty being paramount.

While I'm a firm believer in precedent, it's shouldn't be cast in
granite.  I firmly believe documenting command flags inline was a
mistake.  We should be able to admit that and fix it.

--lyndon

Re: [9front] 9front man pages

[sirjofri]

10.03.2024 20:18:25 Lyndon Nerenberg (VE7TFX/VE6BBM) <lyndon@orthanc.ca>:

> sirjofri writes:
>
>> I also like the idea of having an additional program that parses the source f
>> ile for everything in between ARGBEGIN/ARGEND, combined with comments for des
>> cription. Flags without comment could be omitted to have the option of omitti
>> ng debug functionality, and it's easy enough to document with that. On the ot
>> her hand, that puts part of the documentation into the source code, which is
>> very much different from how man pages work.
>
> The trouble with this approach is it only works with the languages
> it knows about.
>
> What if I write something in Fortran?  Or Go?  Or whatever other
> language I port across.  Whatever this is, it needs to be universal,
> and I don't see a practical solution.

That's a valid point. I was also briefly thinking about rc programs, and that has the same problem, basically (although we have a standard there).

> I don't really believe the argument that people will read only
> the flags documentation and ignore the manpage.  Someone that lazy
> is likely not reading the manpage at all.  And anyway, that argument
> is purely speculation.
>
> Whenever you read technical documentation, those sorts of enumerated
> lists are almost always called out separately.  There are several
> reasons for that, readablilty being paramount.

I also sometimes see man pages with both practices on the same page. While one part discussed the arguments inline, another section has a list/table of arguments that's suitable for a look-up table. That would of course lengthen the man pages, but also be helpful.

I often find myself looking for all the print(2) arguments. I know how print works, so I don't need all the page, but the table only. Sometimes it would be nice to just open that part of the page and skip everything else, but there can't be a single solution for everything.

> While I'm a firm believer in precedent, it's shouldn't be cast in
> granite.  I firmly believe documenting command flags inline was a
> mistake.  We should be able to admit that and fix it.

I don't believe it's a mistake. I think "mistake" is a strong word for decisions like that. I'm sure the inventors invested lots of thought and discussion to get to this decision, although it doesn't seem like that in the modern light.

Coming from a hypertext perspective, the format of the content is never "correct" for all use cases. You can present something as a list, as paragraphs, as a table, as a guided tour or even graphics. Just ask ChatGPT to tell you about the command line flags written as a poem. Useful? Probably not at all. Though that discussion leads to nothing and I know people don't like AI (for reasons). Better find a way to write documentation that helps most people in most cases.

sirjofri

Re: [9front] 9front man pages

[hiro]

> While I'm a firm believer in precedent, it's shouldn't be cast in
> granite.  I firmly believe documenting command flags inline was a
> mistake.  We should be able to admit that and fix it.

i don't need to admit anything that isn't true.
and btw, if you're bored... there's enough other more important things
to fix, work on.