Skip to content

Redundant help and version options in generated man page #799

@scriptingosx

Description

@scriptingosx

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

  • If possible, I've reproduced the issue using the main branch of this package
  • 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions