[Bioperl-l] bugtracker for Dist::Zilla::PluginBundle::BioPerl

[Carnë Draug]

On 25 March 2013 16:23, George Hartzell <hartzell at alerce.com> wrote:
> You might make the SYNOPSIS just a tad less confusing if you point
> some meaningful text into the text sections of the GenerateSection
> parts, something like "text = Info about mailing lists goes here".

I don't understand your suggestion. Could you explain it again please?

> I
> scratched my head a bit wondering why "FEEDBACK" had nothing, "Mailing
> lists" had an empty attribute and the other two had nonsense text.  It
> looks like FEEDBACK is just an empty level 1 header, but
> otherwise....

It's not empty. Feedback is level 1, which contains three level 2
headings for mailing list, support and reporting bugs. The code being
generated should match exactly the feedback section of all current
BioPerl modules. See the feedback section of the Bio::DB::BiblioI that
I recently released with this set up:

https://metacpan.org/module/Bio::DB::BiblioI#FEEDBACK

and compare with the old release of Bio::SeqIO

https://metacpan.org/module/Bio::SeqIO#FEEDBACK

> I can see that being useful. In the name, did you mean "interpolated"
> (which you use further down) where you say "interpreted"?

Yes, that's what I meant. I have just pushed the fix, thank you.

On 25 March 2013 16:46, Fields, Christopher J <cjfields at illinois.edu> wrote:
> On Mar 25, 2013, at 11:23 AM, George Hartzell <hartzell at alerce.com> wrote:
>
>> Carnë Draug writes:
>>> [...]
>>> So I wrote Pod::Weaver::PluginBundle::BioPerl to be used with
>>> Dist::Zilla::PluginBundle::BioPerl. Would be nice if someone could
>>> give some feedback if it's adequate for the rest of the project.
>>>
>>> https://github.com/bioperl/dist-zilla-pluginbundle-bioperl/blob/master/lib/Pod/Weaver/PluginBundle/BioPerl.pm
>>
>> Looks wonderful!
>>
>> I use a "private" section that I think corresponds to what you call
>> "internal".  Is there a BioPerl tradition one way or the other?
>
> Not really, but there probably should be a more standard way of doing this.

I think the large majority of the modules have a head1 APPENDIX that
says "Internal methods are usually preceded with a _" which contained
each method and attribute by the same order they appear on the code
inside a head2. I just followed the name that was already there
"internal", but it's very easy to change. At the moment, what I set up
recognizes the following:

=attr (for attributes)
=method
=func (for functions)
=internal (internal methods)

It doesn't matter the order they appear on the source, PodWeaver will
group and reorder them. It is easy to change the keywords, and add or
remove the groups. Just let me know what the bundle should be doing.
Take a look at

https://github.com/bioperl/Bio-Biblio/blob/master/lib/Bio/DB/BiblioI.pm

which generates

https://metacpan.org/module/Bio::DB::BiblioI

>>> https://metacpan.org/module/Pod::Weaver::Section::GenerateSection
>>
>> [...]
>>
>> This is a useful contribution!
>>
>
> Yes, agreed.  The original purpose of the BioPerl Dist::Zilla bundle (set up during GSoC a few years ago by Sheena) was to make releases easier and more consistent across independent dists if need be; if configuring and using Pod::Weaver simplifies boilerplate and makes documentatio easier I'm all for it.

I wrote another plugin the day after to generate the legal section
which is mainly aimed at BioPerl and distributions with many modules,
where the authors and copyright owners are not always the same. It
takes the copyright information from a block of comments in each
source file.

https://metacpan.org/module/Pod::Weaver::Section::Legal::Complicated

And yesterday the contributors plugin was released again after also
implementing the option to find the names of contributors in the
source of individual files

https://metacpan.org/module/Pod::Weaver::Section::Contributors

I can easily make the changes on our pluginbundles, or write new ones.
And authors from other packages are usually happy to receive patches
so it's also easy to expand on the ones that already exist. The only
problem left is defining what a BioPerl POD should look like. The pod
weaver pluginbundle as it is now, is just what looked appropriate to
me. But would be great if someone could comment on it so adjustments
to it can be made.

Carnë