Before replying on your points, a correction: the line saying "The main reason is that it's so long to be basically unreadable." wasn't related only to the program's description, but to the whole output, sorry for the confusion.
As for the rest: > Man pages are not always installed by people, and a help page should > be able to explain the bare minimum. In my opinion, if people don't install man pages and then need them, it's their own fault if then they don't know what to do. Of course, if the OS doesn't come shipped with them it's not the user's fault, but it still doesn't mean the description of the flag has to be a full paragraph. I believe simply listing the accepted formats is enough, e.g. "Format output according to FORMAT. Accepted placeholders: %j %l %f %u %n" That way people that know what they mean can see the full range of accepted values — for example to make sure they are not adding useless modifiers — without having to scan a long piece of text, while people that don't know, either read the documentation somehow or experiment using the listed letters. > However, since when not specified --dir-printf defaults to --printf, a > mention of --printf will always be there in a way or another. Of course, I was mostly referring to the fact that explaining the purpose of a flag _only_ as "works like <another flag>" without providing any other explanation doesn't really make for a great experience. Writing something like: "Format output according to FORMAT. Accepted placeholders: %j %l %f %u %n Defaults to the value of --printf when omitted" is perfectly fine. Regarding the man page, I believe you should add a dedicated section before "EXAMPLES" where you describe all the formatting modifiers. If you put them right under the flag, not only you duplicate shared values, but it becomes hard to check the available flags since the page becomes unnecessarily long. Of course, there are plenty of other programs out there with a lot of flags and with very long descriptions, so scrolling for screenfuls becomes the norm, but most of the time it's the actual behaviour that needs to be explained at length. In this case, the flags are very simple in what they do, so I believe having formatting rules be in a dedicated section is the best course of action. These are my opinions as someone who can never remember the accepted flags or how they work, and thus need to run programs with `--help' or open up the manual before actually running the program. Thanks, A.V.
