Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
MAIN --help/--man should not be the same #2792
TL;DR -- Perl6 MAIN's --man should conform to Perl5 conventions and produce a full man page from any present POD docs.
In Perl 6, programs can be documented using pod in great detail, but there is no good way to provide that documentation in a clear and readable way from the command-line by default.
The builtin --help flag for MAIN produces an excellent summary of command-line flags, but the expectation for --man would be (at least from the Unix/Linux world) that it would provide a full man-page, yet it simply provides the same output.
In the Perl 5 world, the convention was typically for programs to interpret --man as a request for full POD docs using Pod::Usage, but in Perl6, this functionality difficult to replicate.
The compiler's --doc flag can produce the POD docs, but for a program with documented MAIN arguments this ends up looking like:
For arguments that, under --help would produce:
so the two are not really mutually compatible, and what one ends up wanting is a hybrid of the two, not quite what either contains.
What's needed is a --man mode where normal --help output is placed in a =head1 SYNOPSIS section and any additional sections from the same unit as MAIN are then also included.
Here is an example of what I think a program should look like, when it incorporates both sets of docs:
I would expect that the --man flag applied to that program would produce the full man page present in pod form in its body.
Tested under both 2018.10 Star (my ubuntu default) and current git rakudo master:
$ perl6-dev -v
@JJ you may have misread my bug report. This was about the handling of programs written in Perl 6, using the MAIN CLI interface to provide documentation...
One additional update for context, here's a simple example of how Perl5 programs provided both --help and --man typically: