Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

v2.001

  - Use double-asterisk instead of double-underscore for bold Markdown.
    This allows bold and italic to be nested without confusing parsers.
    Thanks to Mike Covington for the great pull request (gh-9)!
latest commit 0cf43b9b49
Randy Stauner authored April 19, 2014
Octocat-spinner-32 bin Define parse_from* methods for backward compatibility December 15, 2013
Octocat-spinner-32 corpus Test usage examples to ensure backward-compatibility December 13, 2013
Octocat-spinner-32 lib Convert B<> to ** instead of __ to allow nesting with I<> March 31, 2014
Octocat-spinner-32 t Test explicitly that line-starting asterisks are escaped April 19, 2014
Octocat-spinner-32 .gitignore Ignore .build/ and cover_db/ November 17, 2011
Octocat-spinner-32 .mailmap Document url change and bug fixes in change log November 04, 2013
Octocat-spinner-32 .travis.yml Ensure travis has IO::Scalar installed for tests January 01, 2014
Octocat-spinner-32 Changes v2.001 April 19, 2014
Octocat-spinner-32 README.mkdn v2.001 April 19, 2014
Octocat-spinner-32 dist.ini Remove references to unused Pod::ParseLink December 15, 2013
README.mkdn

NAME

Pod::Markdown - Convert POD to Markdown

VERSION

version 2.001

SYNOPSIS

# Pod::Simple API is supported.

# Parse a pod file and print to STDOUT:
Pod::Markdown->new->filter($pod_file);

# Work with strings:
my $markdown;
my $parser = Pod::Markdown->new;
$parser->output_string(\$markdown);
$parser->parse_string_document($pod_string);

# See Pod::Simple docs for more.

# Legacy (Pod::Parser-based) API is supported for backward compatibility:
my $parser = Pod::Markdown->new;
$parser->parse_from_filehandle(\*STDIN);
print $parser->as_markdown;

DESCRIPTION

This module uses Pod::Simple to convert POD to Markdown.

Literal characters in Pod that are special in Markdown (like *asterisks*) are backslash-escaped when appropriate.

By default markdown and html formatted regions are accepted. Regions of markdown will be passed through unchanged. Regions of html will be placed inside a <div> tag so that markdown characters won't be processed. Regions of :markdown or :html will be processed as POD and included. To change which regions are accepted use the Pod::Simple API:

my $parser = Pod::Markdown->new;
$parser->unaccept_targets(qw( markdown html ));

METHODS

new

Pod::Markdown->new(%options);

The constructor accepts the following named arguments:

  • man_url_prefix

    Alters the man page urls that are created from L<> codes.

    The default is http://man.he.net/man.

  • perldoc_url_prefix

    Alters the perldoc urls that are created from L<> codes. Can be:

    • metacpan (shortcut for https://metacpan.org/pod/)
    • sco (shortcut for http://search.cpan.org/perldoc?)
    • any url

    The default is metacpan.

    Pod::Markdown->new(perldoc_url_prefix => 'http://localhost/perl/pod');
    
  • perldoc_fragment_format

    Alters the format of the url fragment for any L<> links that point to a section of an external document (["section" in name](https://metacpan.org/pod/name#section)). The default will be chosen according to the destination "perldoc_url_prefix". Alternatively you can specify one of the following:

    • metacpan
    • sco
    • pod_simple_xhtml
    • pod_simple_html
    • A code ref

    The code ref can expect to receive two arguments: the parser object ($self) and the section text. For convenience the topic variable ($_) is also set to the section text:

    perldoc_fragment_format => sub { s/\W+/-/g; }
    
  • markdown_fragment_format

    Alters the format of the url fragment for any L<> links that point to an internal section of this document (["section"](#section)).

    Unfortunately the format of the id attributes produced by whatever system translates the markdown into html is unknown at the time the markdown is generated so we do some simple clean up.

    Note: markdown_fragment_format and perldoc_fragment_format accept the same values: a (shortcut to a) method name or a code ref.

  • include_meta_tags

    Specifies whether or not to print author/title meta tags at the top of the document. Default is false.

man_url_prefix

Returns the url prefix in use for man pages.

perldoc_url_prefix

Returns the url prefix in use (after resolving shortcuts to urls).

perldoc_fragment_format

Returns the coderef or format name used to format a url fragment to a section in an external document.

markdown_fragment_format

Returns the coderef or format name used to format a url fragment to an internal section in this document.

include_meta_tags

Returns the boolean value indicating whether or not meta tags will be printed.

as_markdown

Returns the parsed POD as Markdown. Takes named arguments. If the with_meta argument is given a positive value, meta tags are generated as well.

format_man_url

Used internally to create a url (using "man_url_prefix") from a string like man(1).

format_perldoc_url

# With $name and section being the two parts of L<name/section>.
my $url = $parser->format_perldoc_url($name, $section);

Used internally to create a url from the name (of a module or script) and a possible section (heading).

The format of the url fragment (when pointing to a section in a document) varies depending on the destination url so "perldoc_fragment_format" is used (which can be customized).

If the module name portion of the link is blank then the section is treated as an internal fragment link (to a section of the generated markdown document) and "markdown_fragment_format" is used (which can be customized).

format_fragment_markdown

Format url fragment for an internal link by replacing non-word characters with dashes.

format_fragment_pod_simple_xhtml

Format url fragment like "idify" in Pod::Simple::XHTML.

format_fragment_pod_simple_html

Format url fragment like "section_name_tidy" in Pod::Simple::HTML.

format_fragment_metacpan

Format fragment for metacpan.org (uses "format_fragment_pod_simple_xhtml").

format_fragment_sco

Format fragment for search.cpan.org (uses "format_fragment_pod_simple_html").

SEE ALSO

SUPPORT

Perldoc

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

perldoc Pod::Markdown

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Bugs / Feature Requests

Please report any bugs or feature requests by email to bug-pod-markdown at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pod-Markdown. You will be automatically notified of any progress on the request by the system.

Source Code

https://github.com/rwstauner/Pod-Markdown

git clone https://github.com/rwstauner/Pod-Markdown.git

AUTHORS

CONTRIBUTORS

COPYRIGHT AND LICENSE

This software is copyright (c) 2004 by Marcel Gruenauer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Something went wrong with that request. Please try again.