Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pod::Markdown(3)      User Contributed Perl Documentation     Pod::Markdown(3)

NAME
       Pod::Markdown - Convert POD to Markdown

VERSION
       version 3.300

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:

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

       o   "local_module_re"

	   Alternate regular expression	for determining	"local"	modules.
	   Default is "our $LOCAL_MODULE_RE = qr/^(Local::|\w*?_\w*)/".

       o   "man_url_prefix"

	   Alters the man page urls that are created from "L<>"	codes.

	   The default is "http://man.he.net/man".

       o   "perldoc_url_prefix"

	   Alters the perldoc urls that	are created from "L<>" codes.  Can be:

	   o   "metacpan" (shortcut for	"https://metacpan.org/pod/")

	   o   "sco" (shortcut for "http://search.cpan.org/perldoc?")

	   o   any url

	   The default is "metacpan".

	       Pod::Markdown->new(perldoc_url_prefix =>	'http://localhost/perl/pod');

       o   "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:

	   o   "metacpan"

	   o   "sco"

	   o   "pod_simple_xhtml"

	   o   "pod_simple_html"

	   o   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; }

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

       o   "include_meta_tags"

	   Specifies whether or	not to print author/title meta tags at the top
	   of the document.  Default is	false.

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

   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:

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

       o   A false value will disable.

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

   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
       o   pod2markdown	- script included for command line usage

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

       o   perlpod - For writing POD

       o   perlpodspec - For parsing POD

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

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

   Source Code
       <https://github.com/rwstauner/Pod-Markdown>

	 git clone https://github.com/rwstauner/Pod-Markdown.git

AUTHORS
       o   Marcel Gruenauer <marcel@cpan.org>

       o   Victor Moral	<victor@taquiones.net>

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

       o   Aristotle Pagaltzis <pagaltzis@gmx.de>

       o   Randy Stauner <rwstauner@cpan.org>

CONTRIBUTORS
       o   Aristotle Pagaltzis <aristotle@cpan.org>

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

       o   Graham Ollis	<plicease@cpan.org>

       o   Mike	Covington <mfcovington@gmail.com>

       o   motemen <motemen@cpan.org>

       o   moznion <moznion@cpan.org>

       o   Peter Vereshagin <veresc@cpan.org>

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

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

perl v5.32.1			  2020-10-31		      Pod::Markdown(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | SUPPORT | AUTHORS | CONTRIBUTORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Pod::Markdown&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help