Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
ajs opened this issue Mar 24, 2019 · 3 comments

Comments

Projects
None yet
3 participants
@ajs
Copy link

commented Mar 24, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Mar 24, 2019

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

This comment has been minimized.

Copy link
Author

commented Mar 24, 2019

@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

This comment has been minimized.

Copy link
Contributor

commented Mar 24, 2019

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

@lucasbuchala lucasbuchala added the CLI label Mar 24, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.