1Pod::Markdown(3) User Contributed Perl Documentation Pod::Markdown(3)
2
6 Pod::Markdown - Convert POD to Markdown
7
9 version 3.300
10
12 # Pod::Simple API is supported.
13 # Command line usage: Parse a pod file and print to STDOUT:
15 # $ perl -MPod::Markdown -e 'Pod::Markdown->new->filter(@ARGV)' path/to/POD/file > README.md
16 # Work with strings:
18 my $markdown;
19 my $parser = Pod::Markdown->new;
20 $parser->output_string(\$markdown);
21 $parser->parse_string_document($pod_string);
22 # See Pod::Simple docs for more.
24
26 This module uses Pod::Simple to convert POD to Markdown.
27 Literal characters in Pod that are special in Markdown (like
29 *asterisks*) are backslash-escaped when appropriate.
30 By default "markdown" and "html" formatted regions are accepted.
32 Regions of "markdown" will be passed through unchanged. Regions of
33 "html" will be placed inside a "<div>" tag so that markdown characters
34 won't be processed. Regions of ":markdown" or ":html" will be
35 processed as POD and included. To change which regions are accepted
36 use the Pod::Simple API:
37 my $parser = Pod::Markdown->new;
39 $parser->unaccept_targets(qw( markdown html ));
40 A note on encoding and escaping
42 The common Pod::Simple API returns a character string. If you want
43 Pod::Markdown to return encoded octets, there are two attributes to
44 assist: "match_encoding" and "output_encoding".
45 When an output encoding is requested any characters that are not valid
47 for that encoding will be escaped as HTML entities.
48 This is not 100% safe, however.
50 Markdown escapes all ampersands inside of code spans, so escaping a
52 character as an HTML entity inside of a code span will not be correct.
53 However, with pod's "S" and "E" sequences it is possible to end up with
54 high-bit characters inside of code spans.
55 So, while "output_encoding => 'ascii'" can work, it is not recommended.
57 For these reasons (and more), "UTF-8" is the default, fallback encoding
58 (when one is required).
59 If you prefer HTML entities over literal characters you can use
61 "html_encode_chars" which will only operate outside of code spans
62 (where it is safe).
63
65 new
66 Pod::Markdown->new(%options);
67 The constructor accepts the following named arguments:
69 • "local_module_url_prefix"
71 Alters the perldoc urls that are created from "L<>" codes when the
73 module is a "local" module ("Local::*" or "Foo_Corp::*" (see
74 perlmodlib)).
75 The default is to use "perldoc_url_prefix".
77 • "local_module_re"
79 Alternate regular expression for determining "local" modules.
81 Default is "our $LOCAL_MODULE_RE = qr/^(Local::|\w*?_\w*)/".
82 • "man_url_prefix"
84 Alters the man page urls that are created from "L<>" codes.
86 The default is "http://man.he.net/man".
88 • "perldoc_url_prefix"
90 Alters the perldoc urls that are created from "L<>" codes. Can be:
92 • "metacpan" (shortcut for "https://metacpan.org/pod/")
94 • "sco" (shortcut for "http://search.cpan.org/perldoc?")
96 • any url
98 The default is "metacpan".
100 Pod::Markdown->new(perldoc_url_prefix => 'http://localhost/perl/pod');
102 • "perldoc_fragment_format"
104 Alters the format of the url fragment for any "L<>" links that
106 point to a section of an external document (""section" in name").
107 The default will be chosen according to the destination
108 "perldoc_url_prefix". Alternatively you can specify one of the
109 following:
110 • "metacpan"
112 • "sco"
114 • "pod_simple_xhtml"
116 • "pod_simple_html"
118 • A code ref
120 The code ref can expect to receive two arguments: the parser object
122 ($self) and the section text. For convenience the topic variable
123 ($_) is also set to the section text:
124 perldoc_fragment_format => sub { s/\W+/-/g; }
126 • "markdown_fragment_format"
128 Alters the format of the url fragment for any "L<>" links that
130 point to an internal section of this document ("section").
131 Unfortunately the format of the id attributes produced by whatever
133 system translates the markdown into html is unknown at the time the
134 markdown is generated so we do some simple clean up.
135 Note: "markdown_fragment_format" and "perldoc_fragment_format"
137 accept the same values: a (shortcut to a) method name or a code
138 ref.
139 • "include_meta_tags"
141 Specifies whether or not to print author/title meta tags at the top
143 of the document. Default is false.
144 • "escape_url"
146 Specifies whether or not to escape URLs. Default is true. It is
148 not recommended to turn this off with an empty
149 local_module_url_prefix, as the resulting local module URLs can be
150 confused with IPv6 addresses by web browsers.
151 html_encode_chars
153 A string of characters to encode as html entities (using
154 "encode_entities" in HTML::Entities if available, falling back to
155 numeric entities if not).
156 Possible values:
158 • A value of 1 will use the default set of characters from
160 HTML::Entities (control chars, high-bit chars, and "<&>"'").
161 • A false value will disable.
163 • Any other value is used as a string of characters (like a regular
165 expression character class).
166 By default this is disabled and literal characters will be in the
168 output stream. If you specify a desired "output_encoding" any
169 characters not valid for that encoding will be HTML entity encoded.
170 Note that Markdown requires ampersands ("&") and left angle brackets
172 ("<") to be entity-encoded if they could otherwise be interpreted as
173 html entities. If this attribute is configured to encode those
174 characters, they will always be encoded. If not, the module will make
175 an effort to only encode the ones required, so there will be less html
176 noise in the output.
177 match_encoding
179 Boolean: If true, use the "=encoding" of the input pod as the encoding
180 for the output.
181 If no encoding is specified, Pod::Simple will guess the encoding if it
183 sees a high-bit character.
184 If no encoding is guessed (or the specified encoding is unusable),
186 "output_encoding" will be used if it was specified. Otherwise "UTF-8"
187 will be used.
188 This attribute is not recommended but is provided for consistency with
190 other pod converters.
191 Defaults to false.
193 output_encoding
195 The encoding to use when writing to the output file handle.
196 If neither this nor "match_encoding" are specified, a character string
198 will be returned in whatever Pod::Simple output method you specified.
199 local_module_re
201 Returns the regular expression used to determine local modules.
202 local_module_url_prefix
204 Returns the url prefix in use for local modules.
205 man_url_prefix
207 Returns the url prefix in use for man pages.
208 perldoc_url_prefix
210 Returns the url prefix in use (after resolving shortcuts to urls).
211 perldoc_fragment_format
213 Returns the coderef or format name used to format a url fragment to a
214 section in an external document.
215 markdown_fragment_format
217 Returns the coderef or format name used to format a url fragment to an
218 internal section in this document.
219 include_meta_tags
221 Returns the boolean value indicating whether or not meta tags will be
222 printed.
223 escape_url
225 Returns the boolean value indicating whether or not URLs should be
226 escaped.
227 format_man_url
229 Used internally to create a url (using "man_url_prefix") from a string
230 like man(1).
231 format_perldoc_url
233 # With $name and section being the two parts of L<name/section>.
234 my $url = $parser->format_perldoc_url($name, $section);
235 Used internally to create a url from the name (of a module or script)
237 and a possible section (heading).
238 The format of the url fragment (when pointing to a section in a
240 document) varies depending on the destination url so
241 "perldoc_fragment_format" is used (which can be customized).
242 If the module name portion of the link is blank then the section is
244 treated as an internal fragment link (to a section of the generated
245 markdown document) and "markdown_fragment_format" is used (which can be
246 customized).
247 format_fragment_markdown
249 Format url fragment for an internal link by replacing non-word
250 characters with dashes.
251 format_fragment_pod_simple_xhtml
253 Format url fragment like "idify" in Pod::Simple::XHTML.
254 format_fragment_pod_simple_html
256 Format url fragment like "section_name_tidy" in Pod::Simple::HTML.
257 format_fragment_metacpan
259 Format fragment for metacpan.org (uses
260 "format_fragment_pod_simple_xhtml").
261 format_fragment_sco
263 Format fragment for search.cpan.org (uses
264 "format_fragment_pod_simple_html").
265 is_local_module
267 Uses "local_module_re" to determine if passed module is a "local"
268 module.
269
271 • pod2markdown - script included for command line usage
272 • Pod::Simple - Super class that handles Pod parsing
274 • perlpod - For writing POD
276 • perlpodspec - For parsing POD
278 • <http://daringfireball.net/projects/markdown/syntax> - Markdown
280 spec
281
283 Perldoc
284 You can find documentation for this module with the perldoc command.
285 perldoc Pod::Markdown
287 Websites
289 The following websites have more information about this module, and may
290 be of help to you. As always, in addition to those websites please use
291 your favorite search engine to discover more resources.
292 • MetaCPAN
294 A modern, open-source CPAN search engine, useful to view POD in
296 HTML format.
297 <https://metacpan.org/release/Pod-Markdown>
299 Bugs / Feature Requests
301 Please report any bugs or feature requests by email to
302 "bug-pod-markdown at rt.cpan.org", or through the web interface at
303 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Pod-Markdown>. You
304 will be automatically notified of any progress on the request by the
305 system.
306 Source Code
308 <https://github.com/rwstauner/Pod-Markdown>
309 git clone https://github.com/rwstauner/Pod-Markdown.git
311
313 • Marcel Gruenauer <marcel@cpan.org>
314 • Victor Moral <victor@taquiones.net>
316 • Ryan C. Thompson <rct at thompsonclan d0t org>
318 • Aristotle Pagaltzis <pagaltzis@gmx.de>
320 • Randy Stauner <rwstauner@cpan.org>
322
324 • Aristotle Pagaltzis <aristotle@cpan.org>
325 • Cindy Wang (CindyLinz) <cindylinz@gmail.com>
327 • Graham Ollis <plicease@cpan.org>
329 • Mike Covington <mfcovington@gmail.com>
331 • motemen <motemen@cpan.org>
333 • moznion <moznion@cpan.org>
335 • Peter Vereshagin <veresc@cpan.org>
337 • Ryan C. Thompson <rthompson@cpan.org>
339 • Yasutaka ATARASHI <yakex@cpan.org>
341
343 This software is copyright (c) 2011 by Randy Stauner.
344 This is free software; you can redistribute it and/or modify it under
346 the same terms as the Perl 5 programming language system itself.
347perl v5.36.0 2023-01-20 Pod::Markdown(3)