Make usage documentation consistent and also demoose

[mattias-p]

Purpose

This PR kills two birds with one stone:

• It fixes the discrepancy between perldoc zonemaster-cli and zonemaster-cli --help, and
• it migrates away from Moose and Moosex::Getopt::GLD.

Context

• Fixes Inconsistent CLI options documentation #68.
• I've tried to keep this PR conservative with regards to improving the actual help text. I have a lot of improvements in mind but I'm deferring them to one or more followup PRs. See Organize --help text #389.

Changes

Application:

• Instead of using Moose and Moosex::Getopt::GLD we now Getopt::Long and Pod::Usage which are both Perl core modules.
• I merged the best parts of the --help and perldoc usage texts. As I worked through them I realized there was a lot of room for further improvement. I tried to be conservative making improvements but in some cases I couldn't help myself.

Tests:

• A unit test is added to make sure --help work.
• A unit test is added to make sure all POD is syntactically correct.

Documentation:

• The --help text is longer now and formatted differently. This because we're using a different method of generating it and the details are taken from POD instead of Moose attributes.

Reviewing this PR

• Inspect the help text and man page of both this branch and the develop branch looking details that have gone missing.

Testing this PR

• Unit tests should pass.
• Perform a limited amount of exploratory testing for edge cases like missing required arguments, unknown options, invalid arguments, or conflicting flags.

[matsduf]

I guess .travis.yml should also be updated to match the update. The installation instruction also needs an update.

[mattias-p]

I've split out #381 from this PR and rebased this one on top of that one.

[matsduf]

The man page starts with

zonemaster-cli --test=delegation/delegation01 --level=debug zonemaster.net

The easier and preferred format is

zonemaster-cli --test=delegation01 --level=debug zonemaster.net

[matsduf]

zonemaster-cli -h gives brief information now, and that is fine, but I do not get any information on how to get full information. zonemaster-cli --help gives brief information. Is it possible to give it paged like a man page? perldoc Zonemaster::CLI gives no information. Maybe refer to man zonemaster-cli and zonemaster-cli --help?

[matsduf]

I think zonemaster-cli with no argument should refer to some documentation like "--help".

[matsduf]

zonemaster-cli --help gives less information than man zonemaster-cli. Preferably it should be the same, or the former refer to the latter. The man page comes from the script. Couldn't --help extract the POD from the script and show that paged? I know that is possible to achieve.

[mattias-p]

The man page starts with

zonemaster-cli --test=delegation/delegation01 --level=debug zonemaster.net

The easier and preferred format is

zonemaster-cli --test=delegation01 --level=debug zonemaster.net

As I state in the PR description I'm deferring all improvements to the text. If you look at #389 you'll see that I update the SYNOPSIS section so that it declares the command line syntax instead of just a selection of examples.

[matsduf]

@mattias-p, please look at issue #388. I think you are behind that code.

[mattias-p]

@matsduf As you discovered I had forgotten to implement the --help aliases. I've force-pushed implementation and automatic test for that. Please review again.

[marc-vanderwal]

Looks good to me.

[marc-vanderwal]

Release testing for 2024.2: I have some remarks, but there are no show-stoppers.

What works:

• zonemaster-cli --json-stream --no-json is rejected, as it should;
• zonemaster-cli --json-translate without --json nor --json-stream gives a deprecation warning and a warning that --json-stream has no effect;
• invalid values for --level and --stop-level are rejected;
• erroneous values for --ns or --ds (that do not respect the prescribed syntax) are rejected.

But there are some things worth looking at:

• A command line such as zonemaster-cli --help --list-tests --version --dump-profile doesn’t make much sense; maybe these four options should be all made mutually exclusive to each other?
• In the synopsis, one line says zonemaster-cli [OPTIONS] --dump-profile. Except from --profile=FILE, are there any other options that could make sense when combined with --dump-profile? For example, zonemaster-cli --dump-profile --no-json still gives me JSON output because --no-json is not applicable to the output caused by --dump-profile.
• The error messages displayed on erroneous values for --level and --stop-level are inconsistent:

$ zonemaster-cli --stop-level=INVALID
Failed to recognize stop level 'INVALID'.
$ zonemaster-cli --level=INVALID
--level must be one of CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, DEBUG2 or DEBUG3.

[matsduf]

@marc-vanderwal wrote:

• In the synopsis, one line says zonemaster-cli [OPTIONS] --dump-profile. Except from --profile=FILE, are there any other options that could make sense when combined with --dump-profile? For example, zonemaster-cli --dump-profile --no-json still gives me JSON output because --no-json is not applicable to the output caused by --dump-profile.

My comment:

I guess it would make sense to combine --profile FILE with --dump-profile.

[matsduf]

@marc-vanderwal, will you create an issue or a PR of your findings?

[marc-vanderwal]

I guess it would make sense to combine --profile FILE with --dump-profile.

Yes, I agree that it makes sense; you just end up dumping the profile from FILE.

@marc-vanderwal, will you create an issue or a PR of your findings?

I’ve created issue #403.

[matsduf]

Yes, I agree that it makes sense; you just end up dumping the profile from FILE.

Not necessarily. File could contains just one property, e.g. no_network, and then you should get the resulting profile with --dump-profile.

I’ve created issue #403.

Great.