Many man pages contain examples and common usages. See for example the rsync man page, with complete examples of how to backup common file systems.
An examples section in a manpage is a fine idea which I would certainly encourage, but that wouldn't render tldr obsolete.
It might not be crazy to move the examples section to the top, since it would more quickly provide what most readers are looking for: a sample command line to tweak. Anyone who is genuinely looking for what a particular flag does is just going to search for it anyway, so it doesn't really matter if that flag appears on the 24th screen instead of the 23rd.
I know you can disable the pager for man, but the typical manpage is going to be fairly long anyway so the pager is generally desired. I suppose you could pipe man through head to just print out the first section, but honestly tldr seems to fill this niche better than I see that working.
In fact, having pages I don't need just causes confusion.
Moreover, commands can have system specific names.
Also my tdlr-pages checkout is only 19MB, so I'm not too concerned about bloat. I'm not really sure how having tldr's for irrelevant commands would be a problem, maybe with some shell autocompletions? Maybe there is a way you could prune the tldr-pages checkout?
I guess all I can really say is tldr works really well for me and I like it a lot. Nothing is perfect, but tldr is quite nice despite some warts.
I agree, but I'm also painfully aware of man page incompleteness every time I'm on a non-OpenBSD system. I'd be grateful to anyone who chipped away at proper tagging for any GNU software. One should be able to :t to jump to the reference for any flag.
For tagging, the formatting would need to be redone to be mdoc, which breaks both the OSes mentioned above and would be an immensely arduous task at this point. Probably not going to happen.
Note GNU and and the Linux man-pages project are mostly outliers; everyone else that lives in BSD/illumos land has long since moved on to mdoc since like the 80s. See also https://www.usenix.org/system/files/login/articles/141-dzons...
Sudo supports such systems even though its manuals are written in mdoc.
The source tarball contains both the original mdoc manuals and man manuals, autogenerated by mandoc (https://mandoc.bsd.lv) which can convert mdoc to man—easy to do, since mdoc is a semantic format.
Then at build time one format or the other will be installed depending on how capable the system manpage formatter is.
Any project using mdoc pages could do the same thing. Projects using autotools could even copy Sudo’s autoconf macros for this.
Also, a gentle, human oriented intro can be a part of man page I think.
I don't see why they could not serve both purposes.
Man pages should start with a tldr section followed by the full reference/spec.
Looking at some examples of tldrs, it mostly boils down to the most common use cases as examples. So well written man pages already have an "examples" section, and that really helps!
Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept.
This is something different. It's a tutorial of how to do the most common things using that tool.
It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples?
Unless you've read formal specs for other languages with a similar paradigm before, it's way easier to learn from examples first, which gets you to the level of understanding where the formal specs start to make sense.
Improvements to man pages should be made, but not at the cost of beginner-friendly projects.