Pod::Markdown(3pm)

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.101
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   html_encode_chars
146       A string of characters to encode as html entities (using
147       "encode_entities" in HTML::Entities if available, falling back to
148       numeric entities if not).
149
150       Possible values:
151
152       ·   A value of 1 will use the default set of characters from
153           HTML::Entities (control chars, high-bit chars, and "<&>"'").
154
155       ·   A false value will disable.
156
157       ·   Any other value is used as a string of characters (like a regular
158           expression character class).
159
160       By default this is disabled and literal characters will be in the
161       output stream.  If you specify a desired "output_encoding" any
162       characters not valid for that encoding will be HTML entity encoded.
163
164       Note that Markdown requires ampersands ("&") and left angle brackets
165       ("<") to be entity-encoded if they could otherwise be interpreted as
166       html entities.  If this attribute is configured to encode those
167       characters, they will always be encoded.  If not, the module will make
168       an effort to only encode the ones required, so there will be less html
169       noise in the output.
170
171   match_encoding
172       Boolean: If true, use the "=encoding" of the input pod as the encoding
173       for the output.
174
175       If no encoding is specified, Pod::Simple will guess the encoding if it
176       sees a high-bit character.
177
178       If no encoding is guessed (or the specified encoding is unusable),
179       "output_encoding" will be used if it was specified.  Otherwise "UTF-8"
180       will be used.
181
182       This attribute is not recommended but is provided for consistency with
183       other pod converters.
184
185       Defaults to false.
186
187   output_encoding
188       The encoding to use when writing to the output file handle.
189
190       If neither this nor "match_encoding" are specified, a character string
191       will be returned in whatever Pod::Simple output method you specified.
192
193   local_module_re
194       Returns the regular expression used to determine local modules.
195
196   local_module_url_prefix
197       Returns the url prefix in use for local modules.
198
199   man_url_prefix
200       Returns the url prefix in use for man pages.
201
202   perldoc_url_prefix
203       Returns the url prefix in use (after resolving shortcuts to urls).
204
205   perldoc_fragment_format
206       Returns the coderef or format name used to format a url fragment to a
207       section in an external document.
208
209   markdown_fragment_format
210       Returns the coderef or format name used to format a url fragment to an
211       internal section in this document.
212
213   include_meta_tags
214       Returns the boolean value indicating whether or not meta tags will be
215       printed.
216
217   format_man_url
218       Used internally to create a url (using "man_url_prefix") from a string
219       like man(1).
220
221   format_perldoc_url
222           # With $name and section being the two parts of L<name/section>.
223           my $url = $parser->format_perldoc_url($name, $section);
224
225       Used internally to create a url from the name (of a module or script)
226       and a possible section (heading).
227
228       The format of the url fragment (when pointing to a section in a
229       document) varies depending on the destination url so
230       "perldoc_fragment_format" is used (which can be customized).
231
232       If the module name portion of the link is blank then the section is
233       treated as an internal fragment link (to a section of the generated
234       markdown document) and "markdown_fragment_format" is used (which can be
235       customized).
236
237   format_fragment_markdown
238       Format url fragment for an internal link by replacing non-word
239       characters with dashes.
240
241   format_fragment_pod_simple_xhtml
242       Format url fragment like "idify" in Pod::Simple::XHTML.
243
244   format_fragment_pod_simple_html
245       Format url fragment like "section_name_tidy" in Pod::Simple::HTML.
246
247   format_fragment_metacpan
248       Format fragment for metacpan.org (uses
249       "format_fragment_pod_simple_xhtml").
250
251   format_fragment_sco
252       Format fragment for search.cpan.org (uses
253       "format_fragment_pod_simple_html").
254
255   is_local_module
256       Uses "local_module_re" to determine if passed module is a "local"
257       module.
258

SUPPORT

272   Perldoc
273       You can find documentation for this module with the perldoc command.
274
275         perldoc Pod::Markdown
276
277   Websites
278       The following websites have more information about this module, and may
279       be of help to you. As always, in addition to those websites please use
280       your favorite search engine to discover more resources.
281
282       ·   MetaCPAN
283
284           A modern, open-source CPAN search engine, useful to view POD in
285           HTML format.
286
287           <https://metacpan.org/release/Pod-Markdown>
288
289   Bugs / Feature Requests
290       Please report any bugs or feature requests by email to
291       "bug-pod-markdown at rt.cpan.org", or through the web interface at
292       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Pod-Markdown>. You
293       will be automatically notified of any progress on the request by the
294       system.
295
296   Source Code
297       <https://github.com/rwstauner/Pod-Markdown>
298
299         git clone https://github.com/rwstauner/Pod-Markdown.git
300

AUTHORS

302       ·   Marcel Gruenauer <marcel@cpan.org>
303
304       ·   Victor Moral <victor@taquiones.net>
305
306       ·   Ryan C. Thompson <rct at thompsonclan d0t org>
307
308       ·   Aristotle Pagaltzis <pagaltzis@gmx.de>
309
310       ·   Randy Stauner <rwstauner@cpan.org>
311

CONTRIBUTORS

313       ·   Aristotle Pagaltzis <aristotle@cpan.org>
314
315       ·   Cindy Wang (CindyLinz) <cindylinz@gmail.com>
316
317       ·   Graham Ollis <plicease@cpan.org>
318
319       ·   Mike Covington <mfcovington@gmail.com>
320
321       ·   motemen <motemen@cpan.org>
322
323       ·   moznion <moznion@cpan.org>
324
325       ·   Peter Vereshagin <veresc@cpan.org>
326
327       ·   Ryan C. Thompson <rthompson@cpan.org>
328
329       ·   Yasutaka ATARASHI <yakex@cpan.org>
330

COPYRIGHT AND LICENSE

332       This software is copyright (c) 2011 by Randy Stauner.
333
334       This is free software; you can redistribute it and/or modify it under
335       the same terms as the Perl 5 programming language system itself.
336
337
338
339perl v5.28.0                      2018-08-06                  Pod::Markdown(3)