内容

• 名称
• 概要
• 描述
  • 最小代码
• 方法
  • perldoc_url_prefix
  • perldoc_url_postfix
  • man_url_prefix
  • man_url_postfix
  • title_prefix, title_postfix
  • html_css
  • html_javascript
  • html_doctype
  • html_charset
  • html_header_tags
    • html_encode_chars
  • html_h_level
  • default_title
  • force_title
  • html_header, html_footer
  • index
  • anchor_items
  • backlink
• 子类化
  • handle_text
  • handle_code
  • accept_targets_as_html
  • resolve_pod_page_link
  • resolve_man_page_link
  • idify
  • batch_mode_page_object_init
• 参见
• 支持
• 版权和免责声明
• 致谢
• 作者

#名称

Pod::Simple::XHTML -- 将 Pod 格式化为验证 XHTML

#概要

use Pod::Simple::XHTML;

my $parser = Pod::Simple::XHTML->new();

...

$parser->parse_file('path/to/file.pod');

#描述

此类是一个格式化程序，它接受 Pod 并将其渲染为验证 XHTML 的 HTML。

这是 Pod::Simple::Methody 的子类，并继承了它的所有方法。实现方式与 Pod::Simple::HTML 完全不同，但它在很大程度上保留了相同的接口。

#最小代码

use Pod::Simple::XHTML;
my $psx = Pod::Simple::XHTML->new;
$psx->output_string(\my $html);
$psx->parse_file('path/to/Module/Name.pm');
open my $out, '>', 'out.html' or die "Cannot open 'out.html': $!\n";
print $out $html;

您还可以控制字符编码和实体。例如，如果您确定 POD 编码正确（使用 =encoding 命令），您可以阻止高位字符被编码为 HTML 实体，并在解析之前将输出字符集声明为 UTF-8，如下所示

$psx->html_charset('UTF-8');
$psx->html_encode_chars(q{&<>'"});

#方法

Pod::Simple::XHTML 提供了许多方法来修改 HTML 输出的格式。在创建解析器对象后，但在调用 parse_file 之前调用这些方法。

my $parser = Pod::PseudoPod::HTML->new();
$parser->set_optional_param("value");
$parser->parse_file($file);

#perldoc_url_prefix

在将 Foo::Bar 转换为 http://whatever/Foo%3a%3aBar 时，在 "Foo%3a%3aBar" 之前要放什么。默认值为 "https://metacpan.org/pod/"。

#perldoc_url_postfix

在 URL 中 "Foo%3a%3aBar" 之后要放什么。此选项默认情况下未设置。

#man_url_prefix

在将 crontab(5) 转换为 http://whatever/man/1/crontab 时，在 "1/crontab" 之前要放什么。默认值为 "http://man.he.net/man"。

#man_url_postfix

在 URL 中 "1/crontab" 之后要放什么。此选项默认情况下未设置。

#title_prefix, title_postfix

在头部标题之前和之后要放什么。这些值应该已经 &-转义。

#html_css

$parser->html_css('path/to/style.css');

要包含的 CSS 文件的 URL 或相对路径。此选项默认情况下未设置。

#html_javascript

要引入的 JavaScript 文件的 URL 或相对路径。此选项默认情况下未设置。

#html_doctype

文件的文档类型标签。此选项默认情况下未设置。

#html_charset

在默认情况下为 html_header_tags 创建的 Content-Type 元标签中声明的字符集。请注意，如果 html_header_tags 的值更改，此选项将被忽略。默认值为 "ISO-8859-1"。

#html_header_tags

文档头部的其他任意 HTML 标签。默认值只是一个内容类型头部标签

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

在此处添加其他元标签，或内联 CSS 或 JavaScript 块（包装在相应的标签中）。

#html_encode_chars

包含所有应编码为 HTML 实体的字符的字符串，使用正则表达式字符类语法指定（您在正则表达式中方括号内找到的内容）。此值将作为 HTML::Entities 的 encode_entities 函数的第二个参数传递。如果未安装 HTML::Entities，则除 &<"'> 之外的任何字符都将以数字方式编码。

#html_h_level

这是 Pod "head1" 对应的 HTML "Hn" 元素的级别。例如，如果 html_h_level 设置为 2，则 head1 将生成 H2，head2 将生成 H3，依此类推。

#default_title

如果无法从内容中确定页面标题，则设置页面的默认标题。此字符串的值应已进行 & 转义。

#force_title

强制页面标题（不要尝试从内容中确定标题）。此字符串的值应已进行 & 转义。

#html_header, html_footer

设置每个文件开头和结尾的 HTML 输出。默认标题包括标题、文档类型标签（如果设置了 html_doctype）、内容标签（由 html_header_tags 自定义）、CSS 文件标签（如果设置了 html_css）以及 Javascript 文件标签（如果设置了 html_javascript）。默认页脚只是关闭 html 和 body 标签。

上面列出的选项自定义了默认标题的某些部分，但设置 html_header 或 html_footer 将完全覆盖内置的标题或页脚。如果您想使用模板标签而不是文字 HTML 标题和页脚，或者将转换后的 POD 页面集成到更大的网站中，这些选项可能很有用。

如果您希望 HTML 中没有输出标题或页脚，请将这些选项设置为空字符串。

#index

是否在每个页面顶部添加目录（为了传统起见，称为索引）。

#anchor_items

是否为每个定义 =item 指令添加锚点。如果您想链接到特定 =item 指令（输出为 <dt> 元素），则需要启用此选项。默认情况下禁用。

#backlink

是否将每个 =head1 指令转换为指向页面顶部（具体来说是打开的 body 标签）的链接。

#SUBCLASSING

如果标准选项不够，您可能需要子类化 Pod::Simple::XHMTL。这些是最有可能被覆盖的方法，当您子类化时，您可能需要覆盖这些方法。

#handle_text

此方法处理任何元素内的文本主体：它是段落的正文，或 "=begin" 标签和相应 "=end" 标签之间的所有内容，或 L 实体内的文本等。如果您添加了自定义元素类型，该类型不仅仅是显示格式化文本，则需要覆盖此方法。也许添加一种方法可以从扩展的 POD 版本生成 HTML 表格。

假设您想要添加一个名为“foo”的自定义元素。在子类的new方法中，在调用SUPER::new之后，您需要调用

$new->accept_targets_as_text( 'foo' );

然后在子类中覆盖start_for方法，以检查"$flags->{'target'}"是否等于“foo”，并设置一个标志来标记您是否处于foo块中（例如"$self->{'in_foo'} = 1"）。然后覆盖handle_text方法以检查标志，并将$text传递给您的自定义子例程以构建“foo”元素的HTML输出，例如

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

#handle_code

此方法处理标记为代码的文本主体。例如，您可以覆盖它以插入语法高亮器。基本实现只是转义文本。

回调方法start_code和end_code在调用handle_code之前和之后分别发出code标签，因此如果您不希望使用这种包装，您可能需要与handle_code一起覆盖它们。

请注意，如果在C<...>序列中存在嵌套的格式化代码，则代码可能会被分成多个段。在这种情况下，在调用handle_code之间，可能已经发出了其他标记标签。如果启用了codes_in_verbatim选项，则逐字节段也是如此。

#accept_targets_as_html

此方法的行为类似于accept_targets_as_text，但它还会将该区域标记为其内容应按字面意思发出，而无需HTML实体转义或包装在div元素中。

#resolve_pod_page_link

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');

将POD链接目标（通常是模块或POD文件名）和节名称解析为URL。对于上面的示例，将返回以下链接：

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

请注意，当只有节参数时，URL将只是一个指向当前文档中节的链接。

#resolve_man_page_link

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

将手册页链接目标和数字节解析为URL。对于上面的示例，将返回以下链接：

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

请注意，第一个参数是必需的。节号将从该参数中解析，如果缺失，将默认为 1。第二个参数目前被忽略，因为 man.he.net 目前在其页面中不包含可链接的 ID 或锚点名称。子类可链接到不同的 man 页面 HTTP 服务器。

#idify

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

此方法将任意字符串转换为有效的 XHTML ID 属性值。遵循 http://webdesign.about.com/od/htmltags/a/aa031707.htm 的强制规则是

• id 必须以字母开头（a-z 或 A-Z）

• 所有后续字符可以是字母、数字 (0-9)、连字符 (-)、下划线 (_)、冒号 (:) 和句点 (.)。

• 最后一个字符不能是连字符、冒号或句点。以这些字符结尾的 URL 虽然被 XHTML 允许，但从纯文本中提取起来可能很麻烦。

• 每个 id 在文档中必须是唯一的。

此外，返回的值在 Pod::Simple::XHTML 对象的上下文中将是唯一的，除非传递第二个参数为真值。ID 属性在单个 XHTML 文档中应始终是唯一的，但如果创建的不是 ID 而是指向 ID 的 URL 哈希（即，如果需要在 <a href="#foo">foo</a> 中放置 "#foo"），则传递真值。

#batch_mode_page_object_init

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

由 Pod::Simple::HTMLBatch 调用，以便该类有机会初始化转换器。在内部，它将 batch_mode 属性设置为 true 并设置 batch_mode_current_level()，但 Pod::Simple::XHTML 目前不使用这些功能。子类可能会使用它们。

#另请参阅

Pod::Simple、Pod::Simple::Text、Pod::Spell

#支持

有关 POD 和 Pod::Simple 的问题或讨论应发送到 [email protected] 邮件列表。发送空邮件到 [email protected] 订阅。

此模块在开放的 GitHub 存储库中进行管理，https://github.com/perl-pod/pod-simple/。欢迎您随意分叉并贡献，或克隆 git://github.com/perl-pod/pod-simple.git 并发送补丁！

欢迎针对 Pod::Simple 的补丁。请将错误报告发送到 <[email protected]>。

#版权和免责声明

版权所有 (c) 2003-2005 Allison Randal。

此库是免费软件；您可以根据与 Perl 本身相同的条款重新分发它和/或修改它。

本程序的发布旨在提供帮助，但没有任何保证；甚至没有对适销性或特定用途适用性的暗示保证。

#致谢

感谢 Hurricane Electric 允许我们使用其 在线 Linux 手册页 网站作为手册页链接。

感谢 search.cpan.org 允许我们使用该网站作为 Perl 模块链接。

#作者

Pod::Simpele::XHTML 由 Allison Randal <[email protected]> 创建。

Pod::Simple 由 Sean M. Burke <[email protected]> 创建。但他已经退休了，请不要打扰他。

Pod::Simple 由以下人员维护：

• Allison Randal [email protected]

• Hans Dieter Pearcey [email protected]

• David E. Wheeler [email protected]

Perldoc 浏览器由 Dan Book (DBOOK) 维护。如果您遇到网站本身、搜索或文档渲染方面的任何问题，请通过 GitHub 问题跟踪器 或 电子邮件 联系他。

Perl 文档由 Perl 5 开发者在 Perl 开发过程中维护。如果您遇到文档内容或格式方面的任何问题，请通过 Perl 问题跟踪器、邮件列表 或 IRC 联系他们。