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

VERSION
    This documentation refers to version 0.18.

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

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
    *wikidoc*) and use Pod::WikiDoc to extract it and convert it into its
    corresponding Pod as a separate ".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 "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
  "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:

    *   "comment_blocks": if true, Pod::WikiDoc will scan for wikidoc in
        comment blocks. Default is false.

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

    *   "keywords": a hash reference with keywords and values for keyword
        substitution

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

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

  "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 perlpodspec.

    "filter" takes a single, optional argument: a hash reference with the
    following optional keys:

    *   "input": a filename or filehandle to read from. Defaults to STDIN.

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

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

    Given a string with valid Pod and/or wikidoc markup, filter/translate it
    to Pod. Unlike "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.

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

    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
    (\\).

  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

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

         #<--- first column 
 
             sub verbatim {}

  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

  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

  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.

  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.

  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.

  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 } }

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

  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> 

  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 "new()".
    If the keyword is unknown or the value is undefined, the keyword will be
    passed through unchanged.

         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.

BUGS
    Please report bugs or feature requests using the CPAN Request Tracker.
    Bugs can be submitted using the web interface at
    <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.

AUTHOR
    David A. Golden (DAGOLDEN)

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 <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.