required options don't get noted as required in the generated manpage/docs

[ihodes]

e.g. in hammerlab/epidisco

$ begin
       pure (fun s -> `Experiment_name s)
       $ Arg.(
           required & opt (some string) None
           & info ["experiment-name"; "E"]
             ~doc:"Give a name to the run(s)" ~docv:"NAME")
     end

And yet it is rendered as

OPTIONS
[...]
       -E NAME, --experiment-name=NAME
           Give a name to the run(s)

and

SYNOPSIS
       ./cocosubmit.native [OPTION]...

[dbuenzli]

Required optional arguments are a contradiction in the terms. You should rather use positional arguments for required arguments.

[ihodes]

After two or three, positional arguments are difficult to read. We have many required args in this application. We also want to disambiguate some arguments (e.g. the type of --normal, --tumor, --rna are all exactly the same, and we want to make sure that the value the user is passing is associated with the key they intend). It's also nice to be able to reorder args.

[dbuenzli]

After two or three, positional arguments are difficult to read.

My guess is that you'll soon end up with a configuration file or dsl. In any case ded2040 now indicates required optional in the documentation of options. As far as synopses are concerned this should be solved in conjunction with #42 so I'm tracking this there.

[ihodes]

My guess is that you'll soon end up with a configuration file or dsl.

Something we're desperately trying to avoid, but ending up with a CLI DSL anyway… there is no escaping that.

Thank you for the addition, and looking forward to seeing what comes out of that issue as well.

[dbuenzli]

Thank you for the addition, and looking forward to seeing what comes out of that issue as well.

Note that I'm not sure this will make it in the next release, but you can always define the SYNOPSIS version yourself if needed, it will replace the auto generated one (but that won't do it for the usage error message).