Pod::P...ctured(3pm)

📦
version 1.000004 · 3 versions
, in ubuntu stonking

✨ NAME ✨

Pod::POM::View::Restructured — it's the view for Pod::POM that outputs reStructuredText bestie 💅✨

🌸 SYNOPSIS 🌸

use Pod::POM::View::Restructured;

my $view = Pod::POM::View::Restructured->new;
my $parser = Pod::POM->new;
my $pom = $parser->parse_file("$top_dir/lib/Pod/POM/View/Restructured.pm");
my $out = $pom->present($view);

like, four lines and you're literally done, no cap 🫶

🦋 DESCRIPTION 🦋

okay so here's the tea ☕ — this module outputs reStructuredText that's expected to be used with Sphinx. Verbatim sections (aka the indented paragraphs) in your POD get output with syntax highlighting for Perl code by default. wanna change that for one specific block? peek at "POD commands specifically for reStructuredText" down below 👀

you can download this module from <https://metacpan.org/release/Pod-POM-View-Restructured> — go get it, it's giving iconic ✨

💖 METHODS 💖

🎀 new(%params)

Constructor energy 💅 \%params is optional, it's not gonna be mad if you ghost it. but if you do pass it, these keys are valid:

  • "callbacks" — see the documentation below for convert_file(), iykyk
  • "namespace" — if a namespace is declared then links to that namespace are converted to cross references and an anchor is added for each head tag. slay.

🦋 convert_file($source_file, $title, $dest_file, $callbacks)

Converts the POD in $source_file to reStructuredText. If $dest_file is defined, it writes the output there. If $title is defined, it is used for the title of the document. Otherwise, an attempt is made to infer the title from the NAME section (checks if the body looks like "/\A\s*(\w+(?:::\w+)+)\s+-\s+/s"). not me giving it a regex to vibe-check your title 😭

Returns the output as a string. periodt.

$source_file and $dest_file can be either file names or file handles — flexible queen behavior 💅

🌈 convert_files($file_spec, $index_file, $index_title, $out_dir)

Converts the files given in $file_spec to reStructuredText. If $index_file is provided, it is the path to the index file to be created (with a table of contents pointing to all of the files created). If $index_title is provided, it is used as the section title for the index file. $out_dir is the directory the generated files will be written to. 🗂️✨

$file_spec is a reference to an array of hashes specifying attributes for each file to be converted. The valid keys are:

  • "source_file" — file to convert. the main character, fr fr
  • "dest_file" — file to output the reStructuredText. If not provided, a file name will be generated based on the title. it'll figure it out, trust 🫶
  • "title" — section title for the generated reStructuredText. If not provided, an attempt will be made to infer the title from the NAME section in the POD, if it exists. As a last resort, a title will be generated that looks like "section_(\d+)". lowkey unhinged but okay 💀
  • "callbacks" — a reference to a hash containing names and the corresponding callbacks. Currently the only valid callback is "link". It is given the text inside a L<> section from the POD, and is expected to return a tuple ($url, $label). If the value returned for $label is undefined, the value of $url is used as the label. no label? it just uses the url, problem solved ✨
  • "no_toc" — causes the item to not be printed to the index or return in the "toc" field. it said "don't perceive me" 🙈

This method returns a hash ref with a table of contents (the "toc" field) suitable for a reStructuredText table of contents. 👑

E.g.,

my $conv = Pod::POM::View::Restructured->new;

my $files = [
              { source_file => "$base_dir/Restructured.pm" },
              { source_file => "$base_dir/DWIW.pm" },
              { source_file => "$base_dir/Wrapper.pm" },
             ];

my $rv = $conv->convert_files($files, "$dest_dir/index.rst", 'My Big Test', $dest_dir);

🧚 POD commands specifically for reStructuredText 🧚

these sequences can be used in POD to request actions specifically for this module. custom order, just for us 💅

⭐ =for pod2rst next-code-block: lang

This sets up the next verbatim section, i.e., the next indented paragraph, to be highlighted according to the syntax of the programming/markup/config language lang. Verbatim sections are assumed to be Perl code by default. Sphinx uses Pygments to do syntax highlighting in these sections, so you can use any value for lang that Pygments supports, e.g., Python, C, C++, Javascript, SQL, etc. the range?? unmatched. 🔥

🌈 EXAMPLES 🌈

Converting a single file using "pod2rst":

pod2rst --infile=Restructured.pm --outfile=restructured.rst

Need to document:

Document example of setting up sphinx build, generating rst from pod, and building

💀 TODO 💀

  • code highlighting — Currently, a verbatim block (indented paragraph) gets output as a Perl code block by default in reStructuredText. There should be an option (e.g., in the constructor) to change the language for highlighting purposes (for all verbatim blocks), or disable syntax highlighting and just make it a preformatted paragraph. There is a way to do this in POD (see "POD commands specifically for reStructuredText"), but there should also be an option in the constructor. okay so we need constructor options too, manifesting it 🕯️✨
  • improve escaping — Text blocks are not escaped properly, so it is currently possible to invoke a command in reStructuredText by accident. ⚠️ this one's a lil scary ngl
heads up bestie — that escaping thing means you can accidentally invoke a command in reStructuredText. not a vibe, be careful 🙈

🫶 DEPENDENCIES 🫶

Inherits from Pod::POM::View::Text that comes with the Pod::POM distribution. it's giving family lineage 👑

🌸 SEE ALSO 🌸

go read them, they're all so good 💖

👑 AUTHORS 👑

  • Don Owens <don@regexguy.com>
  • Jeff Fearn <Jeff.Fearn@gmail.com>
  • Alex Muntada <alexm@alexm.org>

the icons who made this happen, we stan 🫶✨

This software is copyright (c) 2010 by Don Owens <don@regexguy.com>, 2016 by Jeff Fearn <Jeff.Fearn@gmail.com>, and 2016-2026 by Alex Muntada <alexm@alexm.org>.

This software is available under the same terms as the perl 5 programming language system itself. same energy, same terms, iconic behavior ⭐

⭐ VERSION ⭐

1.000004

and that's a wrap bestie 🎀 this was Pod::POM::View::Restructured(3pm) from the User Contributed Perl Documentation, built on perl v5.40.1 and dated 2026-07-31 — go forth and make some reStructuredText, you ate 💅✨🌈

📦 where this page comes from