swift-argument-parser icon indicating copy to clipboard operation
swift-argument-parser copied to clipboard

Redundant help and version options in generated man page

Open scriptingosx opened this issue 6 months ago • 0 comments

When generating a man page with the generate-manual plug-in, the top-level --help and --version options get repeated for every subcommand.

This might make sense for the --help display and the completion output, but in the man page, it is very redundant and distracting.

Example, from my utiluti tool:

UTILUTI(1)                  General Commands Manual                 UTILUTI(1)

NAME
     utiluti – Read and set default URL scheme and file type handlers.

SYNOPSIS
     utiluti subcommand [--version] [--help]

DESCRIPTION
     --version
             Show the version.

     -h, --help
             Show help information.

     url     Manipulate default URL scheme handlers

             --version
                     Show the version.

             -h, --help
                     Show help information.

             get     Get the path to the default application.

                     scheme  the url scheme, e.g. 'http' or 'mailto'

                     --bundle-id
                             list bundle identifiers instead of paths

                     --version
                             Show the version.

                     -h, --help
                             Show help information.

             list    List all applications that can handle this URL scheme.

                     scheme  the url scheme, e.g. 'http' or 'mailto'

                     --bundle-id
                             list bundle identifiers instead of paths

                     --version
                             Show the version.

                     -h, --help
                             Show help information.

             set     Set the default app for this URL scheme.

                     scheme  the url scheme, e.g. 'http' or 'mailto'

                     bundleID
                             bundle identifier for the app

                     --version
                             Show the version.

ArgumentParser version: 1.6.1 Swift version:

swift-driver version: 1.120.5 Apple Swift version 6.1.2 (swiftlang-6.1.2.1.2 clang-1700.0.13.5)
Target: arm64-apple-macosx15.0

Checklist

  • [x] If possible, I've reproduced the issue using the main branch of this package
  • [x] I've searched for existing GitHub issues

Steps to Reproduce

  • Create a ParsableCommand with subcommands and a version.
  • use generate-manual plugin
  • view the generated man page with
man -M .build/plugins/GenerateManual/outputs/<commandName>/: <commandName>

Expected behavior

The --version and -h, --help options should be shown once, at the top level and not be repeated for every subcommand.

At least there should be a way to mark them as global, so they are not repeated.

Actual behavior

The --version and -h, --help options are repeated for every sub level.

scriptingosx avatar Aug 01 '25 07:08 scriptingosx