I see a lot of people talking about examples, and while having more of them could be good, I think the actual problem with most modern man pages is a lack of cl

I see a lot of people talking about examples, and while having more of them could be good, I think the actual problem with most modern man pages is a lack of clear description of program behaviour. I am nowhere near old enough to have used an old Unix implementation, but the man pages back in those days just hit different. just compare how the ls man page starts for the GNU and Unix V7 version. GNU: "List information about the FILEs" Unix V7: "For each directory argument, ls lists the contents of the directory; for each file argument, ls repeats its name and any other information requested." The GNU man page's description continues with one sentence on default ordering before getting to the list of arguments. The only mention ls lists diretory contents is in the description of the -d flag (the flag to make it not do that). The GNU man page also goes on in detail avout the time formats supported by the command, but nowhere does it have anything to say about the format of -l info. Trying to read modern man pages is like trying to read a library documentation where only the parameteres and return values for function are documented, but no description of the function in itself is given.