Re: [9front] 9front man pages

[sirjofri <sirjofri+ml-9front@sirjofri.de>]

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