---
name: "Pod::Simple::Pandoc"
section: "3pm"
platform: "linux"
package: "libpod-pandoc-perl"
version: "0.5.0-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Pod::Simple::Pandoc"
---

# Pod::Simple::Pandoc(3pm)

convert Pod to Pandoc document model

## NAME

Pod::Simple::Pandoc - convert Pod to Pandoc document model

## SYNOPSIS

```
  use Pod::Simple::Pandoc;
  my $parser = Pod::Simple::Pandoc->new( %options );
  my $doc    = $parser->parse_file( $filename );
  # result is a Pandoc::Document object
  my $json = $doc->to_json;
  my $markdown = $doc->to_pandoc( -t => 'markdown' );
  $doc->to_pandoc(qw( -o doc.html --standalone ));
```

## DESCRIPTION

This module converts Pod format (perlpod) to the document model used by Pandoc \<http://pandoc.org/\>. The result can be accessed with methods of Pandoc::Elements and further processed with Pandoc to convert it to other document formats (HTML, Markdown, LaTeX, PDF, EPUB, docx, ODT, man...).

See pod2pandoc and App::pod2pandoc for a command line script and a simplified API to this module.

## OPTIONS

- parse

  Parse Pod data sections with Pandoc and merge them into the document instead of passing them as `"RawBlock"`. Use `"*"` to parse all formats supported by pandoc as input format. Expects an array reference otherwise.

- podurl

  Base URL to link Perl module names to. Set to \<https://metacpan.org/pod/\> by default. A false value disables linking external modules and wraps module names in `"Span"` elements instead. All module names are marked up with class `"perl-module"`.

## METHODS

### parse\_file( $filename \| \*INPUT )

Reads Pod from file or filehandle and convert it to a Pandoc::Document. The filename is put into document metadata field `"file"` and the module name. The NAME section, if given, is additionally split into metadata fields `"title"` and `"subtitle"`.

### parse\_module( $module )

Reads Pod from a module given by name such as `"Pod::Pandoc"` or by URL.

### parse\_string( $string )

Reads Pod from string and convert it to a Pandoc::Document. Also sets metadata fields `"title"` and `"subtitle"`.

### parse\_dir( $directory )

Recursively looks for `".pm"` and `".pod"` files in a given directory and parses them. Returns a hash reference with filenames mapped to Pandoc::Document objects. Each document is enriched with metadata fields `"base"` (relative path from each file to the base directory) in addition to `"file"`, `"title"`, and `"subtitle"`.

### parse\_modules( $directory, \[ quiet =\> 0\|1 \] )

Same as method `"parse_dir"` but returns a Pod::Simple::Pandoc::Modules instance that maps module names to Pandoc::Document instances. The source directory can also be specified with option `"source"`. Option `"quiet"` disables warnings for skipped files.

### parse\_and\_merge( @files\_or\_modules )

Reads Pod from files or modules given by name and merges them into one Pandoc::Document by concatenation.

## MAPPING

Pod elements are mapped to Pandoc elements as following:

### Formatting codes

Formatting codes for *italic text* (`"I<...>"`), **bold text** (`"B<...>"`), and `"code"` (`"C<...>"`) are mapped to Emphasized text (`"Emph"`), strongly emphasized text (`"Strong"`), and inline code (`"Code"`). Formatting code for *filenames* (`"F<...>"`) are mapped to inline code with class `"filename"` (``"`...`{.filename}"`` in Pandoc Markdown).  Formatting codes inside code and filenames (e.g. `"code with `**bold**`"` or *\<http://example.org/\>* as filename) are stripped to unformatted code.  Character escapes (`"E<...>"`) and `"S<...>"` are directly mapped to Unicode characters. The special formatting code `"X<...>"` is ignored.

### Links

Some examples of links of different kinds:

\<http://example.org/\>

pod2pandoc

"OPTIONS" in pod2pandoc

[**perl**(1)](/perl/1.md)

"ENVIRONMENT" in [**crontab**(5)](/crontab/5.md)

hell itself!

Link text can contain formatting codes:

the `"pod2pandoc"` script

"MAPPING"

mapping from PoD to Pandoc

### Titles *may contain formatting "codes"*!

### Lists

- 1\.

  Numbered lists are

- 2\.

  converted to `"NumberedList"` and

  - •

    Bulleted lists are

  - •

    converted to

    `"BulletList"`

- Definition

  - Lists

  - are

  *also* supported.

### =over/=back

An `"=over"`...`"=back"` region containing no `"=item"` is mapped to `"BlockQuote"`.

### Verbatim sections

```
  verbatim sections are mapped
    to code blocks
```

### Data sections

Data sections are passed as `"RawBlock"`. `"HTML"`, `"LaTeX"`, `"TeX"`, and `"tex"` are recognized as alias for `"html"` and `"tex"`.

Option `"parse"` can be used to parse data sections with pandoc executable and merge them into the result document.

## SEE ALSO

This module is based on Pod::Simple (Pod::Simple::SimpleTree). It makes obsolete several specialized `"Pod::Simple::..."` modules such as Pod::Simple::HTML, Pod::Simple::XHTML, Pod::Simple::LaTeX, Pod::Simple::RTF Pod::Simple::Text, Pod::Simple::Wiki, Pod::WordML, Pod::Perldoc::ToToc etc.