rjbs / Pod-Weaver

recombine pod documents into awesomer pod documents
26 stars 28 forks source link

It would be nice if [Pod::Weaver::Section::Collect] could optionally accept a list of "commands" to gather #54

Open tabulon opened 1 year ago

tabulon commented 1 year ago

Hi,

I sometimes find myself wanting to gather several "command" variants under the same POD section heading via Pod::Weaver::Section::Collect, along the following lines :


[Collect / OPTIONS]
command = opt
command = option

[Collect / ATTRIBUTES]
command = has
command = attr
command = attribute

[Collect / FUNCTIONS]
command = func
command = function

(In my case, this stuff happens in perl code within a Pod::Weaver::PluginBundle but that's besides the point. The above INI example should get the point accross).

In the end, such "commands" boil down to mere conventions -- either between a bunch [of people] or the same person across time.

Sure, it would be nice to be able to harmonize on one "command" for each purpose, but the reality is there are several such conventions out there, most quite similar in spirit, and the same author can easily end up maintaining or contributing to modules that follow differing conventions...

It would just reduce needless mental burden if a Pod::Weaver::PluginBundle could accept various "command" alternatives and happily churn the correspnding section.

Currently, trying to pass multiple values for "command" gives an error:

multiple values given for property command in section @Author/***/Options at /usr/local/opt/perl/lib/perl5/site_perl/5.36/Config/MVP/Assembler/WithBundles.pm line 152.

Trying to cheat by defining the same section multiple times doesn't work either:

already have a section named @Author/***/Options at /usr/local/opt/perl/lib/perl5/site_perl/5.36/Config/MVP/Sequence.pm line 97.
    Config::MVP::Sequence::add_section(Config::MVP::Sequence=HASH(0x7faa2e455f68), Config::MVP::Section=HASH(0x7faa252cfd68)) called at ...

If you point me in the right direction, especially for insuring backwards compatibility, I would try to submit a fix.