NAME

App::PODUtils - Command-line utilities related to POD

VERSION

This document describes version 0.050 of App::PODUtils (from Perl distribution App-PODUtils), released on 2021-07-20.

SYNOPSIS

This distribution provides the following command-line utilities related to Perl POD:

FUNCTIONS

dump_pod_structure

Usage:

dump_pod_structure(%args) -> [$status_code, $reason, $payload, \%result_meta]

Dump POD structure using Pod::Elemental.

This is actually just a shortcut for:

% podsel FILENAME --root --dump --transform Pod5 --transform Nester

This function is not exported.

Arguments ('*' denotes required arguments):

  • pod => perl::pod_filename (default: "-")

    Path to a .POD file, or a POD name (e.g. Foo::Bar) which will be searched in @INC.

    "-" means standard input.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

Usage:

extract_links_in_pod(%args) -> any

Extract links in POD.

This function is not exported.

Arguments ('*' denotes required arguments):

  • detail => bool

  • pod => perl::pod_filename (default: "-")

    Path to a .POD file, or a POD name (e.g. Foo::Bar) which will be searched in @INC.

    "-" means standard input.

Return value: (any)

reverse_pod_headings

Usage:

reverse_pod_headings(%args) -> any

Reverse POD headings.

This function is not exported.

Arguments ('*' denotes required arguments):

  • command => str (default: "head1")

  • naked_pod => bool

    Strip =pod and =cut delimiters.

    Normally, when outputing POD text, the =pod header and =cut footer are included. This option, if enabled, strips the outputting of such header/footer.

  • pod => perl::pod_filename (default: "-")

    Path to a .POD file, or a POD name (e.g. Foo::Bar) which will be searched in @INC.

    "-" means standard input.

Return value: (any)

sort_pod_headings

Usage:

sort_pod_headings(%args) -> any

Sort POD headings in text.

This utility sorts POD headings in text. By default it sorts =head1 headings. For example this POD:

=head1 b

some text for b

=head1 a

text for a

=head2 a2

=head2 a1

=head1 c

text for c

will be sorted into:

=head1 a

text for a

=head2 a2

=head2 a1

=head1 b

some text for b

=head1 c

text for c

Note that the =head2 headings are not sorted. If you want to sort those, you can rerun the utility and specify the --command=head2 option.

This function is not exported.

Arguments ('*' denotes required arguments):

  • command => str (default: "head1")

  • naked_pod => bool

    Strip =pod and =cut delimiters.

    Normally, when outputing POD text, the =pod header and =cut footer are included. This option, if enabled, strips the outputting of such header/footer.

  • pod => perl::pod_filename (default: "-")

    Path to a .POD file, or a POD name (e.g. Foo::Bar) which will be searched in @INC.

    "-" means standard input.

  • sort_args => array[str]

    Arguments to pass to the Sort::Sub::* routine.

  • sort_sub => sortsub::spec

    Name of a Sort::Sub::* module (without the prefix).

Return value: (any)

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/App-PODUtils.

SOURCE

Source repository is at https://github.com/perlancar/perl-App-PODUtils.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=App-PODUtils

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

pod2html

podtohtml from App::podtohtml

App::PMUtils

App::PlUtils

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021, 2020, 2019, 2018, 2017, 2016 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.