Pod::Simple::HTML

(源代码, CPAN)

版本 3.43

内容

名称
概要
描述
从命令行调用
从 Perl 调用
- 最小代码
- 更详细的示例
方法
子类化
参见
支持
版权和免责声明
致谢
作者

#名称

Pod::Simple::HTML - 将 Pod 转换为 HTML

#概要

perl -MPod::Simple::HTML -e Pod::Simple::HTML::go thingy.pod

#描述

此类用于生成 Pod 文档的 HTML 渲染。

这是 Pod::Simple::PullParser 的子类，并继承其所有方法（和选项）。

请注意，如果您想对大量 Pod 文档进行批量转换为 HTML，请查看模块 Pod::Simple::HTMLBatch。

#从命令行调用

待办事项

perl -MPod::Simple::HTML -e Pod::Simple::HTML::go Thing.pod Thing.html

#从 Perl 调用

#最小代码

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

#更详细的示例

use Pod::Simple::HTML;

设置内容类型

$Pod::Simple::HTML::Content_decl =  q{<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" >};

my $p = Pod::Simple::HTML->new;

包含单个 JavaScript 源代码

$p->html_javascript('http://abc.com/a.js');

或者在标题中插入多个 JavaScript 源代码（或者包含任何内容，尽管不建议这样做）

$p->html_javascript('
    <script type="text/javascript" src="http://abc.com/b.js"></script>
    <script type="text/javascript" src="http://abc.com/c.js"></script>');

在标题中包含单个 CSS 源代码

$p->html_css('/style.css');

或者插入多个 CSS 源代码

$p->html_css('
    <link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://remote.server.com/jquery.css">
    <link rel="stylesheet" type="text/css" title="pod_stylesheet" href="/style.css">');

告诉解析器输出应该放在哪里。在本例中，它将被放置在 $html 变量中

my $html;
$p->output_string(\$html);

解析并处理包含 pod 的文件

$p->parse_file('path/to/Module/Name.pm');

#方法

TODO 所有（大多数？）访问器方法

以下变量需要在调用 ->new 构造函数之前设置。

设置在打开的 <html> 标签之前包含的字符串

  $Pod::Simple::HTML::Doctype_decl = qq{<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
	 "http://www.w3.org/TR/html4/loose.dtd">\n};

设置 HTML 头部的 content-type：（默认值为 ISO-8859-1）

$Pod::Simple::HTML::Content_decl =  q{<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" >};

设置将嵌入 F、C 标签和逐字文本的打开标签中的值。F 映射到 <em>，C 映射到 <code>，逐字文本映射到 <pre>（计算机术语默认为空字符串）

$Pod::Simple::HTML::Computerese =  ' class="some_class_name';

#html_css

#html_javascript

#title_prefix

#title_postfix

#html_header_before_title

这包括 <title> 打开标签之前的任何内容，包括文档类型，以及包括打开的 <title> 标签。以下调用将将其设置为一个简单的 HTML 文件

$p->html_header_before_title('<html><head><title>');

#top_anchor

默认情况下，Pod::Simple::HTML 在 HTML 的顶部添加一个虚拟锚点。您可以通过调用来更改它

$p->top_anchor('<a name="zz" >');

#html_h_level

通常 =head1 将变为 <h1>，=head2 将变为 <h2> 等等。使用 html_h_level 方法将更改这些级别，设置 =head1 标签的 h 级别

$p->html_h_level(3);

将确保 =head1 将变为 <h3>，=head2 将变为 <h4> 等等...

#索引

如果要将索引（实际上是目录）添加到生成的 HTML 的顶部，请将其设置为某个真值。

$p->index(1);

#html_header_after_title

包括 </title> 的结束标签，以及从头部的其余部分到正文的开始

$p->html_header_after_title('</title>...</head><body id="my_id">');

#html_footer

文档的最后部分

$p->html_footer( qq[\n<!-- end doc -->\n\n</body></html>\n] );

#子类化

可以使用上面描述的任何方法，但为了进一步定制，需要覆盖一些方法

package My::Pod;
use strict;
use warnings;

use base 'Pod::Simple::HTML';

# needs to return a URL string such
# http://some.other.com/page.html
# #anchor_in_the_same_file
# /internal/ref.html
sub do_pod_link {
  # My::Pod object and Pod::Simple::PullParserStartToken object
  my ($self, $link) = @_;

  say $link->tagname;          # will be L for links
  say $link->attr('to');       # 
  say $link->attr('type');     # will be 'pod' always
  say $link->attr('section');

  # Links local to our web site
  if ($link->tagname eq 'L' and $link->attr('type') eq 'pod') {
    my $to = $link->attr('to');
    if ($to =~ /^Padre::/) {
        $to =~ s{::}{/}g;
        return "/docs/Padre/$to.html";
    }
  }

  # all other links are generated by the parent class
  my $ret = $self->SUPER::do_pod_link($link);
  return $ret;
}

1;

同时在 script.pl 中

use My::Pod;

my $p = My::Pod->new;

my $html;
$p->output_string(\$html);
$p->parse_file('path/to/Module/Name.pm');
open my $out, '>', 'out.html' or die;
print $out $html;

待办事项

也许覆盖 do_beginning do_end

#另请参阅

Pod::Simple，Pod::Simple::HTMLBatch

TODO：一个包含示例 Pod 输入和 HTML 输出的语料库？或者常见的习语？

#支持

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

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

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

#版权和免责声明

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

此程序按“现状”提供，不提供任何形式的保证，无论是明示还是暗示，包括但不限于适销性保证和特定用途适用性保证。

#致谢

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

感谢 search.cpan.org 允许使用该网站用于 Perl 模块链接。

#作者

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

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

Allison Randal [email protected]
Hans Dieter Pearcey [email protected]
David E. Wheeler [email protected]