Pod::Simple::HTML

(原始碼, CPAN)

版本 3.43

#名稱

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 head 中的內容類型：(預設為 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>（Computerese 預設為 ""）

$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> 等...

#index

如果您希望在產生的 HTML 頂端新增索引（實際上是目錄），請將其設定為某個真值。

$p->index(1);

#html_header_after_title

包含 </title> 的關閉標籤，以及 head 中的其餘部分，直到主體的開啟

$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 的問題或討論應傳送至 pod-people@perl.org 郵件清單。傳送一封空白電子郵件至 pod-people-subscribe@perl.org 以訂閱。

此模組在開放的 GitHub 儲存庫中管理，https://github.com/perl-pod/pod-simple/。歡迎分岔和貢獻，或複製 git://github.com/perl-pod/pod-simple.git 並發送修補程式！

歡迎針對 Pod::Simple 發送修補程式。請將錯誤報告寄送至 <bug-pod-simple@rt.cpan.org>。

#著作權和免責聲明

此程式庫是免費軟體；您可以在與 Perl 相同的條款下重新散布或修改它。

此程式以有用的希望散布，但沒有任何保證；甚至沒有適銷性或特定目的適用性的默示保證。

#致謝

感謝 Hurricane Electric 允許我們使用其 Linux 手冊頁面線上網站的 man 頁面連結。

感謝 search.cpan.org 允許我們使用此網站的 Perl 模組連結。

#作者

Pod::Simple 由 Sean M. Burke <sburke@cpan.org> 建立。但別打擾他，他已經退休了。

Pod::Simple 由下列人員維護

Allison Randal allison@perl.org
Hans Dieter Pearcey hdp@cpan.org
David E. Wheeler dwheeler@cpan.org