.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Pandoc 3pm"
.TH Pandoc 3pm "2023-01-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pandoc \- wrapper for the mighty Pandoc document converter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Pandoc;             # check at first use
\&  use Pandoc 1.12;        # check at compile time
\&  Pandoc\->require(1.12);  # check at run time
\&
\&  # execute pandoc
\&  pandoc \*(Aqinput.md\*(Aq, \-o => \*(Aqoutput.html\*(Aq;
\&  pandoc \-f => \*(Aqhtml\*(Aq, \-t => \*(Aqmarkdown\*(Aq, { in => \e$html, out => \e$md };
\&
\&  # alternative syntaxes
\&  pandoc\->run(\*(Aqinput.md\*(Aq, \-o => \*(Aqoutput.html\*(Aq);
\&  pandoc [ \-f => \*(Aqhtml\*(Aq, \-t => \*(Aqmarkdown\*(Aq ], in => \e$html, out => \e$md;
\&  pandoc [ \-f => \*(Aqhtml\*(Aq, \-t => \*(Aqmarkdown\*(Aq ], { in => \e$html, out => \e$md };
\&
\&  # check executable
\&  pandoc or die "pandoc executable not found";
\&
\&  # check minimum version
\&  pandoc\->version > 1.12 or die "pandoc >= 1.12 required";
\&
\&  # access properties
\&  say pandoc\->bin." ".pandoc\->version;
\&  say "Default user data directory: ".pandoc\->data_dir;
\&  say "Compiled with: ".join(", ", keys %{ pandoc\->libs });
\&  say pandoc\->libs\->{\*(Aqhighlighting\-kate\*(Aq};
\&
\&  # create a new instance with default arguments
\&  my $md2latex = Pandoc\->new(qw(\-f markdown \-t latex \-\-number\-sections));
\&  $md2latex\->run({ in => \e$markdown, out => \e$latex });
\&
\&  # create a new instance with selected executable
\&  my $pandoc = Pandoc\->new(\*(Aqbin/pandoc\*(Aq);
\&  my $pandoc = Pandoc\->new(\*(Aq2.1\*(Aq); # use ~/.pandoc/bin/pandoc\-2.1 if available
\&
\&  # set default arguments on compile time
\&  use Pandoc qw(\-t latex);
\&  use Pandoc qw(/usr/bin/pandoc \-\-number\-sections);
\&  use Pandoc qw(1.16 \-\-number\-sections);
\&
\&  # utility method to convert from string
\&  $latex = pandoc\->convert( \*(Aqmarkdown\*(Aq => \*(Aqlatex\*(Aq, \*(Aq*hello*\*(Aq );
\&
\&  # utility methods to parse abstract syntax tree (requires Pandoc::Elements)
\&  $doc = pandoc\->parse( markdown => \*(Aq*hello* **world!**\*(Aq );
\&  $doc = pandoc\->file( \*(Aqexample.md\*(Aq );
\&  $doc = pandoc\->file;  # read Markdown from STDIN
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a Perl wrapper for John MacFarlane's
Pandoc <http://pandoc.org> document converter.
.SH "INSTALLATION"
.IX Header "INSTALLATION"
This module requires the Perl programming language (>= version 5.14) as
included in most Unix operating systems by default. The recommended method to
install Perl modules is \f(CW\*(C`cpanm\*(C'\fR (see its install
instructions <https://metacpan.org/pod/App::cpanminus#INSTALLATION> if needed):
.PP
.Vb 1
\&  cpanm Pandoc
.Ve
.PP
Installing instruction for Pandoc itself are given at Pandoc
homepage <http://pandoc.org/installing.html>. On Debian-based systems this
module and script pandoc-version can be used to install and update the
pandoc executable with Pandoc::Release:
.PP
.Vb 1
\&  pandoc\-version install
.Ve
.PP
Then add \f(CW\*(C`~/.pandoc/bin\*(C'\fR to your \f(CW\*(C`PATH\*(C'\fR or copy \f(CW\*(C`~/.pandoc/bin/pandoc\*(C'\fR to
a location where it can be executed.
.SH "USAGE"
.IX Header "USAGE"
The utility function pandoc is exported, unless the module is
imported with an empty list (\f(CW\*(C`use Pandoc ();\*(C'\fR). Importing this module with a
version number or a more complex version requirenment (e.g. \f(CW\*(C`use Pandoc
1.13;\*(C'\fR or \f(CW\*(C`use Pandoc \*(Aq>= 1.6, !=1.7\*(C'\fR) will check version number of
pandoc executable instead of version number of this module (see
\&\f(CW$Pandoc::VERSION\fR for the latter). Additional import arguments can be passed
to set the executable location and default arguments of the global Pandoc
instance used by function pandoc.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "pandoc"
.IX Subsection "pandoc"
If called without parameters, this function returns a global instance of class
Pandoc to execute methods, or \f(CW\*(C`undef\*(C'\fR if no pandoc executable was
found. The location and/or name of pandoc executable can be set with
environment variable \f(CW\*(C`PANDOC_PATH\*(C'\fR (set to the string \f(CW\*(C`pandoc\*(C'\fR by default).
.SS "pandoc( ... )"
.IX Subsection "pandoc( ... )"
If called with parameters, this functions runs the pandoc executable configured
at the global instance of class Pandoc (\f(CW\*(C`pandoc\->bin\*(C'\fR). Arguments (given
as array or array reference) are passed as pandoc command line arguments.
Additional options (given as hash or has reference) can control input, output,
and error stream:
.PP
.Vb 5
\&  pandoc @arguments, \e%options;     # ok
\&  pandoc \e@arguments, %options;     # ok
\&  pandoc \e@arguments, \e%options;    # ok
\&  pandoc @arguments;                # ok, if first of @arguments starts with \*(Aq\-\*(Aq
\&  pandoc %options;                  # ok, if %options is not empty
\&
\&  pandoc @arguments, %options;      # not ok!
.Ve
.PP
Returns \f(CW0\fR on success. On error returns the exit code of pandoc executable or
\&\f(CW\*(C`\-1\*(C'\fR if execution failed. If option \f(CW\*(C`throw\*(C'\fR is set, a Pandoc::Error is
thrown instead. The following options are recognized:
.IP "in / out / err" 4
.IX Item "in / out / err"
These options correspond to arguments \f(CW$stdin\fR, \f(CW$stdout\fR, and
\&\f(CW$stderr\fR of IPC::Run3, see there for details.
.IP "binmode_stdin / binmode_stdout / binmode_stderr" 4
.IX Item "binmode_stdin / binmode_stdout / binmode_stderr"
These options correspond to the like-named options to IPC::Run3, see
there for details.
.IP "binmode" 4
.IX Item "binmode"
If defined any binmode_stdin/binmode_stdout/binmode_stderr option which
is undefined will be set to this value.
.IP "throw" 4
.IX Item "throw"
Throw a Pandoc::Error instead returning the exit code on error. Disabled by
default.
.IP "return_if_system_error" 4
.IX Item "return_if_system_error"
Set to negation of option \f(CW\*(C`throw\*(C'\fR by default.
.PP
For convenience the \f(CW\*(C`pandoc\*(C'\fR function (\fIafter\fR checking the \f(CW\*(C`binmode\*(C'\fR
option) checks the contents of any scalar references passed to the
in/out/err options with
\&\fButf8::is_utf8()\fR
and sets the binmode_stdin/binmode_stdout/binmode_stderr options to
\&\f(CW\*(C`:encoding(UTF\-8)\*(C'\fR if the corresponding scalar is marked as \s-1UTF\-8\s0 and
the respective option is undefined. Since all pandoc executable
input/output must be \s-1UTF\-8\s0 encoded this is convenient if you run with
use utf8, as you then don't need to set the binmode options at
all (encode nor decode) when passing input/output scalar
references.
.ie n .SS "pandoc_data_dir( [ @subdirs ] [ $file ] )"
.el .SS "pandoc_data_dir( [ \f(CW@subdirs\fP ] [ \f(CW$file\fP ] )"
.IX Subsection "pandoc_data_dir( [ @subdirs ] [ $file ] )"
Returns the default pandoc data directory which is directory \f(CW\*(C`.pandoc\*(C'\fR in the
home directory for Unix or \f(CW\*(C`pandoc\*(C'\fR directory in \f(CW\*(C`%APPDATA%\*(C'\fR for Windows.
Optional arguments can be given to refer to a specific subdirectory or file.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "new( [ $executable | $version ] [, @arguments ] )"
.el .SS "new( [ \f(CW$executable\fP | \f(CW$version\fP ] [, \f(CW@arguments\fP ] )"
.IX Subsection "new( [ $executable | $version ] [, @arguments ] )"
Create a new instance of class Pandoc or throw an exception if no pandoc
executable was found.  The first argument, if given and not starting with \f(CW\*(C`\-\*(C'\fR,
can be used to set the pandoc executable (\f(CW\*(C`pandoc\*(C'\fR by default).  If a version
is specified the executable is also searched in \f(CW\*(C`~/.pandoc/bin\*(C'\fR, e.g.
\&\f(CW\*(C`~/.pandoc/bin/pandoc\-2.0\*(C'\fR for version \f(CW2.0\fR.  Additional arguments are
passed to the executable on each run.
.PP
Repeated use of this constructor with same arguments is not recommended because
\&\f(CW\*(C`pandoc \-\-version\*(C'\fR is called for every new instance.
.SS "run( ... )"
.IX Subsection "run( ... )"
Execute the pandoc executable with default arguments and optional additional
arguments and options. See function pandoc for usage.
.ie n .SS "convert( $from => $to, $input [, @arguments ] )"
.el .SS "convert( \f(CW$from\fP => \f(CW$to\fP, \f(CW$input\fP [, \f(CW@arguments\fP ] )"
.IX Subsection "convert( $from => $to, $input [, @arguments ] )"
Convert a string in format \f(CW$from\fR to format \f(CW$to\fR. Additional pandoc options
such as \f(CW\*(C`\-N\*(C'\fR and \f(CW\*(C`\-\-standalone\*(C'\fR can be passed. The result is returned
in same utf8 mode (\f(CW\*(C`utf8::is_unicode\*(C'\fR) as the input. To convert from file to
string use method \f(CW\*(C`pandoc\*(C'\fR/\f(CW\*(C`run\*(C'\fR like this and set input/output format via
standard pandoc arguments \f(CW\*(C`\-f\*(C'\fR and \f(CW\*(C`\-t\*(C'\fR:
.PP
.Vb 1
\&  pandoc\->run( $filename, @arguments, { out => \e$string } );
.Ve
.ie n .SS "parse( $from => $input [, @arguments ] )"
.el .SS "parse( \f(CW$from\fP => \f(CW$input\fP [, \f(CW@arguments\fP ] )"
.IX Subsection "parse( $from => $input [, @arguments ] )"
Parse a string in format \f(CW$from\fR to a Pandoc::Document object. Additional
pandoc options such as \f(CW\*(C`\-N\*(C'\fR and \f(CW\*(C`\-\-normalize\*(C'\fR can be passed. This method
requires at least pandoc version 1.12.1 and the Perl module Pandoc::Elements.
.PP
The reverse action is possible with method \f(CW\*(C`to_pandoc\*(C'\fR of Pandoc::Document.
Additional shortcut methods such as \f(CW\*(C`to_html\*(C'\fR are available:
.PP
.Vb 1
\&  $html = pandoc\->parse( \*(Aqmarkdown\*(Aq => \*(Aq# A *section*\*(Aq )\->to_html;
.Ve
.PP
Method \f(CW\*(C`convert\*(C'\fR should be preferred for simple conversions unless you want to
modify or inspect the parsed document in between.
.ie n .SS "file( [ $filename [, @arguments ] ] )"
.el .SS "file( [ \f(CW$filename\fP [, \f(CW@arguments\fP ] ] )"
.IX Subsection "file( [ $filename [, @arguments ] ] )"
Parse from a file (or \s-1STDIN\s0) to a Pandoc::Document object. Additional pandoc
options can be passed, for instance use \s-1HTML\s0 input format (\f(CW\*(C`@arguments = qw(\-f
html)\*(C'\fR) instead of default markdown. This method requires at least pandoc
version 1.12.1 and the Perl module Pandoc::Elements.
.ie n .SS "require( $version_requirement )"
.el .SS "require( \f(CW$version_requirement\fP )"
.IX Subsection "require( $version_requirement )"
Return the Pandoc instance if its version number fulfills a given version
requirement. Throw an error otherwise.  Can also be called as constructor:
\&\f(CW\*(C`Pandoc\->require(...)\*(C'\fR is equivalent to \f(CW\*(C`pandoc\->require\*(C'\fR but
throws a more meaningful error message if no pandoc executable was found.
.ie n .SS "version( [ $version_requirement ] )"
.el .SS "version( [ \f(CW$version_requirement\fP ] )"
.IX Subsection "version( [ $version_requirement ] )"
Return the pandoc version as Pandoc::Version object.  If a version
requirement is given, the method returns undef if the pandoc version does not
fulfill this requirement.  To check whether pandoc is available with a given
minimal version use one of:
.PP
.Vb 2
\&  Pandoc\->require( $minimum_version)                # true or die
\&  pandoc and pandoc\->version( $minimum_version )    # true or false
.Ve
.ie n .SS "bin( [ $executable ] )"
.el .SS "bin( [ \f(CW$executable\fP ] )"
.IX Subsection "bin( [ $executable ] )"
Return or set the pandoc executable. Setting an new executable also updates
version and data_dir by calling \f(CW\*(C`pandoc \-\-version\*(C'\fR.
.ie n .SS "symlink( [ $name ] [ verbose => 0|1 ] )"
.el .SS "symlink( [ \f(CW$name\fP ] [ verbose => 0|1 ] )"
.IX Subsection "symlink( [ $name ] [ verbose => 0|1 ] )"
Create a symlink with given name to the executable and change executable to the
symlink location afterwards. An existing symlink is replaced. If \f(CW$name\fR is an
existing directory, the symlink will be named \f(CW\*(C`pandoc\*(C'\fR in there. This makes
most sense if the directory is listed in environment variable \f(CW$PATH\fR. If the
name is omitted or an empty string, symlink is created in subdirectory \f(CW\*(C`bin\*(C'\fR
of pandoc data directory.
.ie n .SS "arguments( [ @arguments | \e@arguments )"
.el .SS "arguments( [ \f(CW@arguments\fP | \e@arguments )"
.IX Subsection "arguments( [ @arguments | @arguments )"
Return or set a list of default arguments.
.ie n .SS "data_dir( [ @subdirs ] [ $file ] )"
.el .SS "data_dir( [ \f(CW@subdirs\fP ] [ \f(CW$file\fP ] )"
.IX Subsection "data_dir( [ @subdirs ] [ $file ] )"
Return the stated default data directory, introduced with Pandoc 1.11.  Use
function \f(CW\*(C`pandoc_data_dir\*(C'\fR alternatively to get the expected directory without
calling Pandoc executable.
.SS "input_formats"
.IX Subsection "input_formats"
Return a list of supported input formats.
.SS "output_formats"
.IX Subsection "output_formats"
Return a list of supported output formats.
.SS "highlight_languages"
.IX Subsection "highlight_languages"
Return a list of programming languages which syntax highlighting is supported
for (via Haskell library highlighting-kate).
.ie n .SS "extensions( [ $format ] )"
.el .SS "extensions( [ \f(CW$format\fP ] )"
.IX Subsection "extensions( [ $format ] )"
Return a hash of extensions mapped to whether they are enabled by default.
This method is only available since Pandoc 1.18 and the optional format
argument since Pandoc 2.0.6.
.SS "libs"
.IX Subsection "libs"
Return a hash mapping the names of Haskell libraries compiled into the
pandoc executable to Pandoc::Version objects.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This package includes Pandoc::Version to compare Pandoc version numbers,
Pandoc::Release to get Pandoc releases from GitHub, and
App::Prove::Plugin::andoc to run tests with selected Pandoc executables.
.PP
See Pandoc::Elements for a Perl interface to the abstract syntax tree of
Pandoc documents for more elaborate document processing.
.PP
See Pod::Pandoc to parse Plain Old Documentation format (perlpod) for
processing with Pandoc.
.PP
See Pandoc wrappers and interfaces <https://github.com/jgm/pandoc/wiki/Pandoc-wrappers-and-interfaces>
in the Pandoc GitHub Wiki for a list of wrappers in other programming
languages.
.PP
Other Pandoc related but outdated modules at \s-1CPAN\s0 include
Orze::Sources::Pandoc and App::PDoc.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jakob Vo\*8
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Benct Philip Jonsson
.SH "LICENSE"
.IX Header "LICENSE"
European Union Public Licence v. 1.2 (\s-1EUPL\-1.2\s0)