Getting started with Pod::Weaver

Pod::WeaverModule author: Ricardo SignesTalk author: Joshua KeroesDate: 13 Sep 2012

Who likes to writedocumentation? http://www.ﬂickr.com/photos/bensonkua/2687804310/ 2

What sucks aboutdocumentation? 3

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

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 deﬁnitions =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

Getting started with Pod::Weaver

by Joshua Keroes on Sep 13, 2012

Accessibility

Categories

Upload Details

Usage Rights

Statistics

Getting started with Pod::Weaver Presentation Transcript