[SaulOfTheJungle]

> No, they serve two different purposes.

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.

[fhennig]

Yes, put both things in the man page!

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!