Pod::Markdown(3)

📦
version 3.400.0 · 8 versions
, in opensuse-leap 16.0

🌸 Pod::Markdown — the manual, but make it make sense 💅

okay so bestie, the page you're looking at is Pod::Markdown(3) — a User Contributed Perl Documentation page, and honestly? It's a whole vibe. Let me walk you through it ✨

🎀 NAME 🎀

Pod::Markdown — Convert POD to Markdown. That's it, that's the whole name, and it ate 💅

⭐ VERSION ⭐

version 3.400 — iconic, no notes 🫶

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

like, look at that command-line one-liner. <pink>obsessed</pink>. She's doing the most with the least, and honestly? Same 😌

💖 DESCRIPTION 💖

Okay so the tea: this module uses Pod::Simple to convert POD to Markdown. Simple as that, fr fr.

Literal characters in Pod that are special in Markdown (like *asterisks*) get backslash-escaped when appropriate — so your asterisks stay asterisks and don't start doing italic main character energy on you 💀

By default, markdown and html formatted regions are accepted. Here's the breakdown:

  • Regions of markdown get passed through unchanged — no touchy 🫶
  • Regions of html get placed inside a <div> tag, so that markdown characters won't be processed (protective queen behavior 💅)
  • Regions of :markdown or :html get processed as POD and included

Wanna change which regions are accepted? Use the Pod::Simple API, bestie:

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 you: 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. Like, at all. Read on 💀

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. But with pod's S and E sequences it's possible to end up with high-bit characters inside of code spans. Messy, I know 😭

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). Slay 🌈

🩷 METHODS 🩷

🎀 new 🎀

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

The constructor accepts the following named arguments — buckle up, there's a few 👑

  • local_module_url_prefix — Alters the perldoc urls that are created from L<> codes when the module is a "local" module (Local::* or Foo_Corp::* (see perlmodlib)). The default is to use perldoc_url_prefix.
  • local_module_re — Alternate regular expression for determining "local" modules. Default is our $LOCAL_MODULE_RE = qr/^(Local::|\w*?_\w*)/.
  • 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:

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.
  • escape_url — Specifies whether or not to escape URLs. Default is true. It is not recommended to turn this off with an empty local_module_url_prefix, as the resulting local module URLs can be confused with IPv6 addresses by web browsers 😭 (imagine getting your README mistaken for an IP address, couldn't be me 💀)

🦋 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. Considerate king behavior 👑

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

🍓 local_module_re 🍓

Returns the regular expression used to determine local modules.

🍓 local_module_url_prefix 🍓

Returns the url prefix in use for local modules.

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

🍓 escape_url 🍓

Returns the boolean value indicating whether or not URLs should be escaped.

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

👑 is_local_module 👑

Uses local_module_re to determine if passed module is a "local" module.

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

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

<https://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. Bestie support line, honestly 🫶

🎀 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>
  • Johannes Schauer Marin Rodrigues <josch@mister-muffin.de>
  • 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>

okay so legal stuff, bestie, but it's short and sweet, promise 🫶

This software is copyright (c) 2011 by Randy Stauner. Like, that's the whole ownership vibe, periodt.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Slay — literally the same license as Perl 5, no extra drama, no weird fine print, we love a clean license moment ✨

🎀 so go forth, share it, remix it, whatever — just keep those same Perl 5 terms and everybody's happy 💅

and that's a wrap on the whole page, bestie!! 😭💖 this beauty comes from perl v5.42.0 and it's dated 2024-03-08 — iconic, timeless, lowkey a little vintage 🌸 go forth and convert some Pod to Markdown, you absolute main character 👑🦋

📦 where this page comes from