diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Pod::Simple::XHTML.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Pod::Simple::XHTML.3pm | 398 |
1 files changed, 398 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Pod::Simple::XHTML.3pm b/upstream/mageia-cauldron/man3pm/Pod::Simple::XHTML.3pm new file mode 100644 index 00000000..87f0167a --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Pod::Simple::XHTML.3pm @@ -0,0 +1,398 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. 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 +.\" ======================================================================== +.\" +.IX Title "Pod::Simple::XHTML 3pm" +.TH Pod::Simple::XHTML 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" 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 +Pod::Simple::XHTML \-\- format Pod as validating XHTML +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Pod::Simple::XHTML; +\& +\& my $parser = Pod::Simple::XHTML\->new(); +\& +\& ... +\& +\& $parser\->parse_file(\*(Aqpath/to/file.pod\*(Aq); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This class is a formatter that takes Pod and renders it as XHTML +validating HTML. +.PP +This is a subclass of Pod::Simple::Methody and inherits all its +methods. The implementation is entirely different than +Pod::Simple::HTML, but it largely preserves the same interface. +.SS "Minimal code" +.IX Subsection "Minimal code" +.Vb 6 +\& use Pod::Simple::XHTML; +\& my $psx = Pod::Simple::XHTML\->new; +\& $psx\->output_string(\emy $html); +\& $psx\->parse_file(\*(Aqpath/to/Module/Name.pm\*(Aq); +\& open my $out, \*(Aq>\*(Aq, \*(Aqout.html\*(Aq or die "Cannot open \*(Aqout.html\*(Aq: $!\en"; +\& print $out $html; +.Ve +.PP +You can also control the character encoding and entities. For example, if +you're sure that the POD is properly encoded (using the \f(CW\*(C`=encoding\*(C'\fR command), +you can prevent high-bit characters from being encoded as HTML entities and +declare the output character set as UTF\-8 before parsing, like so: +.PP +.Vb 2 +\& $psx\->html_charset(\*(AqUTF\-8\*(Aq); +\& $psx\->html_encode_chars(q{&<>\*(Aq"}); +.Ve +.SH METHODS +.IX Header "METHODS" +Pod::Simple::XHTML offers a number of methods that modify the format of +the HTML output. Call these after creating the parser object, but before +the call to \f(CW\*(C`parse_file\*(C'\fR: +.PP +.Vb 3 +\& my $parser = Pod::PseudoPod::HTML\->new(); +\& $parser\->set_optional_param("value"); +\& $parser\->parse_file($file); +.Ve +.SS perldoc_url_prefix +.IX Subsection "perldoc_url_prefix" +In turning Foo::Bar into http://whatever/Foo%3a%3aBar, what +to put before the "Foo%3a%3aBar". The default value is +"https://metacpan.org/pod/". +.SS perldoc_url_postfix +.IX Subsection "perldoc_url_postfix" +What to put after "Foo%3a%3aBar" in the URL. This option is not set by +default. +.SS man_url_prefix +.IX Subsection "man_url_prefix" +In turning \f(CWcrontab(5)\fR into http://whatever/man/1/crontab, what +to put before the "1/crontab". The default value is +"http://man.he.net/man". +.SS man_url_postfix +.IX Subsection "man_url_postfix" +What to put after "1/crontab" in the URL. This option is not set by default. +.SS "title_prefix, title_postfix" +.IX Subsection "title_prefix, title_postfix" +What to put before and after the title in the head. The values should +already be &\-escaped. +.SS html_css +.IX Subsection "html_css" +.Vb 1 +\& $parser\->html_css(\*(Aqpath/to/style.css\*(Aq); +.Ve +.PP +The URL or relative path of a CSS file to include. This option is not +set by default. +.SS html_javascript +.IX Subsection "html_javascript" +The URL or relative path of a JavaScript file to pull in. This option is +not set by default. +.SS html_doctype +.IX Subsection "html_doctype" +A document type tag for the file. This option is not set by default. +.SS html_charset +.IX Subsection "html_charset" +The character set to declare in the Content-Type meta tag created by default +for \f(CW\*(C`html_header_tags\*(C'\fR. Note that this option will be ignored if the value of +\&\f(CW\*(C`html_header_tags\*(C'\fR is changed. Defaults to "ISO\-8859\-1". +.SS html_header_tags +.IX Subsection "html_header_tags" +Additional arbitrary HTML tags for the header of the document. The +default value is just a content type header tag: +.PP +.Vb 1 +\& <meta http\-equiv="Content\-Type" content="text/html; charset=ISO\-8859\-1"> +.Ve +.PP +Add additional meta tags here, or blocks of inline CSS or JavaScript +(wrapped in the appropriate tags). +.PP +\fIhtml_encode_chars\fR +.IX Subsection "html_encode_chars" +.PP +A string containing all characters that should be encoded as HTML entities, +specified using the regular expression character class syntax (what you find +within brackets in regular expressions). This value will be passed as the +second argument to the \f(CW\*(C`encode_entities\*(C'\fR function of HTML::Entities. If +HTML::Entities is not installed, then any characters other than \f(CW\*(C`&<\*(C'\fR"'> +will be encoded numerically. +.SS html_h_level +.IX Subsection "html_h_level" +This is the level of HTML "Hn" element to which a Pod "head1" corresponds. For +example, if \f(CW\*(C`html_h_level\*(C'\fR is set to 2, a head1 will produce an H2, a head2 +will produce an H3, and so on. +.SS default_title +.IX Subsection "default_title" +Set a default title for the page if no title can be determined from the +content. The value of this string should already be &\-escaped. +.SS force_title +.IX Subsection "force_title" +Force a title for the page (don't try to determine it from the content). +The value of this string should already be &\-escaped. +.SS "html_header, html_footer" +.IX Subsection "html_header, html_footer" +Set the HTML output at the beginning and end of each file. The default +header includes a title, a doctype tag (if \f(CW\*(C`html_doctype\*(C'\fR is set), a +content tag (customized by \f(CW\*(C`html_header_tags\*(C'\fR), a tag for a CSS file +(if \f(CW\*(C`html_css\*(C'\fR is set), and a tag for a Javascript file (if +\&\f(CW\*(C`html_javascript\*(C'\fR is set). The default footer simply closes the \f(CW\*(C`html\*(C'\fR +and \f(CW\*(C`body\*(C'\fR tags. +.PP +The options listed above customize parts of the default header, but +setting \f(CW\*(C`html_header\*(C'\fR or \f(CW\*(C`html_footer\*(C'\fR completely overrides the +built-in header or footer. These may be useful if you want to use +template tags instead of literal HTML headers and footers or are +integrating converted POD pages in a larger website. +.PP +If you want no headers or footers output in the HTML, set these options +to the empty string. +.SS index +.IX Subsection "index" +Whether to add a table-of-contents at the top of each page (called an +index for the sake of tradition). +.SS anchor_items +.IX Subsection "anchor_items" +Whether to anchor every definition \f(CW\*(C`=item\*(C'\fR directive. This needs to be +enabled if you want to be able to link to specific \f(CW\*(C`=item\*(C'\fR directives, which +are output as \f(CW\*(C`<dt>\*(C'\fR elements. Disabled by default. +.SS backlink +.IX Subsection "backlink" +Whether to turn every =head1 directive into a link pointing to the top +of the page (specifically, the opening body tag). +.SH SUBCLASSING +.IX Header "SUBCLASSING" +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. +.SS handle_text +.IX Subsection "handle_text" +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. +.PP +So, let's say you want to add a custom element called 'foo'. In your +subclass's \f(CW\*(C`new\*(C'\fR method, after calling \f(CW\*(C`SUPER::new\*(C'\fR you'd call: +.PP +.Vb 1 +\& $new\->accept_targets_as_text( \*(Aqfoo\*(Aq ); +.Ve +.PP +Then override the \f(CW\*(C`start_for\*(C'\fR 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 +\&\f(CW\*(C`handle_text\*(C'\fR method to check for the flag, and pass \f(CW$text\fR to your +custom subroutine to construct the HTML output for 'foo' elements, +something like: +.PP +.Vb 8 +\& sub handle_text { +\& my ($self, $text) = @_; +\& if ($self\->{\*(Aqin_foo\*(Aq}) { +\& $self\->{\*(Aqscratch\*(Aq} .= build_foo_html($text); +\& return; +\& } +\& $self\->SUPER::handle_text($text); +\& } +.Ve +.SS handle_code +.IX Subsection "handle_code" +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. +.PP +The callback methods \f(CW\*(C`start_code\*(C'\fR and \f(CW\*(C`end_code\*(C'\fR emits the \f(CW\*(C`code\*(C'\fR tags +before and after \f(CW\*(C`handle_code\*(C'\fR is invoked, so you might want to override these +together with \f(CW\*(C`handle_code\*(C'\fR if this wrapping isn't suitable. +.PP +Note that the code might be broken into multiple segments if there are +nested formatting codes inside a \f(CW\*(C`C<...>\*(C'\fR sequence. In between the +calls to \f(CW\*(C`handle_code\*(C'\fR other markup tags might have been emitted in that +case. The same is true for verbatim sections if the \f(CW\*(C`codes_in_verbatim\*(C'\fR +option is turned on. +.SS accept_targets_as_html +.IX Subsection "accept_targets_as_html" +This method behaves like \f(CW\*(C`accept_targets_as_text\*(C'\fR, but also marks the region +as one whose content should be emitted literally, without HTML entity escaping +or wrapping in a \f(CW\*(C`div\*(C'\fR element. +.SS resolve_pod_page_link +.IX Subsection "resolve_pod_page_link" +.Vb 3 +\& my $url = $pod\->resolve_pod_page_link(\*(AqNet::Ping\*(Aq, \*(AqINSTALL\*(Aq); +\& my $url = $pod\->resolve_pod_page_link(\*(Aqperlpodspec\*(Aq); +\& my $url = $pod\->resolve_pod_page_link(undef, \*(AqSYNOPSIS\*(Aq); +.Ve +.PP +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: +.PP +.Vb 3 +\& https://metacpan.org/pod/Net::Ping#INSTALL +\& https://metacpan.org/pod/perlpodspec +\& #SYNOPSIS +.Ve +.PP +Note that when there is only a section argument the URL will simply be a link +to a section in the current document. +.SS resolve_man_page_link +.IX Subsection "resolve_man_page_link" +.Vb 2 +\& my $url = $pod\->resolve_man_page_link(\*(Aqcrontab(5)\*(Aq, \*(AqEXAMPLE CRON FILE\*(Aq); +\& my $url = $pod\->resolve_man_page_link(\*(Aqcrontab\*(Aq); +.Ve +.PP +Resolves a man page link target and numeric section to a URL. The resulting +link will be returned for the above examples as: +.PP +.Vb 2 +\& http://man.he.net/man5/crontab +\& http://man.he.net/man1/crontab +.Ve +.PP +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. +.SS idify +.IX Subsection "idify" +.Vb 2 +\& my $id = $pod\->idify($text); +\& my $hash = $pod\->idify($text, 1); +.Ve +.PP +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: +.IP \(bu 4 +The id must start with a letter (a\-z or A\-Z) +.IP \(bu 4 +All subsequent characters can be letters, numbers (0\-9), hyphens (\-), +underscores (_), colons (:), and periods (.). +.IP \(bu 4 +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. +.IP \(bu 4 +Each id must be unique within the document. +.PP +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 \f(CW\*(C`<a href="#foo">foo</a>\*(C'\fR. +.SS batch_mode_page_object_init +.IX Subsection "batch_mode_page_object_init" +.Vb 1 +\& $pod\->batch_mode_page_object_init($batchconvobj, $module, $infile, $outfile, $depth); +.Ve +.PP +Called by Pod::Simple::HTMLBatch so that the class has a chance to +initialize the converter. Internally it sets the \f(CW\*(C`batch_mode\*(C'\fR property to +true and sets \f(CWbatch_mode_current_level()\fR, but Pod::Simple::XHTML does not +currently use those features. Subclasses might, though. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Pod::Simple, Pod::Simple::Text, Pod::Spell +.SH SUPPORT +.IX Header "SUPPORT" +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. +.PP +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! +.PP +Patches against Pod::Simple are welcome. Please send bug reports to +<bug\-pod\-simple@rt.cpan.org>. +.SH "COPYRIGHT AND DISCLAIMERS" +.IX Header "COPYRIGHT AND DISCLAIMERS" +Copyright (c) 2003\-2005 Allison Randal. +.PP +This library is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. +.PP +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. +.SH ACKNOWLEDGEMENTS +.IX Header "ACKNOWLEDGEMENTS" +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. +.PP +Thanks to search.cpan.org <http://search.cpan.org/> for permission to use the +site for Perl module links. +.SH AUTHOR +.IX Header "AUTHOR" +Pod::Simpele::XHTML was created by Allison Randal <allison@perl.org>. +.PP +Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. +But don't bother him, he's retired. +.PP +Pod::Simple is maintained by: +.IP \(bu 4 +Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR +.IP \(bu 4 +Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR +.IP \(bu 4 +David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR |