Re: [9front] 9front man pages

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

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