# Generated by Pod::WikiDoc version 0.17

=pod

=head1 NAME

Pod::WikiDoc - Generate Pod from inline wiki style text 

=head1 VERSION

This documentation refers to version 0.18.

=head1 SYNOPSIS

In a source file, Pod format-block style:

     =begin wikidoc
 
     = POD FORMAT-BLOCK STYLE
 
     Write documentation with *bold*, ~italic~ or {code}
     markup.  Create a link to [Pod::WikiDoc].
     Substitute for user-defined %%KEYWORD%%.
 
         Indent for verbatim paragraphs
 
     * bullet
     * point
     * list
 
     0 sequentially
     0 numbered
     0 list
 
     = end wikidoc

In a source file, wikidoc comment-block style:

     ### = WIKIDOC COMMENT-BLOCK STYLE
     ###
     ### Optionally, [Pod::WikiDoc] can extract from
     ### specially-marked comment blocks

Generate Pod from wikidoc, programmatically:

     use Pod::WikiDoc;
     my $parser = Pod::WikiDoc->new( { 
         comment_blocks => 1,
         keywords => { KEYWORD => "foo" },
     } );
     $parser->filter( 
         { input => "my_module.pm", output => "my_module.pod" }
     );

Generate Pod from wikidoc, via command line:

     $ wikidoc -c my_module.pm my_module.pod

=head1 DESCRIPTION

Pod works well, but writing it can be time-consuming and tedious.  For example,
commonly used layouts like lists require numerous lines of text to make just
a couple of simple points.  An alternative approach is to write documentation
in a wiki-text shorthand (referred to here as I<wikidoc>) and use Pod::WikiDoc
to extract it and convert it into its corresponding Pod as a separate C<<< .pod >>>
file.

Documentation written in wikidoc may be embedded in Pod format blocks, or,
optionally, in specially marked comment blocks.  Wikidoc uses simple text-based
markup like wiki websites to indicate formatting and links.  (See 
L</WIKIDOC MARKUP>, below.)

Pod::WikiDoc processes text files (or text strings) by extracting both
existing Pod and wikidoc, converting the wikidoc to Pod, and then writing
the combined document back to a file or standard output. 

Summary of major features of Pod::WikiDoc:

=over

=item *

Extracts and converts wikidoc from Pod format blocks or special 
wikidoc comment blocks

=item *

Extracts and preserves existing Pod

=item *

Provides bold, italic, code, and link markup

=item *

Substitutes user-defined keywords

=item *

Automatically converts special symbols in wikidoc to their
Pod escape equivalents, e.g. EE<lt>ltE<gt>, EE<lt>gtE<gt>

=item *

Preserves other Pod escape sequences, e.g. EE<lt>euroE<gt>

=back

In addition, Pod::WikiDoc provides a command-line utility, L<wikidoc>,
to simplify wikidoc translation.

See the L<Pod::WikiDoc::Cookbook> for more detailed usage examples, 
including how to automate C<<< .pod >>> generation when using L<Module::Build>.

=head1 INTERFACE


=head2 C<<< new >>>

     $parser = Pod::WikiDoc->new( \%args );

Constructor for a new Pod::WikiDoc object.  It takes a single, optional 
argument: a hash reference with the following optional keys:

=over

=item *

C<<< comment_blocks >>>: if true, Pod::WikiDoc will scan for wikidoc in comment
blocks.  Default is false.

=item *

C<<< comment_prefix_length >>>: the number of leading sharp (#) symbols to 
denote a comment block.  Default is 3.

=item *

C<<< keywords >>>: a hash reference with keywords and values for keyword
substitution

=back

=head2 C<<< convert >>>

     my $pod_text = $parser->convert( $input_text );

Given a string with valid Pod andE<sol>or wikidoc markup, filterE<sol>translate it to
Pod.  This is really just a wrapper around C<<< filter >>> for working with
strings rather than files, and provides similar behavior, including adding
a 'Generated by' header.

=head2 C<<< filter >>>

     $parser->filter( \%args );

Filters from an input file for Pod and wikidoc, translating it to Pod 
and writing it to an output file.  The output file will be prefixed with
a 'Generated by' comment with the version of Pod::WikiDoc and timestamp,
as required by L<perlpodspec>.

C<<< filter >>> takes a single, optional argument: a hash reference with 
the following optional keys:

=over

=item *

C<<< input >>>: a filename or filehandle to read from. Defaults to STDIN.  

=item *

C<<< output >>>: a filename or filehandle to write to.  If given a filename
and the file already exists, it will be clobbered. Defaults to STDOUT.

=back

=head2 C<<< format >>>

     my $pod_text = $parser->format( $wiki_text );

Given a string with valid Pod andE<sol>or wikidoc markup, filterE<sol>translate it to
Pod. Unlike C<<< convert >>>, no 'Generated by' comment is added.  This 
function is used internally by Pod::WikiDoc, but is being made available
as a public method for users who want more granular control of the 
translation process or who want to convert wikidoc to Pod for other
creative purposes using the Pod::WikiDoc engine.

=head1 WIKIDOC MARKUP

Pod::WikiDoc uses a wiki-style text markup, called wikidoc.  It is heavily
influenced by L<Kwiki>.  Like other wiki markup, it has both block and 
inline elements, which map directly to their Pod equivalents.

Block elements include:

=over

=item *

Headers

=item *

Verbatim text

=item *

Bullet lists

=item *

Numbered lists

=item *

Ordinary paragraphs

=back

Block elements should be separated by a blank line (though Pod::WikiDoc 
will do the right thing in many cases if you don't).

Inline elements include:

=over

=item *

Bold

=item *

Italic

=item *

Code

=item *

Link

=item *

Escape code

=item *

Keywords

=back

All text except that found in verbatim text, code markup or keywords is
transformed to convert special Pod characters to Pod escape code markup:
EE<lt>ltE<gt>, EE<lt>gtE<gt>, EE<lt>solE<gt>, EE<lt>verbarE<gt>.  Inline markup can be escaped with
a backslash (\).  Including a literal backslash requires a double-backslash
(\\).

=head2 Headers

Headers are indicated with one or more equals signs followed by whitespace in
the first column.  The number of equals signs indicates the level of the
header (the maximum is four).  Headers can not span multiple lines.  

     = header level 1
 
     == header level 2

=head2 Verbatim text

Verbatim text is indicated with leading whitespace in each line of text,
just as with Pod.

     #<--- first column 
 
         sub verbatim {}

=head2 Bullet lists

Bullet lists are indicated with an asterisk in the first column followed by
whitespace.  Bullet lists can span multiple lines.  Lines after the first
should not have an asterisk or be indented.

     * First item in the list
     * Second item in the list
     on multiple lines
     * Third item in the list

=head2 Numbered lists

Numbered lists work just like numbered lists, but with a leading 0 followed
by whitespace.

     0 First item in the list
     0 Second item in the list
     on multiple lines
     0 Third item in the list

=head2 Ordinary paragraphs

Ordinary paragraphs consist of one or more lines of text that do not match
the criteria of other blocks.  Paragraphs are terminated with a empty line.

     This is an ordinary paragraph that
     spans multiple lines.

=head2 Bold markup

Bold text is indicated by bracketing with asterisks.  Bold markup must
begin at a whitespace boundary, the start of a line, or the inside of
other markup.

     This shows *bold* text.

=head2 Italic markup

Italic text is indicated by bracketing with tildes.  Italic markup must
begin at a whitespace boundary, the start of a line, or the inside of
other markup.

     This shows ~italic~ text.

=head2 Code markup

Code (monospaced) text is indicated by bracketing with matched braces.  Code
markup must begin at a whitespace boundary, the start of a line, or the inside
of other markup.  Brackets should nest properly with code.

     This shows {code} text.  It can surround text
     with brackets like this: { $data{ $id } }

=head2 Link markup

Link text is indicated by bracketing with square brackets.  As with Pod, link
text may include a vertical bar to separate display text from the link itself.
Link markup must begin at a whitespace boundary, the start of a line, or the
inside of other markup.

     This is an ordinary [Pod::WikiDoc] link.
     This is a [way to ~markup~ links|Pod::WikiDoc] with display text
     Hypertext links look like this: [http://www.google.com/]

=head2 Escape code markup

Pod-style escape text is passed through as normal to support international
or other unusual characters.

     This is the euro symbol: E<euro> 

=head2 Keyword markup

Text surrounded by double-percent signs is treated as a keyword for expansion.
The entire expression will be replaced with the value of the keyword from the
hash provided when the parser is created with C<<< new() >>>.  If the keyword is
unknown or the value is undefined, the keyword will be passed through
unchanged.

     This is version %%VERSION%%

=head1 DIAGNOSTICS

=over

=item *

C<<< Error: Argument to convert() must be a scalar >>>

=item *

C<<< Error: Argument to filter() must be a hash reference >>>

=item *

C<<< Error: Argument to format() must be a scalar >>>

=item *

C<<< Error: Argument to new() must be a hash reference >>>

=item *

C<<< Error: Class method new() can't be called on an object >>>

=item *

C<<< Error: Couldn't open input file 'FILENAME' >>>

=item *

C<<< Error: Couldn't open output file 'FILENAME' >>>

=item *

C<<< Error: 'input' parameter for filter() must be a filename or filehandle >>>

=item *

C<<< Error: 'output' parameter for filter() must be a filename or filehandle >>>

=back

=head1 INCOMPATIBILITIES

=over

=item *

Default prefix length for wikidoc comment-blocks conflicts with
L<Smart::Comments>.  Change the C<<< comment_prefix_length >>> argument to C<<< new >>> in
Pod::WikiDoc or the level of 'smartness' in L<Smart::Comments> to avoid the
conflict.

=back

=over

=item *

Module::Build before 0.28 does not look in external C<<< .pod >>> files 
to generate a C<<< README >>> with the C<<< create_readme >>> option or to find a module 
abstract.  Set the abstract manually in the C<<< Build.PL >>> file with the
C<<< dist_abstract >>> option.

=back

=head1 BUGS

Please report bugs or feature requests using the CPAN Request Tracker.
Bugs can be submitted using the web interface at
L<http://rt.cpan.org/Public/Dist/Display.html?Name=Pod-WikiDoc>

When submitting a bug or request, please include a test-file or a patch to an
existing test-file that illustrates the bug or desired feature.

=head1 AUTHOR

David A. Golden (DAGOLDEN)

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2005, 2006, 2007 by David A. Golden

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at 
L<http://www.apache.org/licenses/LICENSE-2.0>

Files produced as output though the use of this software, including
generated copies of boilerplate templates provided with this software,
shall not be considered Derivative Works, but shall be considered the
original work of the Licensor.

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


