1Pod::Markdown(3)      User Contributed Perl Documentation     Pod::Markdown(3)
2
3
4

NAME

6       Pod::Markdown - Convert POD to Markdown
7

VERSION

9       version 3.300
10

SYNOPSIS

12         # Pod::Simple API is supported.
13
14         # 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
17         # 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
23         # See Pod::Simple docs for more.
24

DESCRIPTION

26       This module uses Pod::Simple to convert POD to Markdown.
27
28       Literal characters in Pod that are special in Markdown (like
29       *asterisks*) are backslash-escaped when appropriate.
30
31       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
38         my $parser = Pod::Markdown->new;
39         $parser->unaccept_targets(qw( markdown html ));
40
41   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
46       When an output encoding is requested any characters that are not valid
47       for that encoding will be escaped as HTML entities.
48
49       This is not 100% safe, however.
50
51       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
56       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
60       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

METHODS

65   new
66         Pod::Markdown->new(%options);
67
68       The constructor accepts the following named arguments:
69
70       •   "local_module_url_prefix"
71
72           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
76           The default is to use "perldoc_url_prefix".
77
78       •   "local_module_re"
79
80           Alternate regular expression for determining "local" modules.
81           Default is "our $LOCAL_MODULE_RE = qr/^(Local::|\w*?_\w*)/".
82
83       •   "man_url_prefix"
84
85           Alters the man page urls that are created from "L<>" codes.
86
87           The default is "http://man.he.net/man".
88
89       •   "perldoc_url_prefix"
90
91           Alters the perldoc urls that are created from "L<>" codes.  Can be:
92
93           •   "metacpan" (shortcut for "https://metacpan.org/pod/")
94
95           •   "sco" (shortcut for "http://search.cpan.org/perldoc?")
96
97           •   any url
98
99           The default is "metacpan".
100
101               Pod::Markdown->new(perldoc_url_prefix => 'http://localhost/perl/pod');
102
103       •   "perldoc_fragment_format"
104
105           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
111           •   "metacpan"
112
113           •   "sco"
114
115           •   "pod_simple_xhtml"
116
117           •   "pod_simple_html"
118
119           •   A code ref
120
121           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
125             perldoc_fragment_format => sub { s/\W+/-/g; }
126
127       •   "markdown_fragment_format"
128
129           Alters the format of the url fragment for any "L<>" links that
130           point to an internal section of this document ("section").
131
132           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
136           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
140       •   "include_meta_tags"
141
142           Specifies whether or not to print author/title meta tags at the top
143           of the document.  Default is false.
144
145       •   "escape_url"
146
147           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
152   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
157       Possible values:
158
159       •   A value of 1 will use the default set of characters from
160           HTML::Entities (control chars, high-bit chars, and "<&>"'").
161
162       •   A false value will disable.
163
164       •   Any other value is used as a string of characters (like a regular
165           expression character class).
166
167       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
171       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
178   match_encoding
179       Boolean: If true, use the "=encoding" of the input pod as the encoding
180       for the output.
181
182       If no encoding is specified, Pod::Simple will guess the encoding if it
183       sees a high-bit character.
184
185       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
189       This attribute is not recommended but is provided for consistency with
190       other pod converters.
191
192       Defaults to false.
193
194   output_encoding
195       The encoding to use when writing to the output file handle.
196
197       If neither this nor "match_encoding" are specified, a character string
198       will be returned in whatever Pod::Simple output method you specified.
199
200   local_module_re
201       Returns the regular expression used to determine local modules.
202
203   local_module_url_prefix
204       Returns the url prefix in use for local modules.
205
206   man_url_prefix
207       Returns the url prefix in use for man pages.
208
209   perldoc_url_prefix
210       Returns the url prefix in use (after resolving shortcuts to urls).
211
212   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
216   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
220   include_meta_tags
221       Returns the boolean value indicating whether or not meta tags will be
222       printed.
223
224   escape_url
225       Returns the boolean value indicating whether or not URLs should be
226       escaped.
227
228   format_man_url
229       Used internally to create a url (using "man_url_prefix") from a string
230       like man(1).
231
232   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
236       Used internally to create a url from the name (of a module or script)
237       and a possible section (heading).
238
239       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
243       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
248   format_fragment_markdown
249       Format url fragment for an internal link by replacing non-word
250       characters with dashes.
251
252   format_fragment_pod_simple_xhtml
253       Format url fragment like "idify" in Pod::Simple::XHTML.
254
255   format_fragment_pod_simple_html
256       Format url fragment like "section_name_tidy" in Pod::Simple::HTML.
257
258   format_fragment_metacpan
259       Format fragment for metacpan.org (uses
260       "format_fragment_pod_simple_xhtml").
261
262   format_fragment_sco
263       Format fragment for search.cpan.org (uses
264       "format_fragment_pod_simple_html").
265
266   is_local_module
267       Uses "local_module_re" to determine if passed module is a "local"
268       module.
269

SEE ALSO

271       •   pod2markdown - script included for command line usage
272
273       •   Pod::Simple - Super class that handles Pod parsing
274
275       •   perlpod - For writing POD
276
277       •   perlpodspec - For parsing POD
278
279       •   <http://daringfireball.net/projects/markdown/syntax> - Markdown
280           spec
281

SUPPORT

283   Perldoc
284       You can find documentation for this module with the perldoc command.
285
286         perldoc Pod::Markdown
287
288   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
293       •   MetaCPAN
294
295           A modern, open-source CPAN search engine, useful to view POD in
296           HTML format.
297
298           <https://metacpan.org/release/Pod-Markdown>
299
300   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
307   Source Code
308       <https://github.com/rwstauner/Pod-Markdown>
309
310         git clone https://github.com/rwstauner/Pod-Markdown.git
311

AUTHORS

313       •   Marcel Gruenauer <marcel@cpan.org>
314
315       •   Victor Moral <victor@taquiones.net>
316
317       •   Ryan C. Thompson <rct at thompsonclan d0t org>
318
319       •   Aristotle Pagaltzis <pagaltzis@gmx.de>
320
321       •   Randy Stauner <rwstauner@cpan.org>
322

CONTRIBUTORS

324       •   Aristotle Pagaltzis <aristotle@cpan.org>
325
326       •   Cindy Wang (CindyLinz) <cindylinz@gmail.com>
327
328       •   Graham Ollis <plicease@cpan.org>
329
330       •   Mike Covington <mfcovington@gmail.com>
331
332       •   motemen <motemen@cpan.org>
333
334       •   moznion <moznion@cpan.org>
335
336       •   Peter Vereshagin <veresc@cpan.org>
337
338       •   Ryan C. Thompson <rthompson@cpan.org>
339
340       •   Yasutaka ATARASHI <yakex@cpan.org>
341
343       This software is copyright (c) 2011 by Randy Stauner.
344
345       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.
347
348
349
350perl v5.32.1                      2021-01-27                  Pod::Markdown(3)
Impressum