MAIN --help/--man should not be the same

[ajs]

The Problem

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:

class Mu $
Length of results

For arguments that, under --help would produce:

--length=<Int>       Length of results

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:

https://github.com/ajs/tools/blob/dd4ac2e1502995345df8fef9d653abbb751567a4/math/searchmul.p6

I would expect that the --man flag applied to that program would produce the full man page present in pod form in its body.

Environment

• Operating system: any
• Compiler version (perl6 -v):

Tested under both 2018.10 Star (my ubuntu default) and current git rakudo master:

$ perl6-dev -v
This is Rakudo version 2019.03.1-114-g888cf8cdc built on MoarVM version 2019.03-44-g079d67002
implementing Perl 6.d.
$ perl6 -v
This is Rakudo Star version 2018.10 built on MoarVM version 2018.10

[JJ]

As a matter of fact, there are not a lot of POD documents included in Rakudo, and the documentation is not installed by default.

[ajs]

@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:

https://github.com/ajs/tools/blob/master/math/mkprime

[JJ]

Right, I thought you were talking about perl6 --man. Sorry!