0
Pod::WeaverModule author: Ricardo SignesTalk author: Joshua KeroesDate: 13 Sep 2012
Who likes to writedocumentation?           http://www.flickr.com/photos/bensonkua/2687804310/                              ...
What sucks aboutdocumentation?                   3
What sucks aboutdocumentation?It violates the DRY rule.                            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
What else sucks?Let it all out.=head1 COPYRIGHT AND LICENSECopyright (c) 1901 Fergie T. Sumtin.All rights reserved.       ...
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 ...
weaver.ini [@Default] [EnsurePod5]           [Collect /                        ATTRIBUTES] [H1Nester]                     ...
weaver.ini [@Default] [EnsurePod5]           [Collect /                        ATTRIBUTES] [H1Nester]                     ...
weaver.ini [@Default] [EnsurePod5]           [Collect /                        ATTRIBUTES] [H1Nester]                     ...
[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             ...
[NAME]=head1 NAMESome::Package::Name - just a packagepackage Some::Package::Name# ABSTRACT: just a package                ...
[VERSION]=head1 VERSIONversion 1.234                 15
[Generic / SYNOPSIS][Generic / DESCRIPTION][Generic / OVERVIEW]=head1 SYNOPSIS  my $p = Some::Package::Name->new;  say $p;...
[Collect / FUNCTIONS]command = func=head1 FUNCTIONS=over=item binge()eats arguments=item purge()returns eaten args=back   ...
[Collect / FUNCTIONS]command = func=head1 FUNCTIONS=over=item binge()        =func binge()eats arguments       eats argume...
[Collect / METHODS]command = method=head1 METHODS=over=item new()creates an object=item spawn()spawns an object=back      ...
[Collect / METHODS]command = method=head1 METHODS=over=item new()         =method new()creates an object   creates an obje...
[Collect / ATTRIBUTES]command = attr=head1 ATTRIBUTES=over=item torches()number of torches=item matches()number of matches...
[Collect / ATTRIBUTES]command = attr=head1 ATTRIBUTES=over=item torches()     =attr torches()number of torches   number of...
[Region / prelude] =begin :prelude   weaver.ini …                 [Name] =end :prelude     [Version]                   [Re...
[Leftovers] =head1 SUPPORT           weaver.ini For support, please      … send a self-addressed, stamped envelope to:    ...
[Region / postlude] =begin :postlude   weaver.ini …                  … =end :postlude     [Leftovers]                    [...
[Authors] =head1 AUTHORS          weaver.ini Colette O’Day           … <colette@example.com>                         [Left...
[Legal] =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2012 by Joshua Keroes. This is free software; you can ...
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<Y...
Pod::Weaver numeric lists=head1 SEE ALSO    =head1 SEE ALSO=over 4=item *            =for :listL<Your::Module>    1. L<You...
Pod::Weaver frontends                        36
Dist::Zilla dist.ini [PodWeaver] …               37
App::podweaverGreat for troubleshooting; bypassing Dist::Zillapodweaver lib/path/to/file.pm                               ...
ReferencesThis talk at SlideShare: http://xrl.us/jkeroespwDist::Zilla + Pod::Weaver http://xrl.us/dzilpwWhat is Pod::Weave...
Upcoming SlideShare
Loading in...5
×

Getting started with Pod::Weaver

1,793

Published on

Let Perl write your documentation for you.

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
1,793
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
2
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide
  • \n
  • Show of hands and wild cheering please.\n(If &gt;1: hire this champ)\n(If 0: typical. Fortunately, Pod::Weaver can help)\n\n
  • Why don&amp;#x2019;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&amp;#x2019;s a lot of repeated effort.\n
  • Why don&amp;#x2019;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&amp;#x2019;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&apos;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&amp;#x2019;s take unwrap things a few levels. Default is a Pod::Weaver::PluginBundle::Default. The @-sign means PluginBundle instead of Plugin.\n
  • Let&amp;#x2019;s unwrap the CorePrep PluginBundle\n
  • Validate POD and make sure all sub-elements are nested under =head1&amp;#x2019;s. Good housekeeping, basically.\n
  • Undocumented treasure!\n
  • voila, the whole default template. Barring the two housekeeping plugins, the rest are in order. Let&amp;#x2019;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&amp;#x2019;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&amp;#x2019;t able to add commands like =head1 successfully. We&amp;#x2019;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
  • Transcript of "Getting started with Pod::Weaver"

    1. 1. Pod::WeaverModule author: Ricardo SignesTalk author: Joshua KeroesDate: 13 Sep 2012
    2. 2. Who likes to writedocumentation? http://www.flickr.com/photos/bensonkua/2687804310/ 2
    3. 3. What sucks aboutdocumentation? 3
    4. 4. What sucks aboutdocumentation?It violates the DRY rule. 3
    5. 5. What sucks aboutdocumentation?It violates the DRY rule. 3
    6. 6. What else sucks? 4
    7. 7. What else sucks?POD is too verbose.=head1 FUNCTIONS=over=item frowny()Returns a frowny face.=back 4
    8. 8. What else sucks?Let it all out.=head1 COPYRIGHT AND LICENSECopyright (c) 1901 Fergie T. Sumtin.All rights reserved. 5
    9. 9. Templates to the rescue 6
    10. 10. Templates to the rescuePOD::Weaver uses a template.It’s called weaver.ini. 6
    11. 11. weaver.ini [@Default] [@Default] 7
    12. 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. 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. 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. 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. 16. [NAME]=head1 NAMESome::Package::Name - just a package 12
    17. 17. [NAME]=head1 NAMESome::Package::Name - just a package# PODNAME: Some::Package::Name# ABSTRACT: just a package 13
    18. 18. [NAME]=head1 NAMESome::Package::Name - just a packagepackage Some::Package::Name# ABSTRACT: just a package 14
    19. 19. [VERSION]=head1 VERSIONversion 1.234 15
    20. 20. [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
    21. 21. [Collect / FUNCTIONS]command = func=head1 FUNCTIONS=over=item binge()eats arguments=item purge()returns eaten args=back 17
    22. 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. 23. [Collect / METHODS]command = method=head1 METHODS=over=item new()creates an object=item spawn()spawns an object=back 19
    24. 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. 25. [Collect / ATTRIBUTES]command = attr=head1 ATTRIBUTES=over=item torches()number of torches=item matches()number of matches=back 21
    26. 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. 27. [Region / prelude] =begin :prelude weaver.ini … [Name] =end :prelude [Version] [Region / prelude] =for :prelude … [Generic / SYNOPSIS] [Generic / DESCRIPTION] … 23
    28. 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. 29. [Region / postlude] =begin :postlude weaver.ini … … =end :postlude [Leftovers] [Region / postlude] =for :postlude … [Authors] [Legal] 25
    30. 30. [Authors] =head1 AUTHORS weaver.ini Colette O’Day … <colette@example.com> [Leftovers] [Region / postlude] [Authors] [Legal] 26
    31. 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. 32. Let’s sum up. 28
    33. 33. Leaner PODNo more NAMENo more VERSIONNo more AUTHORSNo more COPYRIGHT AND LICENSE 29
    34. 34. Leaner PODCleaner subroutine definitions =func =method =attr 30
    35. 35. Beyond @Default
    36. 36. Lists, the lazy way weaver.ini [@Default] [-Transformer] transformer = List 32
    37. 37. Lists =head1 SEE ALSO =over 4 =item * L<Your::Module> =item * L<Your::Package> =back 33
    38. 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. 39. 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
    40. 40. Pod::Weaver frontends 36
    41. 41. Dist::Zilla dist.ini [PodWeaver] … 37
    42. 42. App::podweaverGreat for troubleshooting; bypassing Dist::Zillapodweaver lib/path/to/file.pm 38
    43. 43. 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
    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.

    ×