Still stuck in Section mode here at the Dist-Pen
Carrying from my last post today I am going to look at the [Contributors] section plug-in. This particular plug-in is of little value so for to my 'Database::Accessor' project as I have no other people working on it with me but one can always dream big that I may have some helpers as time goes on. So it is is work a look.
I wanted to see if anyone else is using this plug-in so I did a Reverse Dependency look up and found that there are thirty-six other distributions that use this so I have few places where I can go an peek and see how it is being used.
It boy scout day here in the Dist-Pen.
In may last post I had final look the various [Bug] section plug-ins so today I am going to look at Merit-badges. I am really talking about that great feeling you had when you earned your first badge in Cubs, Brownies or Young Pioneers. You know the ones I mean the ones for learning to build a fire, sew on a badges, help an old man across the street or showing true will in conforming with the collective.
You can get the same feeling all over again in the programming world as well. All joking aside the [Badge] section plug-in is a quick way to get visual display information to potential users of your software such as this;
So at a glace you know it is passing its testing and you need at least perl 5.10 to use it.
It is the big bug round up day here at the Dist-Pen
In my last post I had a look at the [Bugs] section plug-in for Pod::Weaver, following along that line I am going to look at a three similar ones;
All are just a variation on the [Bugs] plug-in and none of them have the 'header' attribute. I will give you the .25$ trour;
BugsAndLimitations
This plugin requires that you enter the 'bugtracker' key-value pairs under the 'resources' meta key and you can do that by either using the [Bugtracker] or the [MetaResources] to set these values up for you. With my present 'dist.ini' it will produce the following output
=head1 BUGS AND LIMITATIONS
You can make new bug reports, and view existing ones, through the
web interface at L<https://github.com/byterock/database-accessor/issues>
…
as you can see it does not care about the email address.
BugsRT
Yesterday, I attended Gotanda.pm, which is a Japanese local pm group organized by karupanerura.
A lot of interesting talks were presented there.
I especially enjoyed codehex's talk, where he introduced how to write closures in XS.
You can read his blog post for the more detailed explanation.
And I gave my talk about writing perl with w0rp/ale, which is an Asynchronous Lint Engine for vim8.
There is already a blog post about it by oalders, so you may notice it.
If you write Perl with vim, why don't you try ale together with
my simple syntax checker skaji/syntax-check-perl?
Knocking off another Section here at the Dist-Pen today.
The last few posts I was dealing with the trials and tribulation of the [Availability] section plug-in, today I am going to look at another section plug-in [Bugs].
As the name implies add a 'Bug' blurb to your POD. Like the plug-in from my last posts this one is closely entwined with Dist::Zilla and we are luck this time as the POD for this one is quite extensive and does a good job on explaining how to use it. Hopefully, I will not find another bug.
The gem I found in the POD was you can use this Dist::Zilla plug-in [MetaResources] to add name key-value pairs into the 'repository' key of the meta data. At the present time I have all that the key-values I think I need because I use the [GithubMeta] plug-in to gather that data.
So it is Dist and a little Pod day here in the Dist-Pen.
In my last post I as have a look at the [Availability] section plug-in and ran at a problem when I was trying to get the content for the 'development' info that was promised by the Plug-in.
There where a few issues with my approach. First what I wanted to see was the link up to my github site. I though that this would do it to the 'dist.ini' file;
...
[Bugtracker]
web = https://github.com/byterock/%l/issues
mailto = test@test.com
…
Sorry to say more Pod today in the Dist-Pen.
In my last post I wrapped up the final section [Legal] found in the [@Default] template for Pod::Weaver. Since I am on such a roll I will go on and look at a number of other 'Sections' that available on CPAN.
The first one I am going to look at is [Availability]. This will add an section to you POD that will contain an Availability blurb depending on what you have configured in your 'dist.ini' file.
This plug-in cannot be used stand alone you will have to use both the 'Dist::Zilla::Plugin::Bugtracker' and the 'Dist::Zilla::Plugin::Homepage plug-in in your 'dist.ini' file. Now I have yet to play with these two plug-ins so I will install and then add them to my '.ini' file
I can see the end soon for POD here in the Dist-Pen but not quite yet.
In my last post I had a real quick look at the [Authors] section plug-in and how the trick to using it is to know that the list of authors comes from your 'dist.ini' file. Today I am going to look [Legal] the last of the sections found in the [@Default] template.
As you can guess this is where
Pod::Weaver
dumps the legal stuff we all love to add to your PODs. Like the [Authors] plug-in this one gets its info from the 'dist.ini' file. In my file I have
...
author = John Scoles
license = GPL_3
copyright_holder = John Scoles
…
and that is why I get
=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
A few weeks back, it was pointed out to me that Timm Murray was proposing to write an eBook for using Perl on the Raspberry Pi. Due to my extensive work on that platform over the last two-plus years, I had keen interest in the project.
Timm will be writing the bulk of the content using various distributions including my RPi::WiringPi along with all its related distributions, and I will be adding at least one chapter to cover my indoor grow room single-webpage environment controller, as well as performing editing duties and testing of the code.
We've been working together for a couple of weeks now, and today, I'm proud to announce the official launching of the fundraiser for the new book.
Whether you're interested in working on the Raspberry Pi, or just want to donate to a good cause for other Perl hackers, please have a look.
Thanks!
Still plunking away in the POD world today in the Dist-Pen.
In my last post I had a look a the very simple [Leftovers] section plug-in and how it dumps all unaccounted for POD in the that place on your template. Today I am going to look at another simple one from the [@default] template [Authors]
Looking at the POD for the first time is plug-in one would be quite lost at how to use it. I guess the original POD writer though that is was so simple to use it need no explanation. The trick here is this particular plug-in gets all its info from the 'dist.ini' file. In that file there will be a least one 'author' line as in mine;
name = Database-Accessor
author = John Scoles
license = GPL_3
…
To add in more 'authors' simply add in more of the same line like so
author = John Scoles
++author = Bill Bloggings
license = GPL_3
…
and after a quick clean and build with 'dzil' I get
Hey everyone,
Following is the p5p (Perl 5 Porters) mailing list summary for the past three weeks.
Enjoy!
In This Issue:
Keynote Speaker: VM (Vicky) Brasseur
VM (aka Vicky) spent most of her 20 years in the tech industry leading software development departments and teams, and providing technical management and leadership consulting for small and medium businesses. Now she leverages nearly 30 years of free and open source software experience and a strong business background to advise companies about free/open source, technology, community, business, and the intersections between them.
She is the author of Forge Your Future with Open Source, the first book to detail how to contribute to free and open source software projects. Think of it as the missing manual of open source contributions and community participation. The book is published by The Pragmatic Programmers and is now available in an early release beta version. It's available at https://fossforge.com.
Well POD post-ette day again here in the Dist-Pen
In my last post I had a look at the [Collect] section plug-in and how you can use it to gather up similar parts of your POD in to one section in a document. Useful when you want to keep the POD next to the code but you have a mix of function attributes and subs in the code for other valid reasons.
Today I am looking aI would guess would be the simplest plug-in to use [Leftovers]. As the name implies it dump any Pod that has not been put into another section.
In the case of the [@Default] template it is here;
...
[Leftovers]
[Region / postlude]
[Authors]
[Legal]
Now in my present POD I only have one left over bit
=head1 Datatbase::Accessor is not an ORM
and with the above default you see it show ups just before the [Authors] section
Check out older version at ...
=head1 Datatbase::Accessor is not an ORM
Last Thursday, I attended the London Perl Mongers Tech Meet at the Zoopla. This was my second time attending tech meet. I must say this was better than the previous meet, in many ways. First there were more people this time than compare to the last one, I attended. Second, this time talk was more Perl-ish. And last but not the least, plenty of food and drinks, thanks to all the sponsors.
Its collection day here at the Dist-Pen.
In my last post I looked at the rather plain but useful [Generic] section plug-in, that lets the Pod writer control where any section of POD that begins with =head1 can be moved to anywhere on the page. Today I am going to look at another of the often used plug-in the [Collect] section or plug-in.
This section is used to gather, group collect or otherwise gather together items under a named '=head1' tag what have the same POD tag. Looking at the [@Default] template again you will see there are three of them;
[Collect / ATTRIBUTES]
command = attr
[Collect / METHODS]
command = method
[Collect / FUNCTIONS]
command = func
I just shipped 1.300 of this module to the CPAN and it occurs to me that I’ve never talked about it here. I suppose I figured that what it does is so simple that there’s not much to say about it. But it‘s useful if you need what it does, and I wrote it because nobody else had.
- Do you have a web site being served over HTTPS?
- Do you want to redirect visitors coming in over HTTP to HTTPS?
(I.e. send visitors of
http://example.org/some/where to
https://example.org/some/where instead.)
If you answered yes once, you almost certainly answered yes twice. Right? It’s such a common thing to need.
But when I went looking for a way to make my PSGI application do that, I found nothing on CPAN.
I've just updated my tutorial document Perl XML::LibXML by Example to include a section on Working With Large Documents.
This new section introduces the XML::LibXML::Reader API which is a pull-parser style with much lower memory overheads that a traditional DOM parser. It also covers hybrid operation where the Reader API is used to scan through the document and extract sections as DOM fragments for further interrogation via XPath.
Sorry still on the all POD diet here at the Dist-pen today
In my last post I had a look at custom [Region] section and how that section lets you define your own custom tags you can use in you POD. Today I am looking at one of the often used sections and one of the more simple ones the [Generic] section.
If you look at the [@Default] template you will see no less than fours calls to this plug-in
...
[Generic / SYNOPSIS]
[Generic / DESCRIPTION]
[Generic / OVERVIEW]
[Collect / ATTRIBUTES]
...
so you will encounter quite often while looking at others templates. Like all the other plug-ins I can move them about in the template and that is how they will come out in the POD.
One uses this plug in to place in you POD any section of POD that begins with a '=head1' and matches the 'header' attribute you pass in. In the case where you POD does not match one of the '=head1' Pod::Weaver just ignores it.
Good Meal day here in the Dist-Pen
So in my last post I had a look at a the little more complex [Version] section plug-in for Pod::Weaver and Dist::Zilla. How the user can change the format of the section and even use some passed in variable, identified with a '%' in a section template.
Today we are going to look at one of the Meat and Potato sections the [Region]. This section allows you to place you own custom section or 'region' where-ever you want in your document. This is accomplished by using Pod::Weaver 'tags' which are simply text starting with a ':'
To start a 'region' one just needs to add
=begin :prelude
then your content you wanted and obviously to end it you just enter
=end :prelude
The ':' tag can be anything you want as long as it contains no spaces and matches with the end tag. The reason I chose ':prelude' is that it found in the default template I am playing with;
[Region / prelude]
Even more POD here at the Dit-pen.
In my last postI wrote about the rather simple [Name] section today I am going to move onto something a little more complex the [Version] section.
[Version] does not produce a lot of POD just
=head1 VERSION
version 0.01
in the case of my distribution. It is getting that '0.01' from my 'dist.ini' file
...
[AutoVersion]
major = 1
format = {{ sprintf('0.%02d',$major)}}
…
There are four attributes that I can play with on this 'section' plugin;
header
This works the same as the header in [name] so to make it the same as my last post I add this to my 'weaver.ini'
[Version]
header = Version
and I now get this
=head1 Version
version 0.01
So nothing to complex there.
format
This attribute controls what is printed when the version is generated. Now we are getting into a little more complex use of the template. There are nine variables that you can use with this attribute. They are