Getting started with Pod::Weaver
Upcoming SlideShare
Loading in...5
×
 

Getting started with Pod::Weaver

on

  • 1,717 views

Let Perl write your documentation for you.

Let Perl write your documentation for you.

Statistics

Views

Total Views
1,717
Views on SlideShare
1,717
Embed Views
0

Actions

Likes
0
Downloads
1
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Apple Keynote

Usage Rights

CC Attribution-NonCommercial-ShareAlike LicenseCC Attribution-NonCommercial-ShareAlike LicenseCC Attribution-NonCommercial-ShareAlike License

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • \n
  • Show of hands and wild cheering please.\n(If >1: hire this champ)\n(If 0: typical. Fortunately, Pod::Weaver can help)\n\n
  • Why don’t we like to write docs?\nDRY. Heck, we already wrote the code, right?\nBeyond that, every module file in every module must have a NAME section. And an ABSTRACT. And they should have a COPYRIGHT, LICENSE, and AUTHOR(s), too. There’s a lot of repeated effort.\n
  • Why don’t we like to write docs?\nDRY. Heck, we already wrote the code, right?\nBeyond that, every module file in every module must have a NAME section. And an ABSTRACT. And they should have a COPYRIGHT, LICENSE, and AUTHOR(s), too. There’s a lot of repeated effort.\n
  • Should we really have to start a FUNCTIONS section? Is it a head1 or a head2? Why do we have to indent? Or remember to stop indenting, for that matter? And what if we want to intermingle POD with code?\n
  • Should we really have to start a FUNCTIONS section? Is it a head1 or a head2? Why do we have to indent? Or remember to stop indenting, for that matter? And what if we want to intermingle POD with code?\n
  • Why should you have to keep the copyright current? Honestly, we have a computer here.\n\n
  • Know what Perl's good at? Templating. Just count the number of template-related modules on CPAN. viz. http://mapofcpan.org/\n
  • weaver.ini is the template. Let’s take unwrap things a few levels. Default is a Pod::Weaver::PluginBundle::Default. The @-sign means PluginBundle instead of Plugin.\n
  • Let’s unwrap the CorePrep PluginBundle\n
  • Validate POD and make sure all sub-elements are nested under =head1’s. Good housekeeping, basically.\n
  • Undocumented treasure!\n
  • voila, the whole default template. Barring the two housekeeping plugins, the rest are in order. Let’s figure out what they do.\n
  • \n
  • Admittedly, this takes more typing. Fortunately, we can do better.\n
  • You need either a PODNAME or a package. The rule of thumb is to use PODNAME for programs and to package for modules.\n
  • Automatic and painless. podweaver gets it from a META.json or META.yml file. Under dzil, it depends which plugins are loaded in dist.ini, but that’s getting ahead of things.\n
  • Think of the GENERIC plugin as a pass-through. These three sections, named above, and their contents will pass through P::W relatively unharmed.\n
  • The collect plugin fetches and assembles sets of things. \n
  • PW will add the section header and add the indenting; we just list the functions and what they do.\n
  • The method collection uses the new =method keyword....\n
  • \n
  • Like Moose, Mouse, Moo, or Mo? =attr behaves just like the other collects. As with the other examples... Speaking of which, there are two plugins on CPAN you may find useful, one that adds an EXTENDS section; the other a CONSUMES section for Moose roles.\n
  • the shorthand on the right will generate the POD on the left.\n
  • Do you want to add generic/text before the synopsis? Text found here between a preludes =begin and =end or after a =for will be moved to the prelude location. This has to be generic text. I wasn’t able to add commands like =head1 successfully. We’ll look at another section that can handle this shortly.\n
  • Leftovers come before the postlude region. \n
  • Just like the prelude, the postlude will move generic/text after the leftovers.\n
  • Automatic. podweaver gets it from META.json or META.yml. Under dzil, it depends which plugins are loaded in dist.ini.\n
  • Automatic. podweaver gets it from META.json or META.yml. Under dzil, it depends which plugins are loaded in dist.ini.\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • The numbers start at one and are auto-incremented.\n
  • \n
  • Add one line to run Pod::weaver during `dzil build`.\n
  • \n
  • \n

Getting started with Pod::Weaver Getting started with Pod::Weaver Presentation Transcript

  • Pod::WeaverModule author: Ricardo SignesTalk author: Joshua KeroesDate: 13 Sep 2012
  • Who likes to writedocumentation? http://www.flickr.com/photos/bensonkua/2687804310/ 2
  • What sucks aboutdocumentation? 3 View slide
  • What sucks aboutdocumentation?It violates the DRY rule. 3 View slide
  • What sucks aboutdocumentation?It violates the DRY rule. 3
  • What else sucks? 4
  • What else sucks?POD is too verbose.=head1 FUNCTIONS=over=item frowny()Returns a frowny face.=back 4
  • What else sucks?Let it all out.=head1 COPYRIGHT AND LICENSECopyright (c) 1901 Fergie T. Sumtin.All rights reserved. 5
  • Templates to the rescue 6
  • Templates to the rescuePOD::Weaver uses a template.It’s called weaver.ini. 6
  • weaver.ini [@Default] [@Default] 7
  • weaver.ini [@Default] [@CorePrep] [Collect / ATTRIBUTES] command = attr [Name] [Collect / METHODS] [Version] command = method [Region  / prelude] [Generic / SYNOPSIS] [Generic / DESCRIPTION] [Leftovers] [Generic / OVERVIEW] [Region  / postlude] [Authors] 8
  • weaver.ini [@Default] [EnsurePod5] [Collect / ATTRIBUTES] [H1Nester] command = attr [Name] [Collect / METHODS] [Version] command = method [Region  / prelude] [Generic / SYNOPSIS] [Generic / DESCRIPTION] [Leftovers] [Generic / OVERVIEW] [Region  / postlude] [Authors] 9
  • weaver.ini [@Default] [EnsurePod5] [Collect / ATTRIBUTES] [H1Nester] command = attr [Name] [Collect / METHODS] [Version] command = method [Region  / prelude] [Collect / FUNCTIONS] [Generic / SYNOPSIS] command = func [Generic / DESCRIPTION] [Leftovers] [Generic / OVERVIEW] [Region  / postlude] [Authors] 10
  • weaver.ini [@Default] [EnsurePod5] [Collect / ATTRIBUTES] [H1Nester] command = attr [Name] [Collect / METHODS] [Version] command = method [Region  / prelude] [Collect / FUNCTIONS] [Generic / SYNOPSIS] command = func [Generic / DESCRIPTION] [Leftovers] [Generic / OVERVIEW] [Region  / postlude] [Authors] 11
  • [NAME]=head1 NAMESome::Package::Name - just a package 12
  • [NAME]=head1 NAMESome::Package::Name - just a package# PODNAME: Some::Package::Name# ABSTRACT: just a package 13
  • [NAME]=head1 NAMESome::Package::Name - just a packagepackage Some::Package::Name# ABSTRACT: just a package 14
  • [VERSION]=head1 VERSIONversion 1.234 15
  • [Generic / SYNOPSIS][Generic / DESCRIPTION][Generic / OVERVIEW]=head1 SYNOPSIS my $p = Some::Package::Name->new; say $p;=head1 DESCRIPTIONA module that knows it’s own package name. 16
  • [Collect / FUNCTIONS]command = func=head1 FUNCTIONS=over=item binge()eats arguments=item purge()returns eaten args=back 17
  • [Collect / FUNCTIONS]command = func=head1 FUNCTIONS=over=item binge() =func binge()eats arguments eats arguments=item purge() =func purge()returns eaten args returns eaten args=back 18
  • [Collect / METHODS]command = method=head1 METHODS=over=item new()creates an object=item spawn()spawns an object=back 19
  • [Collect / METHODS]command = method=head1 METHODS=over=item new() =method new()creates an object creates an object=item spawn() =method spawn()spawns an object spawns an object=back 20
  • [Collect / ATTRIBUTES]command = attr=head1 ATTRIBUTES=over=item torches()number of torches=item matches()number of matches=back 21
  • [Collect / ATTRIBUTES]command = attr=head1 ATTRIBUTES=over=item torches() =attr torches()number of torches number of torches=item matches() =attr matches()number of matches number of matches=back 22
  • [Region / prelude] =begin :prelude weaver.ini … [Name] =end :prelude [Version] [Region / prelude] =for :prelude … [Generic / SYNOPSIS] [Generic / DESCRIPTION] … 23
  • [Leftovers] =head1 SUPPORT weaver.ini For support, please … send a self-addressed, stamped envelope to: [Leftovers] Joshua Keroes [Region / postlude] Somewhere in [Authors] Portland, OR [Legal] 24
  • [Region / postlude] =begin :postlude weaver.ini … … =end :postlude [Leftovers] [Region / postlude] =for :postlude … [Authors] [Legal] 25
  • [Authors] =head1 AUTHORS weaver.ini Colette O’Day … <colette@example.com> [Leftovers] [Region / postlude] [Authors] [Legal] 26
  • [Legal] =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2012 by Joshua Keroes. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 27
  • Let’s sum up. 28
  • Leaner PODNo more NAMENo more VERSIONNo more AUTHORSNo more COPYRIGHT AND LICENSE 29
  • Leaner PODCleaner subroutine definitions =func =method =attr 30
  • Beyond @Default
  • Lists, the lazy way weaver.ini [@Default] [-Transformer] transformer = List 32
  • Lists =head1 SEE ALSO =over 4 =item * L<Your::Module> =item * L<Your::Package> =back 33
  • Pod::Weaver bullet lists =head1 SEE ALSO =head1 SEE ALSO =over 4 =item * =for :list L<Your::Module> * L<Your::Module> =item * * L<Your::Package> L<Your::Package> =back 34
  • Pod::Weaver numeric lists=head1 SEE ALSO =head1 SEE ALSO=over 4=item * =for :listL<Your::Module> 1. L<Your::Module>=item * 1. L<Your::Package>L<Your::Package>=back 35
  • Pod::Weaver frontends 36
  • Dist::Zilla dist.ini [PodWeaver] … 37
  • App::podweaverGreat for troubleshooting; bypassing Dist::Zillapodweaver lib/path/to/file.pm 38
  • ReferencesThis talk at SlideShare: http://xrl.us/jkeroespwDist::Zilla + Pod::Weaver http://xrl.us/dzilpwWhat is Pod::Weaver 1? http://xrl.us/rjbspw1What is POD::Weaver 2? http://xrl.us/rjbspw2Falling in love with Pod::Weaver http://xrl.us/lovepw 39