Bug #75056 for Module-Build: Generated Build script should provide a '--help' option as alias to the 'help' action

Thu Feb 16 04:57:48 2012 EDAVIS [...] cpan.org - Ticket created

Subject:

Generated Build script should have help message

In a distribution that uses Module::Build, when you run 'perl Build.PL' it generates a Build executable, but it's not clear how to use that: % ./Build --help Building File-Temp % ./Build install --help !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ERROR: Can't create '/usr/share/man/man3' Do not have write permissions on '/usr/share/man/man3' !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! at /usr/share/perl5/Module/Build/Base.pm line 3569 The Build program should provide a basic usage message, or if no options are accepted, it should give a message for that. (And unknown options should be an error rather than ignored.)

Thu Feb 16 06:36:59 2012 LEONT [...] cpan.org - Correspondence added

On Thu Feb 16 04:57:48 2012, EDAVIS wrote: Show quoted text

> In a distribution that uses Module::Build, when you run 'perl Build.PL' > it generates a Build executable, but it's not clear how to use that: > > % ./Build --help > Building File-Temp > % ./Build install --help > !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! > ERROR: Can't create '/usr/share/man/man3' > Do not have write permissions on '/usr/share/man/man3' > !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! > at /usr/share/perl5/Module/Build/Base.pm line 3569 > > The Build program should provide a basic usage message,

You're looking for the help action (mentioned in the Module::Build perldoc): ./Build help ./Build help install Show quoted text

> or if no options > are accepted, it should give a message for that. (And unknown options > should be an error rather than ignored.)

Yeah. Module::Build's argument handling is rather messy. Leon

Thu Feb 16 06:37:01 2012 The RT System itself - Status changed from 'new' to 'open'

Thu Feb 16 06:37:22 2012 LEONT [...] cpan.org - Severity Unimportant changed to Wishlist

Thu Feb 16 18:29:38 2012 schwern [...] pobox.com - Correspondence added

Subject:	Re: [rt.cpan.org #75056] Generated Build script should have help message
Date:	Thu, 16 Feb 2012 15:29:19 -0800
To:	bug-Module-Build [...] rt.cpan.org
From:	Michael G Schwern <schwern [...] pobox.com>

On 2012.2.16 3:37 AM, Leon Timmermans via RT wrote: Show quoted text

>> % ./Build --help >> Building File-Temp >> % ./Build install --help >> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! >> ERROR: Can't create '/usr/share/man/man3' >> Do not have write permissions on '/usr/share/man/man3' >> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! >> at /usr/share/perl5/Module/Build/Base.pm line 3569 >> >> The Build program should provide a basic usage message,

> > You're looking for the help action (mentioned in the Module::Build perldoc):

I'm all for making --help do something useful. It's a pretty common command line convention. ./Build --help # same as ./Build help ./Build <action> --help # same as ./Build help <action>

Thu Feb 16 18:31:28 2012 dagolden [...] cpan.org - Subject changed from 'Generated Build script should have help message' to 'Generated Build script should provide a '--help' option as alias to the 'help' action'

Mon Feb 20 06:00:23 2012 LEONT [...] cpan.org - Correspondence added

On Thu Feb 16 18:29:38 2012, schwern@pobox.com wrote: Show quoted text

> I'm all for making --help do something useful. It's a pretty common > command > line convention. > > ./Build --help # same as ./Build help > ./Build <action> --help # same as ./Build help <action>

I think I actually rather like it. The help action is rather unusual in taking a non-option argument, I think it's the only action doing so. From a symmetry point of view, making it an option instead of an action would make sense. The only complication is how to distinguish the overview-help (./Build help) from the build help (./Build help build). Both could be mapped to ./Build --help. Leon

Mon Feb 20 19:43:52 2012 schwern [...] pobox.com - Correspondence added

Subject:	Re: [rt.cpan.org #75056] Generated Build script should provide a '--help' option as alias to the 'help' action
Date:	Mon, 20 Feb 2012 16:43:42 -0800
To:	bug-Module-Build [...] rt.cpan.org
From:	Michael G Schwern <schwern [...] pobox.com>

On 2012.2.20 3:00 AM, Leon Timmermans via RT wrote: Show quoted text

> The only complication is how to distinguish the overview-help (./Build > help) from the build help (./Build help build). Both could be mapped to > ./Build --help.

"Build --help" provides the overview and a pointer to "Build build --help". "Build build --help" provides help about the build action. Proof by contradiction... "Build --help" is one of the more likely ways a user is going to look for command line help. If "Build --help" showed the build action help, and "Build build --help" did as well, where do we put the help overview that the user will find it? "Build help --help"? The user won't think of that. The build action help would have to point at the help action help. As the build action help is obviously not what they wanted, the user is likely to dismiss it without reading it and thus miss the help overview instructions. -- On error resume stupid