byterock

Just when you think the Dist::Zilla is gone, I am going to go back to the Dist-Pen for the next few posts.

I could just spend the next thirty posts or so writing up a new POD each day and posting the results here. I wouldn't learn anything though, I alreay know how to write POD, and I am sure I would loose any readers I might of gained over the last few weeks. So I think I will spare us that and instead re-visit Dist-Zilla today.

I am going to re-vist how I am using [PodWeaver] plugin, as I am facing some thirty POD files that will have a good deal of boiler plate in them and I would like to have some things just done for me.

To investigate how Pod::Weaver works I created only a single POD today 'Manual.pod' with just this in it

=pod

=head1 Database::Accessor is not an ORM

=cut 

and then gave good old 'dzil build' a go to see what I get

...

[PkgVersion] skipping private package Database::Accessor::Roles::DAD in lib/Database/Accessor.pm

couldn't determine document name for lib/Database/Accessor/Manual.pod

Add something like this to lib/Database/Accessor/Manual.pod:

# PODNAME: bobby_tables.pl at /usr/local/share/perl/5.18.2/Pod/Weaver.pm line 135.

Hmm I think one should get an automatic 65 on the NPAS if you know that Bobby Tables' real name is “Robert'); DROP TABLE students;---”. Anyway that seems like a good idea so I added one in and gave the build another go and got

[PkgVersion] skipping private package Database::Accessor::Roles::DAD in lib/Database/Accessor.pm

[PodWeaver] [@Default/Name] couldn't find abstract in lib/Database/Accessor/Manual.pod

[DZ] writing Database-Accessor in Database-Accessor-0.01

still built and in my doc I have

# PODNAME: Manual


__END__

=pod

=encoding UTF-8

=head1 NAME

Manual

=head1 VERSION

version 0.01

=head1 Datatbase::Accessor is not an ORM

=head1 AUTHOR

John Scoles

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by John Scoles.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007

Ok so that takes care of a good deal of the boiler plate, and I see that it added in a NAME for me taking the just the file name. Ok I can see some potential here I guess. Now to search about and find some other goodies for the pot.

What I am playing with here is realy just Pod::Weaver Dist::Zilla is just doing all the instace codeing for my which is nice. Now documention tends to be a little sparce, no tutorial or how-to POD out there that I could find. From what little I have found I managed to piece together that it is 'Pod::Elemental::Transformer' that you need to get installed and use one of its Transformers.

One of the often used ones is 'Pod::Elemental::Transformer::List' and as I would like to have a TOC or alike on my initial Manual.pod I will give that a try.

In my 'weaver.ini' file I need to set this up like this

[@Default]

++[-Transformer]

++transformer = List

and in my POD I will just start with something simple

=head1 Datatbase::Accessor is not an ORM


=head1 Table Of Contents

=for :list

* Database::Accessor::Tutorial::GettingStarted

* Database::Accessor::Tutorial::Basics

=cut 

and then after installing ' Pod::Elemental::Transformer::List, I give it a go with 'dzil build' and voila;

=head1 Table Of Contents

=for :list

* Database::Accessor::Tutorial::GettingStarted

* Database::Accessor::Tutorial::Basics

Hmm that does not look right??

Oh well something to figure out for tomorrow.