Pod::Simple::XHTML(3p) Perl Programmers Reference Guide #

bbaacckklliinnkk Whether to turn every =head1 directive into a link pointing to the top of the page (specifically, the opening body tag).

SSUUBBCCLLAASSSSIINNGG #

 If the standard options aren't enough, you may want to subclass
 Pod::Simple::XHMTL. These are the most likely candidates for methods
 you'll want to override when subclassing.

hhaannddllee__tteexxtt This method handles the body of text within any element: it’s the body of a paragraph, or everything between a “=begin” tag and the corresponding “=end” tag, or the text within an L entity, etc. You would want to override this if you are adding a custom element type that does more than just display formatted text. Perhaps adding a way to generate HTML tables from an extended version of POD.

 So, let's say you want to add a custom element called 'foo'. In your
 subclass's "new" method, after calling "SUPER::new" you'd call:

   $new->accept_targets_as_text( 'foo' );

 Then override the "start_for" method in the subclass to check for when
 "$flags->{'target'}" is equal to 'foo' and set a flag that marks that
 you're in a foo block (maybe "$self->{'in_foo'} = 1"). Then override the
 "handle_text" method to check for the flag, and pass $text to your custom
 subroutine to construct the HTML output for 'foo' elements, something
 like:

   sub handle_text {
       my ($self, $text) = @_;
       if ($self->{'in_foo'}) {
           $self->{'scratch'} .= build_foo_html($text);
           return;
       }
       $self->SUPER::handle_text($text);
   }

hhaannddllee__ccooddee This method handles the body of text that is marked up to be code. You might for instance override this to plug in a syntax highlighter. The base implementation just escapes the text.

 The callback methods "start_code" and "end_code" emits the "code" tags
 before and after "handle_code" is invoked, so you might want to override
 these together with "handle_code" if this wrapping isn't suitable.

 Note that the code might be broken into multiple segments if there are
 nested formatting codes inside a "C<...>" sequence.  In between the calls
 to "handle_code" other markup tags might have been emitted in that case.
 The same is true for verbatim sections if the "codes_in_verbatim" option
 is turned on.

aacccceepptt__ttaarrggeettss__aass__hhttmmll This method behaves like “accept_targets_as_text”, but also marks the region as one whose content should be emitted literally, without HTML entity escaping or wrapping in a “div” element.

rreessoollvvee__ppoodd__ppaaggee__lliinnkk my $url = $pod->resolve_pod_page_link(‘Net::Ping’, ‘INSTALL’); my $url = $pod->resolve_pod_page_link(‘perlpodspec’); my $url = $pod->resolve_pod_page_link(undef, ‘SYNOPSIS’);

 Resolves a POD link target (typically a module or POD file name) and
 section name to a URL. The resulting link will be returned for the above
 examples as:

   https://metacpan.org/pod/Net::Ping#INSTALL
   https://metacpan.org/pod/perlpodspec

#SYNOPSIS #

 Note that when there is only a section argument the URL will simply be a
 link to a section in the current document.

rreessoollvvee__mmaann__ppaaggee__lliinnkk my $url = $pod->resolve_man_page_link(‘crontab(5)’, ‘EXAMPLE CRON FILE’); my $url = $pod->resolve_man_page_link(‘crontab’);

 Resolves a man page link target and numeric section to a URL. The
 resulting link will be returned for the above examples as:

     http://man.he.net/man5/crontab
     http://man.he.net/man1/crontab

 Note that the first argument is required. The section number will be
 parsed from it, and if it's missing will default to 1. The second
 argument is currently ignored, as man.he.net <http://man.he.net> does not
 currently include linkable IDs or anchor names in its pages. Subclass to
 link to a different man page HTTP server.

iiddiiffyy my $id = $pod->idify($text); my $hash = $pod->idify($text, 1);

 This method turns an arbitrary string into a valid XHTML ID attribute
 value.  The rules enforced, following
 <http://webdesign.about.com/od/htmltags/a/aa031707.htm>, are:

 •   The id must start with a letter (a-z or A-Z)

 •   All subsequent characters can be letters, numbers (0-9), hyphens (-),
     underscores (_), colons (:), and periods (.).

 •   The final character can't be a hyphen, colon, or period. URLs ending
     with these characters, while allowed by XHTML, can be awkward to
     extract from plain text.

 •   Each id must be unique within the document.

 In addition, the returned value will be unique within the context of the
 Pod::Simple::XHTML object unless a second argument is passed a true
 value. ID attributes should always be unique within a single XHTML
 document, but pass the true value if you are creating not an ID but a URL
 hash to point to an ID (i.e., if you need to put the "#foo" in "<a
 href="#foo">foo</a>".

bbaattcchh__mmooddee__ppaaggee__oobbjjeecctt__iinniitt $pod->batch_mode_page_object_init($batchconvobj, $module, $infile, $outfile, $depth);

 Called by Pod::Simple::HTMLBatch so that the class has a chance to
 initialize the converter. Internally it sets the "batch_mode" property to
 true and sets "batch_mode_current_level()", but Pod::Simple::XHTML does
 not currently use those features. Subclasses might, though.

SSEEEE AALLSSOO #

 Pod::Simple, Pod::Simple::Text, Pod::Spell

SSUUPPPPOORRTT #

 Questions or discussion about POD and Pod::Simple should be sent to the
 pod-people@perl.org mail list. Send an empty email to
 pod-people-subscribe@perl.org to subscribe.

 This module is managed in an open GitHub repository,
 <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
 contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
 send patches!

 Patches against Pod::Simple are welcome. Please send bug reports to
 <bug-pod-simple@rt.cpan.org>.

CCOOPPYYRRIIGGHHTT AANNDD DDIISSCCLLAAIIMMEERRSS #

 Copyright (c) 2003-2005 Allison Randal.

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

 This program is distributed in the hope that it will be useful, but
 without any warranty; without even the implied warranty of
 merchantability or fitness for a particular purpose.

AACCKKNNOOWWLLEEDDGGEEMMEENNTTSS #

 Thanks to Hurricane Electric <http://he.net/> for permission to use its
 Linux man pages online <http://man.he.net/> site for man page links.

 Thanks to search.cpan.org <http://search.cpan.org/> for permission to use
 the site for Perl module links.

AAUUTTHHOORR #

 Pod::Simpele::XHTML was created by Allison Randal <allison@perl.org>.

 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
 bother him, he's retired.

 Pod::Simple is maintained by:

 •   Allison Randal "allison@perl.org"

 •   Hans Dieter Pearcey "hdp@cpan.org"

 •   David E. Wheeler "dwheeler@cpan.org"

perl v5.36.3 2023-02-15 Pod::Simple::XHTML(3p)