Getting started with Pod::Weaver
43
Pod::Weaver Module author: Ricardo Signes Talk author: Joshua Keroes Date: 13 Sep 2012
-
Upload
joshua-keroes -
Category
Technology
-
view
2.561 -
download
0
Transcript of Getting started with Pod::Weaver
Pod::WeaverModule author: Ricardo SignesTalk author: Joshua KeroesDate: 13 Sep 2012
Who likes to write documentation?
http://www.flickr.com/photos/bensonkua/2687804310/
2
What sucks about documentation?
3
It violates the DRY rule.
What sucks about documentation?
3
It violates the DRY rule.
What sucks about documentation?
3
What else sucks?
4
What else sucks?
POD is too verbose.
=head1 FUNCTIONS
=over
=item frowny()
Returns a frowny face.
=back4
What else sucks?Let it all out.
=head1 COPYRIGHT AND LICENSE
Copyright (c) 1901 Fergie T. Sumtin.
All rights reserved.
5
Templates to the rescue
6
Templates to the rescue
POD::Weaver uses a template.
It’s called weaver.ini.
6
weaver.ini [@Default]
[@Default]
7
weaver.ini [@Default][@CorePrep]
[Name]
[Version]
[Region / prelude]
[Generic / SYNOPSIS]
[Generic / DESCRIPTION]
[Generic / OVERVIEW]
[Collect / ATTRIBUTES]
command = attr
[Collect / METHODS]
command = method
[Leftovers]
[Region / postlude]
[Authors] 8
weaver.ini [@Default][EnsurePod5]
[H1Nester]
[Name]
[Version]
[Region / prelude]
[Generic / SYNOPSIS]
[Generic / DESCRIPTION]
[Generic / OVERVIEW]
[Collect / ATTRIBUTES]
command = attr
[Collect / METHODS]
command = method
[Leftovers]
[Region / postlude]
[Authors] 9
weaver.ini [@Default][EnsurePod5]
[H1Nester]
[Name]
[Version]
[Region / prelude]
[Generic / SYNOPSIS]
[Generic / DESCRIPTION]
[Generic / OVERVIEW]
[Collect / ATTRIBUTES]
command = attr
[Collect / METHODS]
command = method
[Collect / FUNCTIONS]
command = func
[Leftovers]
[Region / postlude]
[Authors] 10
weaver.ini [@Default][EnsurePod5]
[H1Nester]
[Name]
[Version]
[Region / prelude]
[Generic / SYNOPSIS]
[Generic / DESCRIPTION]
[Generic / OVERVIEW]
[Collect / ATTRIBUTES]
command = attr
[Collect / METHODS]
command = method
[Collect / FUNCTIONS]
command = func
[Leftovers]
[Region / postlude]
[Authors] 11
[NAME]
=head1 NAME
Some::Package::Name - just a package
12
[NAME]
=head1 NAME
Some::Package::Name - just a package
# PODNAME: Some::Package::Name
# ABSTRACT: just a package
13
[NAME]
=head1 NAME
Some::Package::Name - just a package
package Some::Package::Name
# ABSTRACT: just a package
14
[VERSION]
=head1 VERSION
version 1.234
15
[Generic / SYNOPSIS][Generic / DESCRIPTION][Generic / OVERVIEW]
=head1 SYNOPSIS
my $p = Some::Package::Name->new;
say $p;
=head1 DESCRIPTION
A 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()
eats arguments
=item purge()
returns eaten args
=back
=func binge()
eats arguments
=func purge()
returns eaten args
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()
creates an object
=item spawn()
spawns an object
=back
=method new()
creates an object
=method spawn()
spawns an object
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()
number of torches
=item matches()
number of matches
=back
=attr torches()
number of torches
=attr matches()
number of matches
22
[Region / prelude]
=begin :prelude
…
=end :prelude
=for :prelude …
weaver.ini
[Name]
[Version]
[Region / prelude]
[Generic / SYNOPSIS]
[Generic / DESCRIPTION]
…
23
=head1 SUPPORT
For support, please send a self-addressed, stamped envelope to:
Joshua Keroes
Somewhere in
Portland, OR
weaver.ini
…
[Leftovers]
[Region / postlude]
[Authors]
[Legal]
[Leftovers]
24
[Region / postlude]
=begin :postlude
…
=end :postlude
=for :postlude …
weaver.ini
…
[Leftovers]
[Region / postlude]
[Authors]
[Legal]
25
[Authors]
=head1 AUTHORS
Colette O’Day <[email protected]>
weaver.ini
…
[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 POD
No more NAME
No more VERSION
No more AUTHORS
No more COPYRIGHT AND LICENSE
29
Leaner POD
Cleaner 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
=over 4
=item *
L<Your::Module>
=item *
L<Your::Package>
=back
=head1 SEE ALSO
=for :list
* L<Your::Module>
* L<Your::Package>
34
Pod::Weaver numeric lists
=head1 SEE ALSO
=over 4
=item *
L<Your::Module>
=item *
L<Your::Package>
=back
=head1 SEE ALSO
=for :list
1. L<Your::Module>
1. L<Your::Package>
35
Pod::Weaver frontends
36
Dist::Zilla
dist.ini
[PodWeaver]
…
37
App::podweaver
Great for troubleshooting; bypassing Dist::Zilla
podweaver lib/path/to/file.pm
38
References
This talk at SlideShare: http://xrl.us/jkeroespw
Dist::Zilla + Pod::Weaver http://xrl.us/dzilpw
What is Pod::Weaver 1? http://xrl.us/rjbspw1
What is POD::Weaver 2? http://xrl.us/rjbspw2
Falling in love with Pod::Weaver http://xrl.us/lovepw
39
