I am intrigued by the latest addition in ArgumentParser 1.1.3 by @rauhul
ArgumentParser now includes a SwiftPM plugin for generating man pages. Explore the functionality and configuration by running swift package plugin experimental-generate-manual --help from your package root. (#332)
When would a command-line tool author use that feature? Is there a significant difference / advantage of
man <command-line-tool> # view the generated man page
over
<command-line-tool> --help # view the generated help
Man pages have a long and strong tradition as being the primary source of documentation for a command line program, a protocol, a library function, etc.
In contrast to the usually brief help with regards to the syntax of a tool, they‘re supposed to cover much more information.
True in general. Looking at the capability to generate man pages with the new plugin from ArgumentParser, I don't think that man pages are superior. The man pages have the same content as the help for command-line tools written in Swift and using ArgumentParser.
I see the value when a command-line tool author wants to host the man page online. The generated man pages can easily be used for that purpose.
I am eager to learn about other use cases for which people think this new functionality of ArgumentParser can help.
Hosting the man page online is one use-case. Tools that show and index man pages for easier browsing and searching on device are another (e.g. the Dash docs viewer). Then there are also things like the fish shell, which can generate auto-complete data by parsing man pages and have shortcuts to show the manpage for the command you are currently typing.
Overall, man pages are simply the the standard, conventional way of providing documentation for command line tools, and sticking to that convention makes your docs more easily accessible and useful, even if they have the same content as a --help.
That said, this functionality is not really geared towards authors of command line tools. Instead, whoever creates a package (whether that be homebrew, apt, pacman, ...) would use this to include the man page in the appropriate directory in the package. Those two hats might be worn by the same person, of course.
These are great examples for use cases, thank you for sharing!
This statement is generally true. I'd like to note that the situation is currently different for command-line tools written in Swift. I checked the following popular Swift command-line tools tools and all of them have no man page: SwiftLint, SwiftFormat, Sourcery, SwiftGen, XcodeGen, Tuist, Periphery.
But this could change thanks to the new SwiftPM plugin for generating man pages :)