NAME

VERSION

SYNOPSIS

     =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

DESCRIPTION

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 "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:

• Extracts and converts wikidoc from Pod format blocks or special wikidoc comment blocks
• Extracts and preserves existing Pod
• Provides bold, italic, code, and link markup
• Substitutes user-defined keywords
• Automatically converts special symbols in wikidoc to their Pod escape equivalents, e.g. E<lt>, E<gt>
• Preserves other Pod escape sequences, e.g. E<euro>

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

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

INTERFACE

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

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

     $parser->filter( \%args );

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

WIKIDOC MARKUP

Block elements include:

• Headers
• Verbatim text
• Bullet lists
• Numbered lists
• Ordinary paragraphs

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:

• Bold
• Italic
• Code
• Link
• Escape code
• Keywords

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

     = header level 1
 
     == header level 2

     #<--- first column
 
         sub verbatim {}

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

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

     This is an ordinary paragraph that
     spans multiple lines.

     This shows *bold* text.

     This shows ~italic~ text.

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

     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/]

     This is the euro symbol: E<euro>

     This is version %%VERSION%%

DIAGNOSTICS

• "Error: Argument to convert() must be a scalar"
• "Error: Argument to filter() must be a hash reference"
• "Error: Argument to format() must be a scalar"
• "Error: Argument to new() must be a hash reference"
• "Error: Class method new() can't be called on an object"
• "Error: Couldn't open input file 'FILENAME'"
• "Error: Couldn't open output file 'FILENAME'"
• "Error: 'input' parameter for filter() must be a filename or filehandle"
• "Error: 'output' parameter for filter() must be a filename or filehandle"

INCOMPATIBILITIES

• Default prefix length for wikidoc comment-blocks conflicts with Smart::Comments. Change the "comment_prefix_length" argument to "new" in Pod::WikiDoc or the level of 'smartness' in Smart::Comments to avoid the conflict.
• Module::Build before 0.28 does not look in external ".pod" files to generate a "README" with the "create_readme" option or to find a module abstract. Set the abstract manually in the "Build.PL" file with the "dist_abstract" option.

SUPPORT

  git clone https://github.com/dagolden/pod-wikidoc.git

AUTHOR

CONTRIBUTOR

COPYRIGHT AND LICENSE

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004