serenity Base: List of utilities missing man pages

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!

[x] abench
[x] aconv
[x] adjtime
[x] allocate
[x] aplay
[x] arp
[x] asctl
[x] base64
[x] basename
[x] beep
[x] blockdev
[x] bt
[x] cal
[x] cat
[x] checksum
[x] chgrp
[x] chmod
[x] chown
[x] chres
[ ] cksum
[x] clear
[x] cmp
[x] comm
[x] config
[x] copy
[x] cp
[ ] cpp-lexer
[ ] cpp-parser
[ ] cpp-preprocessor
[x] crash
[x] cut
[x] date
[x] dd
[ ] df
[x] diff
[x] dirname
[ ] disasm
[ ] disk_benchmark
[x] dmesg
[x] du
[x] echo
[x] env
[ ] errno
[x] expr
[ ] false
[ ] fdtdump
[ ] fgrep
[x] file
[x] find
[ ] flock
[x] fortune
[ ] functrace
[x] glsl-compiler
[x] gml-format
[x] grep
[ ] gron
[x] groupadd
[x] groupdel
[x] groups
[x] gunzip
[x] gzip
[x] head
[ ] headless-browser
[ ] hello-world (Jakt test file, probably doesn't need a manpage?)
[ ] hexdump
[x] host
[x] hostname
[ ] icc
[x] id
[x] ifconfig
[ ] image
[x] image2bin
[x] ini
[ ] install
[ ] isobmff
[x] jail-attach
[x] jail-create
[x] js
[x] json
[ ] kcov-example (Probably doesn't need a manpage?)
[x] keymap
[ ] kill
[ ] killall
[x] ldd
[x] less
[ ] ln
[ ] logout
[x] ls
[x] lsblk
[ ] lscpu
[ ] lsirq
[x] lsjails
[x] lsof
[x] lspci
[ ] lsusb
[ ] lzcat
[x] man
[ ] markdown-check
[ ] matroska
[x] md
[x] md5sum
[x] memstat
[x] mkdir
[ ] mkfifo
[ ] mknod
[x] mktemp
[x] more
[x] mount
[x] mv
[x] nc
[x] netstat
[ ] network-settings
[x] nl
[x] nohup
[ ] nologin
[x] notify
[ ] nproc
[x] ntpquery
[x] open
[x] passwd
[ ] paste
[ ] patch
[ ] pathchk
[ ] pdf
[x] pgrep
[x] pidof
[x] ping
[ ] pixelflut
[x] pkg
[x] pkill
[x] pledge
[x] pls
[x] pmap
[x] pmemdump
[x] printf
[ ] pro
[x] profile
[x] ps
[x] purge
[x] pwd
[x] readelf
[x] readlink
[x] realpath
[x] reboot
[x] rev
[x] rm
[x] rmdir
[ ] route
[ ] run-tests
[ ] scratch
[ ] sed
[ ] seq
[x] sha1sum
[x] sha256sum
[x] sha512sum
[x] shot
[x] shred
[x] shuf
[x] shutdown
[x] sleep
[x] sort
[x] sql
[x] stat
[x] strace
[x] strings
[ ] stty
[x] su
[ ] sync
[x] syscall
[x] sysctl
[ ] tac
[x] tail
[x] tar
[ ] tee
[ ] telws
[x] test
[ ] test-bindtodevice
[ ] test-fuzz
[ ] test-imap
[x] test-js
[ ] test-pthread
[ ] test-unveil
[ ] test_env
[x] timezone
[x] top
[x] touch
[x] tr
[x] traceroute
[x] tree
[ ] true
[x] truncate
[ ] tsort
[ ] tt
[ ] ttfdisasm
[ ] tty
[x] umount
[x] uname
[x] uniq
[x] unveil
[x] unzip
[ ] update-cpp-test-results
[x] uptime
[x] useradd
[x] userdel
[x] usermod
[x] utmpupdate
[x] w
[x] wallpaper
[ ] wasm
[x] watch
[x] which
[x] whoami
[ ] wsctl
[x] xargs
[ ] xml
[ ] xzcat
[x] yes
[x] zip

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.

Dec 19 '21 14:12 AtkinsSJ

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

Dec 19 '21 22:12 BenWiederhake

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?

Dec 20 '21 08:12 bgianfo

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.

Dec 20 '21 12:12 BenWiederhake

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.

Dec 22 '21 09:12 bgianfo

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.

Dec 22 '21 10:12 BenWiederhake

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?

Dec 22 '21 11:12 bgianfo

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.

Dec 22 '21 11:12 AtkinsSJ

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

Jun 21 '23 08:06 timschumi

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.

Jun 21 '23 12:06 AtkinsSJ

In #21014 I added a man page for pkg

Sep 18 '23 09:09 cubiclove

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.

Sep 18 '23 09:09 AtkinsSJ