.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Man 3pm"
.TH Locale::Po4a::Man 3pm "2023-01-03" "Po4a 工具" "Po4a 工具"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "名稱"
.IX Header "名稱"
Locale::Po4a::Man \- 將手動頁面從/轉換為 \s-1PO\s0 檔案
.SH "描述"
.IX Header "描述"
Po4a (\s-1PO\s0 For Anything) 專案的目標是在文件等不需要翻譯的領域使用 gettext 工具簡化翻譯(更有趣的是，簡化翻譯的維護)。
.PP
Locale::Po4a::Man 是一個模組，用於幫助將 nroff 格式(手冊頁的語言)的文件翻譯成其他 [人類] 語言。
.SH "使用 PO4A::MAN 進行翻譯"
.IX Header "使用 PO4A::MAN 進行翻譯"
這個模組非常努力地讓翻譯員的工作變得更容易。因此，呈現給翻譯人員的文字不是手冊頁中的文字的逐字副本。實際上，nroff 格式的粗略部分是隱藏的，這樣翻譯人員就不會把它們搞砸了。
.SS "文字換行"
.IX Subsection "文字換行"
未縮排的段落會自動為翻譯器重新換行。這可能會在生成的輸出中導致一些細微的差異，因為 groff 使用的重新包裝規則不是很清楚。例如，有時保留括號後的兩個空格。
.PP
無論如何，不同之處只在於換行段落中額外空格的位置，我認為這是值得的。
.SS "字型規格"
.IX Subsection "字型規格"
第一個更改是關於字型更改規範。在 nroff 中，有幾種方法可以指定給定的單詞應該用小寫、粗體還是斜體書寫。在要翻譯的文字中，只有一種方法，借用 \s-1POD\s0 (Perl Online Documentation) 格式：
.IP "I<text> \*(-- 斜體文字" 4
.IX Item "I<text> 斜體文字"
等效於 \efItext\efP 或 \*(L".I text\*(R"
.IP "B<text> \*(-- 粗體文字" 4
.IX Item "B<text> 粗體文字"
等效於 \efBtext\efP 或 \*(L".B text\*(R"
.IP "R<text> \*(-- 羅馬文字" 4
.IX Item "R<text> 羅馬文字"
等效於 \efRtext\efP
.IP "CW<text> \*(-- 等長寬度文字" 4
.IX Item "CW<text> 等長寬度文字"
等效於 \ef(CWtext\efP 或 \*(L".CW text\*(R"
.PP
備註：並非所有 groff 裝置都提供 \s-1CW\s0 面。不推薦使用。這是為了您的方便而提供的。
.SS "字元自動音譯"
.IX Subsection "字元自動音譯"
Po4a 會自動音譯某些字元，以簡化翻譯或稽核翻譯。以下是音譯的列表：
.IP "連字元" 4
.IX Item "連字元"
手冊頁中的連字元 (\-) 和減號 (\e\-) 在 \s-1PO\s0 檔案中都音譯為簡單的破折號 (\-)。然後，在將翻譯插入到輸出文件中時，所有破折號都音譯為 roff 減號 (\e\-)。
.Sp
翻譯人員可以在翻譯中使用 roff 字形 '\e[hy]' 強制使用連字元。
.IP "不間斷空格" 4
.IX Item "不間斷空格"
翻譯人員可以在翻譯中使用不間斷空格。這些不間斷空格 (latin1 中的 0xA0)將音譯為 roff 不間斷空格('\e ')。
.IP "引用音譯" 4
.IX Item "引用音譯"
`` 和 '' 分別音譯為 \e*(lq 和 \e*(rq.
.Sp
為了避免這些音譯，翻譯人員可以插入零寬度 roff 字元(即分別使用 '\e&' 或 '\e&')。
.SS "在翻譯中放 '<' 和 '>'"
.IX Subsection "在翻譯中放 '<' 和 '>'"
由於這些字元用於分隔字型修改後的部分，因此您不能逐字使用它們。改為使用 E<lt> 和 E<gt> (與 \s-1POD\s0 中相同)。
.SH "此模組接受的選項"
.IX Header "此模組接受的選項"
以下是此模組的特定選項：
.IP "\fBdebug\fR" 4
.IX Item "debug"
啟用此模組某些內部機制的除錯。 使用源檢視哪些部件可以除錯。
.IP "\fBverbose\fR" 4
.IX Item "verbose"
增加詳細程度。
.IP "\fBgroff_code\fR" 4
.IX Item "groff_code"
此選項控制模組在遇到.de、.ie 或 .if 節時的行為。它可以採用下列值：
.RS 4
.IP "\fIfail\fR" 4
.IX Item "fail"
這是預設值。遇到 .de、.ie 或 .if 章節時，模組將失敗。
.IP "\fIverbatim\fR" 4
.IX Item "verbatim"
指示必須按原樣將 .de、.ie 或 .if 節從原始文件複製到翻譯後的文件。
.IP "\fItranslate\fR" 4
.IX Item "translate"
指示將為翻譯建議 .de、.ie 或 .if 章節。僅當這些部分之一中包含可翻譯字串時，才應使用此選項。否則，應該首選 \fIverbatim\fR。
.RE
.RS 4
.RE
.IP "\fBgenerated\fR" 4
.IX Item "generated"
該選項指定檔案是生成的，並且 po4a 不應嘗試檢測手冊頁是否由另一種格式生成。要在生成的手冊頁上使用 po4a，此選項是必需的。請注意，轉換生成的頁面而不是源頁面通常更脆弱，因此不是一個好主意。
.IP "\fBmdoc\fR" 4
.IX Item "mdoc"
此選項僅對 mdoc 頁面有用。
.Sp
它透過告訴 po4a 不翻譯 '\s-1NAME\s0' 部分來選擇更嚴格的 mdoc 格式支援。翻譯了 '\s-1NAME\s0' 部分的 mdoc 頁面不會生成任何頁首或頁尾。
.Sp
根據 groff_mdoc，名稱，概要和描述
章節是必填項。
翻譯的概要或描述部分沒有已知問題，
但您也可以這樣指定這些部分：
 \-o mdoc=NAME,SYNOPSIS,DESCRIPTION
.Sp
此 mdoc 問題也可以透過如下附錄解決：
 PO4A\-HEADER:mode=before;position=^.Dd
 .TH \s-1DOCUMENT_TITLE 1\s0 \*(L"月日，年\*(R" 作業系統 \*(L"章節名\*(R"
.PP
The following options specify the behavior of a user-defined macro (with a .de request), or of a classical macro that is not supported by po4a.  They take as argument a comma-separated list of macros.  For example:
.PP
.Vb 1
\& \-o noarg=FO,OB,AR \-o translate_joined=BA,ZQ,UX
.Ve
.PP
注意：如果某個宏不受 po4a 支援，並且您認為它是標準的 roff 宏，那麼您應該將其提交給 po4a 開發團隊。
.IP "\fBuntranslated\fR" 4
.IX Item "untranslated"
\&\fBuntranslated\fR 指示不必翻譯此宏(在其引數處)。
.IP "\fBnoarg\fR" 4
.IX Item "noarg"
\&\fBnoarg\fR 類似於 \fBuntransted\fR，不同之處在於 po4a 將驗證沒有引數新增到此宏。
.IP "\fBtranslate_joined\fR" 4
.IX Item "translate_joined"
\&\fBtranslate_joined\fR 指示 po4a 必須提議翻譯宏的引數。
.IP "\fBtranslate_each\fR" 4
.IX Item "translate_each"
對於 \fBtranslate_each\fR，除了每個引數將被單獨翻譯外，還將為翻譯建議引數。
.IP "\fBno_wrap\fR" 4
.IX Item "no_wrap"
該選項將逗號分隔的對列表 \fIbegin\fR:\fIend\fR 作為引數，其中 \fIbegin\fR 和 \fIend\fR 是分隔不應該重新換行的節的開始和結束的命令。
.Sp
注意：不執行任何測試來確保 \fIend\fR 命令與其 \fIbegin\fR 命令匹配；任何結束命令都會停止 no_wrap 模式。如果您有一個沒有 \fIend\fR (分別是 \fIbegin\fR )的 \fIbegin\fR  (分別是 \fIend\fR)宏，則可以指定現有的 \fIend\fR (如 fi)或 \fIbegin\fR (如 nf)作為對應宏。這些宏 (及其引數) 不會被翻譯。
.IP "\fBinline\fR" 4
.IX Item "inline"
此選項指定不得拆分當前段落的逗號分隔宏列表。然後，要轉換的字串將包含 \fIfoo <.bar baz qux> quux\fR，其中 \fIbar\fR 是應該內聯的命令，\fIbaz qux\fR 是其參數。
.IP "\fBunknown_macros\fR" 4
.IX Item "unknown_macros"
此選項指示找到未知宏時 po4a 的行為。預設情況下，po4a 失敗並顯示警告。它可以採用以下值： \fBfailed\fR (預設值)、\fBuntranslated\fR、\fBnoarg\fR、\fBtranslate_joined\fR 或 \fBtranslate_each\fR (有關這些值的解釋，請參見上文)。
.SH "創作符合 PO4A::MAN 的手冊頁"
.IX Header "創作符合 PO4A::MAN 的手冊頁"
這個模組仍然非常有限，而且將永遠如此，因為它不是一個真正的 nroff 直譯器。做一個真正的 nroff 直譯器是可能的，允許作者使用所有現有的宏，甚至在他們的頁面中定義新的宏，但我們不想這樣做。這太難了，我們認為沒有必要。我們確實認為，如果手冊頁的作者想要看到他們的作品被翻譯，他們可能必須適應，以減輕翻譯人員的工作。
.PP
因此，po4a 中實現的 man 解析器有一些我們不太願意糾正的已知限制，如果您希望看到翻譯人員處理您的文件，這些限制將構成您必須避免的一些陷阱。
.SS "不要在 nroff 中程式設計"
.IX Subsection "不要在 nroff 中程式設計"
nroff 是一種完整的程式語言，具有宏定義、條件等功能。因為這個解析器不是一個功能齊全的 nroff 直譯器，所以它在使用這些工具的頁面上將失敗 (我框中大約有200個這樣的頁面)。
.SS "使用普通宏集"
.IX Subsection "使用普通宏集"
仍然有一些宏不受 po4a::man 支援。這只是因為我找不到任何關於它們的文件。這是我的計算機上使用的不受支援的宏的列表。請注意，此列表並不詳盡，因為程式在第一個遇到的不受支援的宏上失敗。如果您有關於這些宏的任何資訊，我很樂意新增對它們的支援。由於這些宏，po4a::man 無法訪問我框中的大約 250 個頁面。
.PP
.Vb 11
\& ..               ."              .AT             .b              .bank
\& .BE              ..br            .Bu             .BUGS           .BY
\& .ce              .dbmmanage      .do                             .En
\& .EP              .EX             .Fi             .hw             .i
\& .Id              .l              .LO             .mf
\& .N               .na             .NF             .nh             .nl
\& .Nm              .ns             .NXR            .OPTIONS        .PB
\& .pp              .PR             .PRE            .PU             .REq
\& .RH              .rn             .S<             .sh             .SI
\& .splitfont       .Sx             .T              .TF             .The
\& .TT              .UC             .ul             .Vb             .zZ
.Ve
.SS "從 po4a 隱藏文字"
.IX Subsection "從 po4a 隱藏文字"
有時，作者知道有些部分是不可翻譯的，不應該用 po4a 提取。例如，選項可能接受 \fIother\fR 引數，並且 \fIother\fR 也可能顯示為列表的最後一項。在第一種情況下，\fIother\fR 應該是不可翻譯的。在第二種情況下，應該翻譯 \fIother\fR。
.PP
在這種情況下，作者可以避免 po4a 提取一些字串，使用一些特殊的 groff 結構：
.PP
.Vb 1
\& .if !\*(Aqpo4a\*(Aqhide\*(Aq .B other
.Ve
.PP
(這將需要 \fB\-o groff_code=verbatim\fR 選項)
.PP
還可以定義一個新的宏來自動執行：
 .de IR_untranslated
 .    \s-1IR\s0 \e\e$@
 ..
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
(這將需要選項 \fB\-o groff_code=verbatim\fR 和 \fB\-o untranslated=IR_untranslated\fR；使用此構造，不嚴格需要 \fB.if !'po4a'hide'\fR 條件，因為 po4a 不會解析宏定義的內部)
.PP
或使用別名：
 .als IR_untranslated \s-1IR\s0
.PP
.Vb 1
\& .IR_untranslated \e\-q ", " \e\-\e\-quiet
.Ve
.PP
這將需要 \fB\-o untranslated=als,IR_untranslated\fR 選項。
.SS "結論"
.IX Subsection "結論"
總結這一節，請保持簡單，在編寫手冊頁時不要試圖變得聰明。很多事情在 nroff 中是可能的，並且不被這個解析器支援。例如，不要試圖擾亂 \ec 來中斷文字處理(就像我框中的 40 頁一樣)。或者，確保將宏引數與宏本身放在同一行。我知道它在 nroff 中是有效的，但是會使解析器過於複雜而無法處理。
.PP
當然，另一種可能是使用另一種更便於翻譯的格式(比如使用 po4a::pod 的 POD，或者像 \s-1SGML\s0 這樣的 \s-1XML\s0 家族之一)，但是多虧了 po4a::man，它不再需要了。也就是說，如果您的文件的源格式是 \s-1POD\s0 或 XML，那麼轉換源格式而不是這個生成的格式可能更聰明。在大多數情況下，po4a::man 將檢測生成的頁面併發出警告。它甚至會拒絕處理 \s-1POD\s0 生成的頁面，因為這些頁面由 po4a::pod 完美地處理，而且它們的 nroff 對應項定義了許多我不想編寫支援的新宏。在我的機器上，4323 個頁面中的 1432 個是從 \s-1POD\s0 生成的，將被 po4a::man 忽略。
.PP
在大多數情況下， po4a::man 會發現問題並拒絕處理頁面，發出一個適應的訊息。在一些罕見的情況下，程式將沒有警告完成，但輸出將是錯誤的。這種情況稱為 \*(L"bugs\*(R"；如果遇到這種情況，請務必報告此情況，並在可能時進行修復…
.SH "此模組的狀態"
.IX Header "此模組的狀態"
此模組可用於大多數現有手冊頁。
.PP
一些測試定期在 Linux 機器上執行：
.IP "\(bu" 4
三分之一的頁面被拒絕，因為它們是從 po4a 支援的另一種格式 (例如 \s-1POD\s0 或 \s-1SGML\s0) 生成的。
.IP "\(bu" 4
10% 的剩餘頁面因錯誤而被拒絕(例如，不支援 groff 宏)。
.IP "\(bu" 4
然後，只有不到 1% 的頁面被 po4a 靜默接受，但存在重大問題 (即丟失單詞或插入新詞)
.IP "\(bu" 4
處理其他頁面時通常沒有比間距差異或換行更重要的差異 (只有不到 10% 的已處理頁面出現字型問題)。
.SH "參見"
.IX Header "參見"
\&\fBLocale::Po4a::Pod\fR\|(3pm), \fBLocale::Po4a::TransTractor\fR\|(3pm), \fBpo4a\fR\|(7)
.SH "作者"
.IX Header "作者"
.Vb 3
\& Denis Barbier <barbier@linuxfr.org>
\& Nicolas François <nicolas.francois@centraliens.net>
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH "版權和許可"
.IX Header "版權和許可"
版權所有 © 2002\-2008 \s-1SPI,\s0 Inc.
.PP
此程式是自由軟體；您可以根據 \s-1GPL\s0 條款重新分發和/或修改它(請參閱複製檔案)。