avoid documenting examples related to: -h & --help

[mfrw]

As discussed in #6145 discussion.
Should we refrain from documenting the obvious -h & --help examples ?

[bl-ue]

+1 because --help, -h, & /? are very common. They also take up space that could be used for other examples, and at a minimum they increase cognitive load.

[marchersimon]

I think we should only include it when it's not obvious. The cases I can think of where it would make sense:

• When each subcommand has its own help
• When it's not the default -h or --help
• When you want to refer to something in the help, e.g. "List all available formatting options:"

[mfrw]

I did some quick and dirty analysis. A very crude estimate:

(tldr-root) $ rg ' \--help' | wc -l
122
(tldr-root) $ rg ' \-h' | wc -l
183

Should we start with a couple of examples and see how it goes ?

[sbrl]

I agree with @marchersimon's suggestions. Sounds like a good idea to review this, but on a case-by-case basis.

[CleanMachine1]

Here's my opinion.

Keep it, and let all future --help commands be used. However they should always be prioritised to be removed if a better example is available.

There is no harm in having it, other than making the page a little longer (3 lines)

[marchersimon]

Making the page a little longer can be problematic, since our goal is to provide as short documentation as possible.

[CleanMachine1]

Most pages already go over the default terminal size for me.
I don't know about others usage of tldr.

Its not like we document EVERY detail. Its just an easy thing to add, and could add something if someone doesn't know the --help/-h flag, if they are new to *nix

[sbrl]

I say don't actively go looking through all existing pages and removing it, but consider it on case-by-case basis as it comes up as to whether it adds any value. e.g. on the nmcli page it's valuable to indicate that it also lists all subcommands.

[CleanMachine1]

close?

[mfrw]

Yep .. if all are in agreement .. lets close this one :)