Reuse USAGE from clap in generated man pages

[ducaale]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Clap Version

3.1.0

Describe your use case

N/A

Describe the solution you'd like

I would like clap_manpage to render the synopsis section similar to how it done in --help.

For reference, this how it looks in xh --help

USAGE:
    xh [OPTIONS] <[METHOD] URL> [--] [REQUEST_ITEM]...

And this how the synopsis is rendered in the generated manpage

SYNOPSIS
       xh  [--help]  [-V|--version]  [-j|--json]  [-f|--form] [-m|--multipart] [--raw] [--pretty] [-s|--style] [--re‐
       sponse-charset] [--response-mime] [-p|--print] [-h|--headers] [-b|--body]  [-v|--verbose]  [--all]  [-P|--his‐
       tory-print]  [-q|--quiet]  [-S|--stream]  [-o|--output]  [-d|--download]  [-c|--continue]  [--session] [--ses‐
       sion-read-only]  [-A|--auth-type]  [-a|--auth]  [--bearer]   [--ignore-netrc]   [--offline]   [--check-status]
       [-F|--follow]  [--max-redirects] [--timeout] [--proxy] [--verify] [--cert] [--cert-key] [--ssl] [--native-tls]
       [--default-scheme]  [--https]  [--http-version]   [-I|--ignore-stdin]   [--curl]   [--curl-long]   [--no-help]
       [--no-version]  [--no-json]  [--no-form]  [--no-multipart]  [--no-raw]  [--no-pretty]  [--no-style]  [--no-re‐
       sponse-charset]  [--no-response-mime]  [--no-print]  [--no-headers]  [--no-body]   [--no-verbose]   [--no-all]
       [--no-history-print]  [--no-quiet]  [--no-stream] [--no-output] [--no-download] [--no-continue] [--no-session]
       [--no-session-read-only]  [--no-auth-type]  [--no-auth]   [--no-bearer]   [--no-ignore-netrc]   [--no-offline]
       [--no-check-status]  [--no-follow]  [--no-max-redirects] [--no-timeout] [--no-proxy] [--no-verify] [--no-cert]
       [--no-cert-key] [--no-ssl] [--no-native-tls] [--no-default-scheme] [--no-https] [--no-http-version]  [--no-ig‐
       nore-stdin] [--no-curl] [--no-curl-long] <raw-method-or-url> [raw-rest-args]

Alternatives, if applicable

Fortunately, clap_mangen is flexible enough when it comes to overriding sections or adding new ones

let man = clap_mangen::Man::new(app);
let mut buf = Vec::new();
man.render_title(&mut buf).unwrap();

roff::Roff::new()
    .control("SH", ["NAME"])
    .text([roff::roman(
        "xh - Friendly and fast tool for sending HTTP requests",
    )])
    .control("SH", ["SYNOPSIS"])
    .text([roff::roman(
        "xh [OPTIONS] <[METHOD] URL> [--] [REQUEST_ITEM]...",
    )])
    .to_writer(&mut buf)
    .unwrap();

Additional Context

N/A

[epage]

This was discussed in #3174 (comment)

epage:

Hmm, looks like this is generating a usage. Ideally we would use our regular usage generator (and respect the users usage when they call override_usage).

@sondr3

If we were to use something like this we'd need to have it be more modular, the render_usage() methods output is not really usable in a manpage as is since there is no formatting and it is missing all the options.

epage:

DontCollapseArgsInUsage helps some but not all the way.

Is it recommended to not collapse anything for man pages? Seems like that could get overly verbose

Looks like we are italicizing the name but nothing else. On the other hand, there is a lot of relevant logic in our usage generator, like more thorough detection of required arguments, etc. I'm mixed on which way to go.

@sondr3

'm not sure what the preference is, git does some line splitting while fd squashes all short options together (fd [-HIEsiaLp0hV] [-d depth] and only shows the short name for options.

epage:

I guess we can stick to git's precedence for now and see how the feedback turns out

[ducaale]

Should hidden options be visible in the synopsis section or is that a bug that needs fixing?

[epage]

That is a bug.

[epage]

btw we might be able to reuse usage formatting in the future. Usage formatting also has a way to force certain arguments to show up without being required. This could offer users a way to customize things (when we make usage generation public).

So back to reusing it. Clap has some extensibility limitations around formatting. Users can't provide custom-formatted strings and can't theme clap. We've just not wanted to expose an entire formatting API in clap. If there was another formatting API we could reuse that is fully stable, then we could.

We have that, ANSI escape codes.

My idea: We could have usage generation output ansi escape codes and parse it and turn it into ROFF

Building blocks:

• Experiment with fwdansi or my own version of it and switch clap to that, allowing end-users to provide any formatting they want
• Split out the escape parsing code for reuse
• Another client of the escape parsing code would be a ROFF generator.