Pod::Checker

(原始碼, CPAN)

版本 1.75

#名稱

Pod::Checker - 檢查 pod 文件的語法錯誤

#語法

use Pod::Checker;

$syntax_okay = podchecker($filepath, $outputpath, %options);

my $checker = Pod::Checker->new(%options);
$checker->parse_from_file($filepath, \*STDERR);

#選項/參數

$filepath 是要讀取的輸入 POD，而 $outputpath 是要寫入 POD 語法錯誤訊息的地方。任一參數都可以是表示檔案路徑的純量，或是開啟檔案處理程序的參考。如果未指定，輸入檔案預設為 \*STDIN，而輸出檔案預設為 \*STDERR。

#podchecker()

此函式可以接受選項雜湊

#-warnings => val: 開啟/關閉警告。val 通常為 1 表示開啟，但較高的值會觸發額外的警告。請參閱 "Warnings"。
#-quiet => val: 如果 val 為 true，則不列印任何錯誤/警告。

#說明

podchecker 會執行 Perl5 POD 格式文件語法檢查。

歡迎好奇/有抱負的使用者提出他們希望在 Pod::Checker 和 podchecker 中看到的其他功能，並驗證檢查是否與 perlpod 一致。

目前執行下列檢查

未知的「=xxxx」指令、「X<...>」內部序列，以及未終止的內部序列。
檢查 =begin 和 =end 是否正確配對。此類區塊的內容通常會被忽略，也就是說不會執行語法檢查。
檢查 =over、=item 和 =back 是否正確巢狀和配對。
檢查是否具有相同的巢狀內部序列（例如 L<...L<...>...>）。
檢查 E<...> 實體是否格式錯誤或不存在。
檢查超連結 L<...> 的語法是否正確。詳情請參閱 perlpod。
檢查未解析的內部文件連結。此檢查也可能會顯示拼寫錯誤的連結，這些連結看起來像是內部連結，但應該是連結到其他內容。

#診斷

#錯誤

空的 =headn

沒有任何文字的標題（=head1 或 =head2）？那不是標題！
第 N 行的 =over 沒有關閉 =back
您在「=headN」之前忘記了「=back」
=over 是文件中的最後一件事嗎？

=over 指令沒有在下一標題（=head1 或 =head2）或檔案結尾之前對應的 =back。
在任何「=over」之外的「=item」
沒有 =over 的 =back

在 =over/=back 區塊之外找到了 =item 或 =back 指令。
在 =over N 中不能有 0

您需要縮排一個嚴格大於 0 的空格數，而不是 0。
=over 應該是：'=over' 或 '=over positive_number'

沒有引數的 =over，或其引數為一個嚴格大於 0 的數字。
=begin TARGET 沒有匹配的 =end TARGET

找到了沒有匹配 =end 指令的 =begin 指令。
沒有目標的 =begin？

找到了沒有後接格式器規範的 =begin 指令。
=end TARGET 沒有匹配的 =begin。

找到了獨立的 =end 指令。
沒有目標的「=end」？

「=end」指令需要有一個目標，就像 =begin 指令一樣。
「=end TARGET」無效。

TARGET 需要是一個單字
=end CONTENT 不匹配 =begin TARGET

CONTENT 需要匹配 =begin 的 TARGET。
沒有目標的 =for？

=for 指令之後沒有指定格式器。
未解析的內部連結 NAME

給定連結至 NAME 在目前的 POD 中沒有相符的節點。當單字節點名稱未包含在 "" 中時也會發生此情況。
未知指令：CMD

已找到無效的 POD 指令。有效指令為 =head1、=head2、=head3、=head4、=over、=item、=back、=begin、=end、=for、=pod、=cut
刪除未知格式化程式碼 SEQ

已遇到無效的標記指令。有效指令為：B<>、C<>、E<>、F<>、I<>、L<>、S<>、X<>、Z<>
未終止的 SEQ<> 序列

未封閉的格式化程式碼
E<...> 包圍著奇怪的內容

找不到的 STRING 無法解釋為字元實體。
空的 E<>
空的 L<>
空的 X<>

E、L 和 X 格式化程式碼中需要有內容。
在 =pod / =cut 之後有雜湊文字

=pod 和 =cut 指令不接受任何引數。
=back 不接受任何參數，但您說 =back ARGUMENT

=back 指令不接受任何引數。
=pod 指令不應超過一行長！忽略所有 N 行內容

不言自明
=cut 發現於 pod 區塊之外。

在非 POD 中間找到 '=cut' 指令
無效的 =encoding 語法：CONTENT

=encoding 指令中的語法錯誤

#警告

這些不一定會造成問題，但表示風格平庸。

巢狀指令 CMD<...CMD<...>...>

已找到兩個巢狀的相同標記指令。通常這沒有意義。
連結目標 name 的多個出現次數 (N)

POD 檔案有一些 =item 和/或 =head 指令具有相同的文字。這樣一來，指向此類文字的潛在超連結無法唯一。此警告僅在警告層級大於 1 時列印。
段落中只包含空白字元的行

在看似空白的行上有一些空白字元。POD 對此類事物非常敏感，因此會標示出來。vi 使用者開啟 list 選項以避免此問題。
=item 沒有內容

有一個清單 =item 沒有文字內容。您可能想要刪除空的項目。
您不能有 =items（如第 N 行），除非在 =over 之後的第 1 件事是 =item

由 =over 引入的清單以文字或逐字段落開始，但以 =item 繼續。將非項目段落移出 =over/=back 區塊。
預期 '=item 預期值'
預期 '=item *'
可能的 =item 類型不符：發現 'x' 引導假設的定義 =item

例如以類似項目符號的 =item 開始的清單，並以編號清單繼續。這顯然不一致。對於大多數翻譯人員，第一個 =item 的類型會決定清單的類型。
您有 '=item x'，而不是預期的 '=item N'

錯誤編號的 =item 數字；它們需要連續遞增。
E<內容> 中的未知 E 內容

發現不屬於標準 ISO 集合或 POD 特殊字元 verbar 和 sol 的字元實體。目前，只有在發現沒有 Unicode 字元的字元實體時，才會出現此警告。這應修復為遵循原始警告。
空的 =over/=back 區塊

以 =over 開啟的清單不包含任何內容。
前一段落中的空區段

前一段落（由 =head 指令引入）不包含任何有效內容。這通常表示遺漏了一些東西。注意：=head1 後面緊接著 =head2 不會觸發此警告。
NAME 區段中的逐字段落

NAME 區段（=head1 NAME）應包含一個段落，其中包含腳本/模組名稱，後跟破折號 `-' 和對該事物用途的非常簡短的描述。
=headn 沒有前置較高層級

例如，如果在 POD 檔案中，=head1 之前有 =head2。
非空的 Z<>

Z<> 序列應為空。警告：此問題在 Pod::Simple 中偵測到，並會由任何客戶端程式碼標記為錯誤；無論如何，Z<...> 的任何內容都將被忽略。

# 超連結

有一些關於格式錯誤超連結的警告

忽略連結中的前導/尾隨空白

L<...> 內容的開頭或結尾有空白。
替代文字/節點 '%s' 包含未跳脫的 | 或 /

字元 | 和 / 在 L<...> 上下文中是特殊的。雖然超連結剖析器會盡力確定在有疑問的情況下哪個 "/" 是文字，哪個是分隔符號，但應該像這樣跳脫這些文字字元
```
/     E<sol>
|     E<verbar>
```

請注意，錯誤/警告的行號可能是指錯誤/警告存在的段落開頭行號，而不是錯誤/警告所在的行號。此錯誤存在於與格式化代碼相關的錯誤/警告中。此問題應已修正。

#傳回值

podchecker 會傳回找到的 POD 語法錯誤數目，或是在檔案中完全找不到任何 POD 指令時傳回 -1。

#範例

請參閱 "SYNOPSIS"

#腳本

此發行版附帶的 podchecker 腳本是此模組的精簡包裝器。請使用下列方式參閱線上手冊

podchecker -help
podchecker -man

#介面

此模組在檢查時會收集文件屬性，例如超連結的節點 (=headX、=item) 和索引條目 (X<>)。POD 轉譯器可以使用此功能在實際開始轉換前執行語法檢查並取得節點。此功能在執行時間上較耗時，但可進行非常穩健的轉換。

自 v1.24 起，Pod::Checker 模組僅使用 poderror 方法來列印錯誤和警告。摘要輸出 (例如「Pod 語法正確」) 已從模組中移除，並已包含在 podchecker (腳本) 中。這允許 Pod::Checker 的使用者完全控制輸出行為。podchecker (腳本) 的使用者會獲得眾所周知的行為。

v1.45 繼承自 Pod::Simple，而所有先前版本都繼承自 Pod::Parser。在使用 Pod::Checker 時，請不要使用 Pod::Simple 的介面，除非此介面已記錄在此頁面的某處。我再說一次，請勿使用 POD::SIMPLE 的介面。

下列清單記載了對 Pod::Simple 的覆寫，主要是為了讓 Pod::Coverage 滿意

#end_B
#end_C
#end_Document
#end_F
#end_I
#end_L
#end_Para
#end_S
#end_X
#end_fcode
#end_for
#end_head
#end_head1
#end_head2
#end_head3
#end_head4
#end_item
#end_item_bullet
#end_item_number
#end_item_text
#handle_pod_and_cut
#handle_text
#handle_whiteline
#hyperlink
#scream
#start_B
#start_C
#start_Data
#start_F
#start_I
#start_L
#start_Para
#start_S
#start_Verbatim
#start_X
#start_fcode
#start_for
#start_head
#start_head1
#start_head2
#start_head3
#start_head4
#start_item_bullet
#start_item_number
#start_item_text
#start_over
#start_over_block
#start_over_bullet
#start_over_empty
#start_over_number
#start_over_text
#whine

#Pod::Checker->new( %options )

傳回繼承自 Pod::Simple 的新 Pod::Checker 物件的參考，並用於稍後呼叫所需的方法。辨識下列選項

-warnings => num 如果 num 為 true，則印出警告。num 值越大，印出的警告越多。目前只有 1 和 2 等級。

-quiet => num 如果 num 為 true，則不印出任何錯誤/警告。這在 Pod::Checker 用於將 POD 程式碼從 POD 格式化程式中轉換為純文字時很有用。

#$checker->poderror( @args )

#$checker->poderror( {%opts}, @args )

用於印出錯誤和警告的內部方法。如果未提供選項，則僅印出 "@_”。辨識下列選項並用於形成輸出

-msg

在 @args 之前要印出的訊息。

-line

發生錯誤的行號。

-file

發生錯誤的檔案（名稱）。預設為正在處理的目前檔案名稱。

-severity

錯誤等級，應該是 'WARNING' 或 'ERROR'。

#$checker->num_errors()

設定（如果指定引數）並擷取找到的錯誤數目。

#$checker->num_warnings()

設定（如果指定引數）並擷取找到的警告數目。

#$checker->name()

設定（如果指定引數）並擷取在 =head1 NAME 區段中找到的 POD 標準名稱。

#$checker->node()

新增（如果指定引數）並擷取目前 POD 的節點（由 =headX 和 =item 定義）。節點會按出現順序傳回。它們包含純文字，每個空白字元都會壓縮成一個空白。

#$checker->idx()

新增（如果指定引數）並擷取目前 POD 的索引項目（由 X<> 定義）。它們包含純文字，每個空白字元都會壓縮成一個空白。

#$checker->hyperlinks()

擷取包含連結至目前 POD 之外的項目（由 L<> 定義）的陣列。

每個都是具有下列方法的類別實例

#line()

傳回找到連結的大略行號

#type()

傳回連結的類型；其中之一："url"，例如 http://www.foo，"man"，例如說明頁面，或 "pod"。

#page()

傳回連結的頁面或網址。

#node()

傳回連結頁面中的錨點或節點，或空字串 ("")（如果連結中沒有出現）。

#作者

請使用 http://rt.cpan.org 回報錯誤。

Brad Appleton <bradapp@enteract.com>（初始版本），Marek Rouchal <marekr@cpan.org>，Marc Green <marcgreen@cpan.org>（移植至 Pod::Simple），Ricardo Signes <rjbs@cpan.org>（更多移植至 Pod::Simple），Karl Williamson <khw@cpan.org>（更多移植至 Pod::Simple）

根據 Tom Christiansen <tchrist@mox.perl.com> 編寫的 Pod::Text::pod2text() 程式碼

目錄

#名稱

#語法

#選項/參數

#podchecker()

#說明

#診斷

#錯誤

#警告

# 超連結

#傳回值

#範例

#腳本

#介面

#作者