內容

• 名稱
• 語法
• 說明
  • 最小程式碼
• 方法
  • 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

檔案的 Document Type 標籤。此選項預設未設定。

#html_charset

html_header_tags 預設建立的 Content-Type meta 標籤中要宣告的字元集。請注意，如果變更 html_header_tags 的值，此選項將會被忽略。預設為「ISO-8859-1」。

#html_header_tags

文件標頭的其他任意 HTML 標籤。預設值只有一個內容類型標頭標籤

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

在此處新增其他 meta 標籤，或區塊內 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 中輸出標頭或頁尾，請將這些選項設定為空字串。

#索引

是否在每個頁面頂端新增目錄（為了傳統，稱為索引）。

#錨點項目

是否將每個定義 =item 指令設為錨點。如果您想要連結到特定的 =item 指令（輸出為 <dt> 元素），就需要啟用這項功能。預設為停用。

#回溯連結

是否將每個 =head1 指令轉換為指向頁面頂端（特別是開啟的 body 標籤）的連結。

#子類別化

如果標準選項不夠用，您可能需要建立 Pod::Simple::XHMTL 的子類別。以下是子類別化時您最有可能想要覆寫的方法候選清單。

#處理文字

此方法處理任何元素內的文字主體：段落的主體，或 "=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);
}

#處理程式碼

此方法處理標記為程式碼的文字主體。例如，您可能會覆寫此方法以插入語法高亮顯示。基本實作僅跳脫文字。

呼叫回方法 start_code 和 end_code 在呼叫 handle_code 之前和之後發出 code 標籤，因此如果您不適合此包裝，您可能需要與 handle_code 一起覆寫這些標籤。

請注意，如果 C<...> 序列內有巢狀格式化程式碼，則程式碼可能會分成多個區段。在這種情況下，在呼叫 handle_code 之間可能會發出其他標記標籤。如果啟用 codes_in_verbatim 選項，則對逐字陳述區段也是如此。

#accept_targets_as_html

此方法的行為類似於 accept_targets_as_text，但也會將區域標記為應逐字發出其內容的區域，而不會在 div 元素中進行 HTML 實體跳脫或包裝。

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

將 man 頁面連結目標和數字區段解析為 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)、連字號 (-)、底線 (_)、冒號 (:) 和句點 (.)。

• 最後一個字元不能是連字號、冒號或句點。雖然 XHTML 允許以這些字元結尾的 URL，但從純文字中擷取這些 URL 可能很麻煩。

• 每個 id 在文件中必須是唯一的。

此外，傳回的值在 Pod::Simple::XHTML 物件的內容中將是唯一的，除非傳遞第二個引數為 true 值。ID 屬性在單一 XHTML 文件中應始終是唯一的，但如果您建立的不是 ID 而是指向 ID 的 URL hash，請傳遞 true 值（即，如果您需要在 <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 的問題或討論，請寄送電子郵件至 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>。

#著作權和免責聲明

著作權所有 (c) 2003-2005 Allison Randal。

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

散布此程式時，希望它會對您有所幫助，但我們不提供任何保證；甚至不保證適售性或適用於特定用途。

#致謝

感謝 Hurricane Electric 允許我們使用其 線上 Linux 手冊頁 網站來提供手冊頁連結。

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

#作者

Pod::Simpele::XHTML 是由 Allison Randal <allison@perl.org> 所建立。

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

Perldoc Browser 由 Dan Book (DBOOK) 維護。如有任何與網站本身、搜尋或文件呈現相關的問題，請透過 GitHub 問題追蹤器 或 電子郵件 與他聯繫。

Perl 文件由 Perl 5 Porters 在 Perl 開發過程中維護。如有任何與文件內容或格式相關的問題，請透過 Perl 問題追蹤器、郵件清單 或 IRC 與他們聯繫。