search

SerenityOS / serenity

The Serenity Operating System 🐞
https://serenityos.org
BSD 2-Clause "Simplified" License
29.82k stars 3.15k forks source link

Base: List of utilities missing man pages #11311

Open AtkinsSJ opened 2 years ago

AtkinsSJ commented 2 years ago

For Application man pages see #21091.

I thought it might be useful to know which utilities lack man pages, since that's not easy to tell otherwise. This is a list manually compiled by comparing the directory listing of /bin with the online man pages. If any are missing, please let me know!

To add a man page, create a <foo>.md file in the relevant section directory. There are plenty of examples in there to copy from.

BenWiederhake commented 2 years ago

Note that you can also auto-generate the manpages if the program uses ArgsParser: https://github.com/SerenityOS/serenity/pull/10655

When writing that PR, I intentionally left out a lot of programs, and only auto-generated those that seem like they're actually going to be useful. More details in the PR.

What that means for you: You could just add a few programs to Base/root/generate_manpages.sh, run ninja image or something to rebuild the image, and run export-argsparser-manpages.sh to write the new manpages back into Base/.

bgianfo commented 2 years ago

What that means for you: You could just add a few programs to Base/root/generate_manpages.sh, run ninja image or something to rebuild the image, and run export-argsparser-manpages.sh to write the new manpages back into Base/.

I'm assuming that will clobber any additional information anyone might have added to those man pages? That seems unfortunate if true?

BenWiederhake commented 2 years ago

I'm not entirely sure what you mean? Have a look at the script, you have to manually approve pages one by one. In other words, existing manpages only get overwritten if you decide that it should be overwritten, and add the program to the list.

Note that a CI step makes sure that the script and the pages remain in sync. If someone tries to add something to the auto-generated pages without adding it to the ArgsParser invocation (or vice versa), that CI job would fail.

bgianfo commented 2 years ago

In other words, existing manpages only get overwritten if you decide that it should be overwritten, and add the program to the list.

Note that a CI step makes sure that the script and the pages remain in sync. If someone tries to add something to the auto-generated pages without adding it to the ArgsParser invocation (or vice versa), that CI job would fail.

It seems like it would be nice if the auto generation only effected the things that can be programmatically be determined, so just the Arguments section of the man page for example. If this was true then I think we would have the best of both worlds, people can enrich man pages with useful information, but the arguments are always kept up to date as programs evolve.

Auto generated man pages without any ability to tweak / enrich them with content seems like an anti pattern. You just end up having a duplication of content with no value add, and you are stuck in that situation forever.

BenWiederhake commented 2 years ago

If you feel that something is missing from a generated manpage, it will also be missing from someprogram --help. So it's a good idea to actually tell ArgsParser about all the information and text you'd like to have there, because then it will also appear in someprogram --help.

How about this: A new argsparser.add_section("Examples", "Arbitrary markdown text");, and we actually get the best of both worlds, where --help and Help(1) have all the information.

bgianfo commented 2 years ago

That works, I guess. Writing markdown inside C++ isn't the greatest experience though, so that seems like a pretty significant downside.

I'm not sure I buy the argument that an application's usage statement should hold the same information as a well written manpage. For example, I'm not sure I would want the description we have in the abench man page (https://man.serenityos.org/man1/abench.html), in the programs usage message?

AtkinsSJ commented 2 years ago

Yeah, my impression is that --help is for a quick overview and description of inputs, whereas the man page is detailed, has examples, maybe goes into using the GUI if the app has one.

I don't see a need to put everything in foo --help when you can just as easily (more easily?) type man foo if you really want all the details.

timschumi commented 1 year ago

md5sum, sha1sum, sha256sum and sha512sum are all symlinks to checksum, which does have a manpage. Therefore, they probably don't qualify for "no manpage".

AtkinsSJ commented 1 year ago

md5sum, sha1sum, sha256sum and sha512sum are all symlinks to checksum, which does have a manpage. Therefore, they probably don't qualify for "no manpage".

:+1: That makes sense. Side note, that page renders in a really goofy way in man though.

cubiclove commented 10 months ago

In #21014 I added a man page for pkg

AtkinsSJ commented 10 months ago

I've just gone through and (hopefully) made sure that all utilities are listed, and all the ones with man pages are marked as complete.

liammulh commented 3 months ago

Hi, is the checklist in the original comment outdated? It looks like blockdev's checkbox is unchecked, but it does have a man page (https://github.com/SerenityOS/serenity/blob/master/Base/usr/share/man/man8/blockdev.md), and it is published online (https://man.serenityos.org/man8/blockdev.html).

I was looking for a good first issue to help out with, so I looked for one with the "good-first-issue" label and the "documentation" label.

I am happy to try to update the list if that would be helpful. :)

AtkinsSJ commented 3 months ago

Hi, is the checklist in the original comment outdated?

It probably is yes. I never noticed that blockdev got a manpage, thanks for letting me know. I've checked it off now.

I am happy to try to update the list if that would be helpful. :)

If you're happy to do that, sure! Just leave a comment here if you spot any others. Thanks! :^)

Add00 commented 2 months ago

Hello, I went a head and reviewed all of the unchecked boxes on the list, I found the following ones now have man pages:

I hope this helps. I'm currently writing some man pages for the tools which do not have one. Is it okay to use the help messages from the commands as a basis for the man page?

AtkinsSJ commented 1 month ago

Thanks! I've marked those as done.

Is it okay to use the help messages from the commands as a basis for the man page?

Sure! We actually have a tool that does just that. It hasn't been used in a while, so it may or may not be useful to you.

Add00 commented 1 month ago

Thank you for pointing out the tool! I'm still learning my way around the project, so I probably wouldn't have noticed it. I'll see if I can use it to assist me with documenting the remaining commands.