An examples section in a manpage is a fine idea which I would certainly encourage, but that wouldn't render tldr obsolete.
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.