Generally agree that augmenting existing man pages is then way to go. However, using a new number to categorize "use cases" or "examples" is probably incorrect.

Generally agree that augmenting existing man pages is then way to go. However, using a new number to categorize "use cases" or "examples" is probably incorrect. man page categories (1, 2, 3, etc.) are organized by type of command. See: http://www.schweikhardt.net/man_page_howto.html#q2 http://www.schweikhardt.net/man_page_howto.html#q2 Reviewing the convention for man pages, it seems like adding an EXAMPLES section to existing man pages is the correct way to augment the documentation. Definitely support your position that improving existing documentation is the way to go. Just wanted to share my research on how man pages are supposed to work.