/ 
Pod-WikiDoc-0.21
River stage two • 1 direct dependent • 22 total dependents
/ Pod::WikiDoc

NAME

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

VERSION

version 0.21

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

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/dagolden/pod-wikidoc/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

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

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

AUTHOR

David A Golden <dagolden@cpan.org>

CONTRIBUTOR

James E Keenan <jkeenan@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by David A Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004