Pod::Weaver is a tool that uses templates to generate documentation from POD source. It addresses issues like redundant documentation by following rules defined in a weaver.ini template file. This allows it to generate leaner POD that removes unneeded sections like NAME, VERSION, and AUTHORS. It also defines subroutines, methods, and attributes more cleanly. Pod::Weaver supports various output formats through different templates and can be used via Dist::Zilla or directly with the podweaver command.

1. Pod::Weaver
Module author: Ricardo Signes
Talk author: Joshua Keroes
Date: 13 Sep 2012

2. Who likes to write
documentation?
http://www.flickr.com/photos/bensonkua/2687804310/
2

3. What sucks about
documentation?
3

4. What sucks about
documentation?
It violates the DRY rule.
3

5. What sucks about
documentation?
It violates the DRY rule.
3

6. What else sucks?
4

7. What else sucks?
POD is too verbose.
=head1 FUNCTIONS
=over
=item frowny()
Returns a frowny face.
=back
4

8. What else sucks?
Let it all out.
=head1 COPYRIGHT AND LICENSE
Copyright (c) 1901 Fergie T. Sumtin.
All rights reserved.
5

9. Templates to the rescue
6

10. Templates to the rescue
POD::Weaver uses a template.
It’s called weaver.ini.
6

11. weaver.ini [@Default]
[@Default]
7

12. 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

13. 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

14. 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

15. 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

16. [NAME]
=head1 NAME
Some::Package::Name - just a package
12

17. [NAME]
=head1 NAME
Some::Package::Name - just a package
# PODNAME: Some::Package::Name
# ABSTRACT: just a package
13

18. [NAME]
=head1 NAME
Some::Package::Name - just a package
package Some::Package::Name
# ABSTRACT: just a package
14

19. [VERSION]
=head1 VERSION
version 1.234
15

20. [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

21. [Collect / FUNCTIONS]
command = func
=head1 FUNCTIONS
=over
=item binge()
eats arguments
=item purge()
returns eaten args
=back
17

22. [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

23. [Collect / METHODS]
command = method
=head1 METHODS
=over
=item new()
creates an object
=item spawn()
spawns an object
=back
19

24. [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

25. [Collect / ATTRIBUTES]
command = attr
=head1 ATTRIBUTES
=over
=item torches()
number of torches
=item matches()
number of matches
=back
21

26. [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

27. [Region / prelude]
=begin :prelude weaver.ini
… [Name]
=end :prelude [Version]
[Region / prelude]
=for :prelude … [Generic / SYNOPSIS]
[Generic / DESCRIPTION]
…
23

28. [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

29. [Region / postlude]
=begin :postlude weaver.ini
… …
=end :postlude [Leftovers]
[Region / postlude]
=for :postlude … [Authors]
[Legal]
25

30. [Authors]
=head1 AUTHORS weaver.ini
Colette O’Day …
<colette@example.com>
[Leftovers]
[Region / postlude]
[Authors]
[Legal]
26

31. [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

32. Let’s sum up.
28

33. Leaner POD
No more NAME
No more VERSION
No more AUTHORS
No more COPYRIGHT AND LICENSE
29

34. Leaner POD
Cleaner subroutine definitions
=func
=method
=attr
30

35. Beyond @Default

36. Lists, the lazy way
weaver.ini
[@Default]
[-Transformer]
transformer = List
32

37. Lists
=head1 SEE ALSO
=over 4
=item *
L<Your::Module>
=item *
L<Your::Package>
=back
33

38. 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

39. Pod::Weaver numeric lists
=head1 SEE ALSO =head1 SEE ALSO
=over 4
=item * =for :list
L<Your::Module> 1. L<Your::Module>
=item * 1. L<Your::Package>
L<Your::Package>
=back
35

40. Pod::Weaver frontends
36

41. Dist::Zilla
dist.ini
[PodWeaver]
…
37

42. App::podweaver
Great for troubleshooting; bypassing Dist::Zilla
podweaver lib/path/to/file.pm
38

43. 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