Give --help example of using grep on stderr of rustc

[Enselic]

It is very useful in cases like this but it is a bit tricky to figure out how to do it if you are new to using cargo-bisect-rustc.

By adding this example to --help we can make it easier for others to discover this trick.

[ehuss]

I'm wondering, have you seen the documentation at https://rust-lang.github.io/cargo-bisect-rustc/? I'm a little reluctant to add lots of examples here, since there are many different workflows. What do you think of linking to that documentation in the help instead?

[Enselic]

Thanks for taking a look at my PR.

Yep, I am aware of those docs. If strongly prefer a summary of examples in --help over being redirected to a web page with one example per page, however. So I think it's great that --help already has a couple of examples.

I think we should make it as easy as possible for casual users of cargo-bisect-rustc to use the tool. Because that means we are more likely to get help with bisecting in e.g. the context of issue triaging. The first time someone encounters the tool, I think the web documentation is probably a good entry point. But once they have used to tool a few times, they just need a brief refresher on how to use the tool. That they already have the tool installed I think is a sufficiently strong indication that they are not encountering the tool for the first time. And if they type --help, why whould we "hold back" information and force them to take one (or actually several, since the web docs are multi-paged) extra step to see some examples? Examples are a great way to quickly demonstrate usage without a user having to read the docs for each individual option and figure out how to combine them.

And I think my example is actually a great example to have in --help, because it demonstrates something non-obvious but important, namely that that you can use --script bash -- -c "..." to unlock the use of grep for bisecting. Without having to create a separate .sh-script, because that also has the downside of requiring extra steps, which unnecessarily detracts users of the tool.

[apiraino]

@Enselic I am also a great fan of offline documentation but at this time the offline docs for this tool are a bit clunky to use (see also #359). I agree that for now it's probably quicker to just update the online documentation.

But.

If your intent is to expand offline documentation, how about giving this tool a man page that replicates and expands the online help? I didn't investigate deeply but clap supports auto-generating man pages using the roff crate. Or like bat does.

Ideally a workflow that generates both offline and online help (can I dream? :slightly_smiling_face: )

[Enselic]

If your intent is to expand offline documentation

Well my intent is to make the tool easier to use by providing a useful example directly under --help. I'm not a big fan of man pages because while all installations of cargo-bisect-rustc has --help (e.g. cargo install --path . from git or simply cargo install cargo-bisect-rustc), not all installations have a man page installed. So to me it is clear that --help is the best place to put short but informative examples, because it is available to all users in a convenient way.

[Enselic]

I'll close this for now. Maybe I'll get around to update the online documentation later.