Pod::Advent - POD Formatter for The Perl Advent Calendar
Version 0.03
use Pod::Advent; my $pod = shift @ARGV or die "need pod filename"; my $advent = Pod::Advent->new; $advent->parse_file( \*STDIN );
Example POD:
=for advent_year 2007 =for advent_day 32 =for advent_title This is a sample =for advent_author Your Name Here Today's module M<My::Example> is featured on the A<http://example.com|Example Place> web site and is I<very> B<special>. =sourcedcode example.pl
This module provides a POD formatter that is designed to facilitate the create of submissions for The Perl Advent Calendar (http://perladvent.pm.org) by providing authors with simple markup that will be automatically transformed to full-fill the specific formatting guidelines. This makes it easier for authors to provide calendar-ready submissions, and for the editors to save lots of time in editting submissions.
For example, 'file-, module and program names should be wrapped in <tt>,' and 'the code sample should be appended to the document from the results of a perltidy -nnn -html'. Both of these can be trivially accomplished:
This entry is for M<Foo::Bar> and the F<script.pl> program. =sourcedcode mod0.pl
The meta-data of title, date (year & day), and author is now easy to specify as well, and is used to automatically generate the full HTML header (including style) that the calendar entries require before being posted.
See ex/sample.pod.txt and ex/sample.html in the distribution for a fuller example.
This is because POD doesn't support the case of L<http://example.com|Example>, so we introduce this A<> code for that exact purpose -- to generate <a href="URL">TEXT</a> hyperlinks.
A<http://perladvent.pm.org|The Perl Advent Calendar> A<http://perladvent.pm.org>
This is intended for module names. The first instance, it will <tt> it and hyperlink it to a http://search.cpan.org/search?module= url. All following instances will just <tt> it. Being just for module searches, any other searches can simply use the A<> code instead.
M<Pod::Simple> A<http://search.cpan.org/search?query=Pod::Simple::Subclassing|Pod::Simple::Subclassing> A<http://search.cpan.org/search?dist=TimeDate|TimeDate>
Insert a superscript footnote reference. It will link to a #N anchor.
In this entry we talk about XYZ.N<3> ... <a name="3"></a>3. Some footnote about XYZ.
Specify the title of the submission.
=for advent_title Your Entry Title
Specify the author of the submission.
=for advent_author Your Name Here
Specify the year of the submission (defaults to current year).
=for advent_year 2007
Specify the day of the submission (if currently known).
=for advent_day 99
Display a code snippet (sends it through Perl::Tidy).
=begin code my $foo = Bar->new(); $foo->do_it; =end code
Same as code, but with line numbers.
=begin codeNNN my $foo = Bar->new(); $foo->do_it; =end codeNNN
Display a snippet (e.g. data, output, etc) as <PRE>-formatted text (does not use Perl::Tidy).
=begin pre x,y,z 1,2,3 2,4,9 3,8,27 =end pre
Processes POD and wraps it in a <BLOCKQUOTE> section.
=begin quote "Ho-Ho-Ho!" -- S.C. =end quote
Currently behaves exactly the same as quote.
=begin eds The editors requested this directive. -- the management =end eds
Normal behavior.
Normal behavior. Uses <tt>
Uses <tt>. Sends text through Perl::Tidy.
Normal behavior: uses <I>
Normal behavior: uses <B>
Expected behavior (N=1..4): uses <headN>
create test suite
include sample.pod and sample.html
code refactoring (package var usage; also maybe make code/directive behavior based on a config data structure)
footnotes
over/item
optional stylesheet
supported pod docs
docs re: html passing through
spell check support -- probably on the POD, as opposed to generated html
specify 5.6.1 as min perl ... https://rt.cpan.org/Public/Bug/Display.html?id=28374
check html output for validity
try w/other Pod::Simple output options .. e.g. to scalar to file or handle. (i.e. not always just plain 'print')
See Pod::Simple for all of the inherited methods. Also see Pod::Simple::Subclassing for more information.
Constructor. See Pod::Simple.
Appends text to the output buffer.
Appends a newline onto the output buffer.
Overload of method to process start of an element.
Overload of method to process end of an element.
Overload of method to process handling of text.
David Westbrook, <dwestbrook at gmail.com>
<dwestbrook at gmail.com>
Please report any bugs or feature requests to bug-pod-advent at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pod-Advent. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-pod-advent at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Pod::Advent
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Pod-Advent
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Pod-Advent
CPAN Ratings
http://cpanratings.perl.org/d/Pod-Advent
Search CPAN
http://search.cpan.org/dist/Pod-Advent
http://perladvent.pm.org - The Perl Advent Calendar
http://perladvent.pm.org/2007/17 - The 2007-12-17 submission that discussed this application of Pod::Simple
Pod::Simple - The base class for Pod::Advent
Pod::Simple::Subclassing - Discusses the techniques that Pod::Advent is based on
perlpod - POD documentation
Perl::Tidy - used for formatting code
The maintainers of The Perl Advent Calendar at http://perladvent.pm.org.
The 2007 editors, Bill Ticker & Jerrad Pierce, for reviewing and providing feedback on this concept.
Copyright 2007 David Westbrook, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Pod::Advent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Advent
CPAN shell
perl -MCPAN -e shell install Pod::Advent
For more information on module installation, please visit the detailed CPAN module installation guide.