zonemaster
Inconsistent CLI options documentation
The command line options are documented in two different ways. The two different documentations can be show with the commands zonemaster-cli --help and perldoc zonemaster-cli respectively. Both commands should output the same documentation.
The top part of man zonemaster-cli (options) is more or less identical to zonemaster-cli --help, but not completely:
- They are presented in different ways.
manis in English only,--helpis partly translated.- Some options are mentioned in
helponly, such as--configand--sourceaddr.
Make those to be identical by just defining it once. In the implementation the man page comes from the script zonemaster-cli and the help comes from CLI.pm.
The is an option --usage which gives the same as --help. Confusing.
@vlevigneron, I have failed to find a good solution on this. Can you take a look at it?
le 29 Jul, Mats Dufberg a ?crit :
@vlevigneron, I have failed to find a good solution on this. Can you take a look at it?
OK, but before that, I will fix (and merge if revewed with success) the following issues :
zonemaster/zonemaster-cli#145 zonemaster/zonemaster-cli#159 zonemaster/zonemaster-cli#160
-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/zonemaster/zonemaster-cli/issues/68#issuecomment-889214586
-- Vincent Levigneron A.F.N.I.C. @.***
I see that @matsduf and I have no idea how to fix zonemaster/zonemaster-cli#160. What we see is what is expected from MooseX::Getopt. I found no way to change that behaviour in the doocumentation.
Could we migrate from MooseX::Getopt? It works for very few options but not for the Zonemaster use case.
Everything is possible but it would be a complete rewrite of zonemaster-cli/lib/Zonemaster/CLI.pm.
I have struggled to make MooseX::Getopt not print out, but I have failed. Is it possible to create a "catch all" option and then let that print an error message and use "perldoc zonemaster-cli" for the documentation?
I guess I found something. I'll create a PR today, you'll see if it is an acceptable workaround.
Would it be acceptable to drop the translation of the help output? I would say yes definitely. Do you guys agree?
Would it be acceptable to drop the translation of the help output?
Is that the equivalent to "man zonemaster-cli" or do you mean all output?
$ zonemaster-cli --locale sv_SE.UTF-8
Måste ange namnet på en domän att testa.
$ zonemaster-cli
Must give the name of a domain to test.
If you only mean the equivalent of "man zonemaster-cli" I think it is OK.
Would it be acceptable to drop the translation of the help output?
This sounds reasonable to me. However, and I don't know how feasible it is, since it seems we have translations for zonemaster-cli --help, can't we use the translations for the man pages? Or are they using different part of the code, so translating the man page is a job on its own?
My idea was to switch approaches and do what I usually do for documentation of CLI tools. I.e. to specify the options using Getopt::Long, document them in POD and perform the usage output with Pod::Usage. All of these are included in the Perl Core, so we could probably drop CLI's dependency on Moose that way. And the end result would be rather nice for both users and maintainers. Except for users who really need the usage translations, of course. So I guess the question is how important this feature is.
If we must have the usage translations we'll have to come up with a new approach. Because Gettext doesn't work for POD. At least not as far as I know.
I think it is nice to have all output translatable, but it would be acceptable to have the output from "--help" in English only. Other output we should keep translatable.
It is a question of resources and priorities.