optparse-applicative subcommand help text

Question

I'm using optparse-applicative that comes with stackage lts 5.1 I have a parser with subcommands and I have described a help text for their options, but they don't show.

This is the output when I run the executable with --help :

[david@devcentos65 manipro]$ /home/david/.local/bin/manipro --help
manipro - text1

Usage: manipro COMMAND [-v|--verbose]   text2

Available options:  
  -h,--help                Show this help text  
  -v,--verbose             text3

Available commands:   
  export                   text4
  dico                     text9

The code :

parserArgs :: ParserInfo ArgApp
parserArgs = info (helper <*> args) desc
    where
    desc =  
        fullDesc <> 
        progDesc "text1"  <> 
        header "text2"


args = ArgApp <$> argCmd <*> optverbose
    where
    optverbose = switch ( 
        short 'v' <> long "verbose" <> 
        help "text3" )

argCmd = subparser (argCmdExport <> argCmdDico)

argCmdExport = command "export" infos
    where
    infos = info options desc
    desc  = progDesc "text4" 
    options = ArgCmdExport <$> 
        argModeExport <*> 
        argTableExport <*> 
        argOptExport

argModeExport  = argument auto (metavar "FORMAT")
argTableExport = argument text (metavar "TABLE")

argOptExport = ArgOptExport <$> optional noesc <*> optional cols <*>
    ens <*> tst
    where
    noesc = option textList (long "noesc" <> metavar "CHAMPS" <> help "text5" )
    cols = option textList (long "cols" <> metavar "CHAMPS" <> help "text6" )
    ens = flag EnsEtoile  EnsDollar (short 'd' <> long "dollar" <> 
        help "text7") 
    tst = flag False True (short 't' <> long "test" <> 
        help "text8")

argCmdDico    = command "dico" infos
    where
    infos = info options desc
    desc  = progDesc "text9" 
    options = ArgCmdDico <$> 
        argOptDico

argOptDico = ArgOptDico <$> optional tables
    where
    tables = option textList (long "tables" <> metavar "TABLES" <>
        help "text10" )


text = str >>= return . pack
textList = str >>= return . splitOn "," . pack

Answer 1

optparse-applicative hides the detailed description of a command deliberately if you only use --help. After all, you might have a dozen commands. For example, stack has 34. Listing probably fills your terminal vertically. If it displayed all possible arguments, you would end up with a lot of text.

Instead, --help will only show the common arguments and a list of commands. In order to show the description of a single command, you have to use <executable> <command> --help:

$ stack --help | head
stack - The Haskell Tool Stack

Usage: stack [--help] [--version] [--numeric-version] [--docker*] [--nix*]
             ([--verbosity VERBOSITY] | [-v|--verbose]) [--work-dir WORK-DIR]
             [--[no-]system-ghc] [--[no-]install-ghc] [--arch ARCH] [--os OS]
             [--ghc-variant VARIANT] [-j|--jobs JOBS] [--extra-include-dirs DIR]
             [--extra-lib-dirs DIR] [--[no-]skip-ghc-check] [--[no-]skip-msys]
             [--local-bin-path DIR] [--[no-]modify-code-page]
             [--resolver RESOLVER] [--compiler COMPILER] [--[no-]terminal]
             [--stack-yaml STACK-YAML] COMMAND|FILE

$ stack --help | grep clean
  clean                    Clean the local packages

$ stack clean --help
Usage: stack clean [PACKAGE] [--help]
  Clean the local packages

Available options:
  PACKAGE                  If none specified, clean all local packages
  --help                   Show this help text

Run 'stack --help' for global options that apply to all subcommands.

This reduces the clutter somewhat. It also follows the same rules as other popular multi-command applications, such as git and hg (with the small exception that <executable> --help <command> will still show only the general help).

Answer 2

As Zeta points out, the description of a single command is shown on <executable> <command> --help. But for this to work, in optparse-applicative a parser for the option --help is needed for every command's subparser. You've only defined one for <executable> --help (see second line of your haskell code block). Without a help-parser for a specific command the output of <executable> <command> --help will be no help message, but a notification about an invalid option --help and a usage note.

The general pattern would be to sequentially applicate the parser for the --help option, i.e. helper, to the parser for your command's arguments, like so: command "command-name" (info (yourCommandArgParser <**> helper) (fullDesc <> progDesc "your commands description" <> ...)).

So for the export command you could write:

argCmdExport = command "export" infos
    where
    infos = info (options <**> helper) desc
    desc  = progDesc "text4" 
    options = ArgCmdExport <$> 
        argModeExport <*> 
        argTableExport <*> 
        argOptExport

PS. The question is old, but I stumbled over it, when I had the same problem. And there is still nothing about it on the web.