Any command/tool to show example of a command

Question

man often doesn't contain the example of a command, or very little.

Such as scp:

NAME
     scp — secure copy (remote file copy program)

SYNOPSIS
     scp [-12346BCpqrv] [-c cipher] [-F ssh_config] [-i identity_file] [-l limit] [-o ssh_option] [-P port]
         [-S program] [[user@]host1:]file1 ... [[user@]host2:]file2

This is hard to understand where to put source file and destination file, same as documents like this.

It is very clear and easy understand with an example and some description:

scp -r  user@source_machine:/user/Desktop user@remote_machine:/path/foo

And as zip:

NAME
       zip - package and compress (archive) files

SYNOPSIS
       zip  [-aABcdDeEfFghjklLmoqrRSTuvVwXyz!@$]  [--longoption  ...]  [-b path] [-n suffixes] [-t date] [-tt
       date] [zipfile [file ...]]  [-xi list]

Thanks it has exmaple zip -r foo.zip foo

The normal way I think is zip A into B, [zipfile [file ...]] maybe saying you can pack zipfile with other files too(on no-native speaker vision). Only the example can make that clear.

So I wonder if there is a command or tool can show me the example of a command.

Answer 1

Quite a long time, and I found some solutions:

tldr

• need: npm
• url: https://github.com/tldr-pages/tldr
• command: tldr tar

PS: tldr support many clients (check readme on above repo). Especially the go client can work offline and provide all platform binaries : https://github.com/leighmcculloch/tldr/

cheat

• need: python
• url: https://github.com/chrisallenlane/cheat
• command: cheat tar

eg

• need: python
• url: https://github.com/srsudar/eg
• command: eg tar

Answer 2

Unfortunately,no.

Documentation is up to the developers, so it is their responsibility to include examples into man pages. Sometimes they do, sometimes they do not. For instance , find command has very lovely and extensive EXAMPLES section in its man page.

Tools for providing examples would be handy, but since there are millions of commands/programs for Ubuntu and Linux in general, developing such tool would be a considerable effort, on the level of Sisyphus. Simple approach is just search online for usage examples of whatever program you are trying to run. Books are also very handy resource. Many of books on Linux, Unix, shell scripting, etc - they provide lots of examples and more importantly usage context for those commands.

If you believe that the manual page for a particular tool should contain (more) examples, please file a bug report with its maintainers or developers on Launchpad or “upstream” or, better yet, submit a patch that adds these examples.