/ 
Pod-Advent-0.02
River stage zero No dependents
/ Pod::Advent

NAME

Pod::Advent - POD Formatter for The Perl Advent Calendar

VERSION

Version 0.02

SYNOPSIS

use Pod::Advent;
my $pod = shift @ARGV or die "need pod filename";
my $advent = Pod::Advent->new;
$advent->parse_file( \*STDIN );

DESCRIPTION

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.

Example: "sample.pod.txt" in ex renders as "sample.html" in ex

SUPPORTED POD

Custom Codes

A<>

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>

M<>

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>

N<>

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.

Custom Directives

sourcedcode

Custom Info Targets

advent_title

Specify the title of the submission.

=for advent_title Your Entry Title

advent_author

Specify the author of the submission.

=for advent_author Your Name Here

advent_year

Specify the year of the submission (defaults to current year).

=for advent_year 2007

advent_day

Specify the day of the submission (if currently known).

=for advent_day 99

Custom Block Targets

code

Display a code snippet (sends it through Perl::Tidy).

=begin code
my $foo = Bar->new();
$foo->do_it;
=end code

codeNNN

Same as code, but with line numbers.

=begin codeNNN
my $foo = Bar->new();
$foo->do_it;
=end codeNNN

pre

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

quote

Processes POD and wraps it in a <BLOCKQUOTE> section.

=begin quote
"Ho-Ho-Ho!"
  -- S.C.
=end quote

eds

Currently behaves exactly the same as quote.

=begin eds
The editors requested
this directive.
  -- the management
=end eds

Standard Codes

L<>

Normal behavior.

F<>

Normal behavior. Uses <tt>

C<>

Uses <tt>. Sends text through Perl::Tidy.

I<>

Normal behavior: uses <I>

B<>

Normal behavior: uses <B>

Standard Directives

headN

Expected behavior (N=1..4): uses <headN>

TODO

create test suite

include sample.pod and sample.html

code cleanup (remove the =head1 NAME support, and Y-code support)

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')

METHODS

See Pod::Simple for all of the inherited methods. Also see Pod::Simple::Subclassing for more information.

new

Constructor. See Pod::Simple.

INTERNAL METHODS

add

Appends text to the output buffer.

nl

Appends a newline onto the output buffer.

_handle_element_start

Overload of method to process start of an element.

_handle_element_end

Overload of method to process end of an element.

_handle_text

Overload of method to process handling of text.

AUTHOR

David Westbrook, <dwestbrook at gmail.com>

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Pod::Advent

You can also look for information at:

SEE ALSO

ACKNOWLEDGEMENTS

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 & LICENSE

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.