NAME

       Pod::Markdown - Convert POD to Markdown

VERSION

       version 3.005

SYNOPSIS

         # Pod::Simple API is supported.

         # Command line usage: Parse a pod file and print to STDOUT:
         # $ perl -MPod::Markdown -e 'Pod::Markdown->new->filter(@ARGV)' path/to/POD/file > README.md

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

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 ));

   A note on encoding and escaping
       The common Pod::Simple API returns a character string.  If you want Pod::Markdown to
       return encoded octets, there are two attributes to assist: "match_encoding" and
       "output_encoding".

       When an output encoding is requested any characters that are not valid for that encoding
       will be escaped as HTML entities.

       This is not 100% safe, however.

       Markdown escapes all ampersands inside of code spans, so escaping a character as an HTML
       entity inside of a code span will not be correct.  However, with pod's "S" and "E"
       sequences it is possible to end up with high-bit characters inside of code spans.

       So, while "output_encoding => 'ascii'" can work, it is not recommended.  For these reasons
       (and more), "UTF-8" is the default, fallback encoding (when one is required).

       If you prefer HTML entities over literal characters you can use "html_encode_chars" which
       will only operate outside of code spans (where it is safe).

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

           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.

   html_encode_chars
       A string of characters to encode as html entities (using "encode_entities" in
       HTML::Entities if available, falling back to numeric entities if not).

       Possible values:

       •   A value of 1 will use the default set of characters from HTML::Entities (control
           chars, high-bit chars, and "<&>"'").

       •   A false value will disable.

       •   Any other value is used as a string of characters (like a regular expression character
           class).

       By default this is disabled and literal characters will be in the output stream.  If you
       specify a desired "output_encoding" any characters not valid for that encoding will be
       HTML entity encoded.

       Note that Markdown requires ampersands ("&") and left angle brackets ("<") to be entity-
       encoded if they could otherwise be interpreted as html entities.  If this attribute is
       configured to encode those characters, they will always be encoded.  If not, the module
       will make an effort to only encode the ones required, so there will be less html noise in
       the output.

   match_encoding
       Boolean: If true, use the "=encoding" of the input pod as the encoding for the output.

       If no encoding is specified, Pod::Simple will guess the encoding if it sees a high-bit
       character.

       If no encoding is guessed (or the specified encoding is unusable), "output_encoding" will
       be used if it was specified.  Otherwise "UTF-8" will be used.

       This attribute is not recommended but is provided for consistency with other pod
       converters.

       Defaults to false.

   output_encoding
       The encoding to use when writing to the output file handle.

       If neither this nor "match_encoding" are specified, a character string will be returned in
       whatever Pod::Simple output method you specified.

   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.

   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

       •   pod2markdown - script included for command line usage

       •   Pod::Simple - Super class that handles Pod parsing

       •   perlpod - For writing POD

       •   perlpodspec - For parsing POD

       •   <http://daringfireball.net/projects/markdown/syntax> - Markdown spec

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.

       •   MetaCPAN

           A modern, open-source CPAN search engine, useful to view POD in HTML format.

           <http://metacpan.org/release/Pod-Markdown>

   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
       <https://rt.cpan.org/Public/Bug/Report.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

       •   Marcel Gruenauer <marcel@cpan.org>

       •   Victor Moral <victor@taquiones.net>

       •   Ryan C. Thompson <rct at thompsonclan d0t org>

       •   Aristotle Pagaltzis <pagaltzis@gmx.de>

       •   Randy Stauner <rwstauner@cpan.org>

CONTRIBUTORS

       •   Aristotle Pagaltzis <aristotle@cpan.org>

       •   Cindy Wang (CindyLinz) <cindylinz@gmail.com>

       •   Graham Ollis <plicease@cpan.org>

       •   Mike Covington <mfcovington@gmail.com>

       •   motemen <motemen@cpan.org>

       •   moznion <moznion@cpan.org>

       •   Peter Vereshagin <veresc@cpan.org>

       •   Ryan C. Thompson <rthompson@cpan.org>

       •   Yasutaka ATARASHI <yakex@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2011 by Randy Stauner.

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