.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 1" .TH LOCALE::PO4A::MAN.3PM 1 2024-06-26 "perl v5.38.2" "User Contributed Perl Documentation" .\" 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 \- 將手動頁面從/轉換為 PO 檔案 .SH 描述 .IX Header "描述" Po4a (PO 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 中,有幾種方法可以指定給定的單詞應該用小寫、粗體還是斜體書寫。在要翻譯的文字中,只有一種方法,借用 POD (Perl Online Documentation) 格式: .IP "I \-\- 斜體文字" 4 .IX Item "I -- 斜體文字" 等效於 \efItext\efP 或 ".I text" .IP "B \-\- 粗體文字" 4 .IX Item "B -- 粗體文字" 等效於 \efBtext\efP 或 ".B text" .IP "R \-\- 羅馬文字" 4 .IX Item "R -- 羅馬文字" 等效於 \efRtext\efP .IP "CW \-\- 等長寬度文字" 4 .IX Item "CW -- 等長寬度文字" 等效於 \ef(CWtext\efP 或 ".CW text" .PP 備註:並非所有 groff 裝置都提供 CW 面。不推薦使用。這是為了您的方便而提供的。 .SS 字元自動音譯 .IX Subsection "字元自動音譯" Po4a 會自動音譯某些字元,以簡化翻譯或稽核翻譯。以下是音譯的列表: .IP 連字元 4 .IX Item "連字元" 手冊頁中的連字元 (\-) 和減號 (\e\-) 在 PO 檔案中都音譯為簡單的破折號 (\-)。然後,在將翻譯插入到輸出文件中時,所有破折號都音譯為 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 和 E (與 POD 中相同)。 .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 不翻譯 'NAME' 部分來選擇更嚴格的 mdoc 格式支援。翻譯了 'NAME' 部分的 mdoc 頁面不會生成任何頁首或頁尾。 .Sp 根據 groff_mdoc,名稱,概要和描述 章節是必填項。 翻譯的概要或描述部分沒有已知問題, 但您也可以這樣指定這些部分: \-o mdoc=NAME,SYNOPSIS,DESCRIPTION .Sp 此 mdoc 問題也可以透過如下附錄解決: PO4A\-HEADER:mode=before;position=^.Dd .TH DOCUMENT_TITLE 1 "月日,年" 作業系統 "章節名" .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 . IR \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 IR .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,或者像 SGML 這樣的 XML 家族之一),但是多虧了 po4a::man,它不再需要了。也就是說,如果您的文件的源格式是 POD 或 XML,那麼轉換源格式而不是這個生成的格式可能更聰明。在大多數情況下,po4a::man 將檢測生成的頁面併發出警告。它甚至會拒絕處理 POD 生成的頁面,因為這些頁面由 po4a::pod 完美地處理,而且它們的 nroff 對應項定義了許多我不想編寫支援的新宏。在我的機器上,4323 個頁面中的 1432 個是從 POD 生成的,將被 po4a::man 忽略。 .PP 在大多數情況下, po4a::man 會發現問題並拒絕處理頁面,發出一個適應的訊息。在一些罕見的情況下,程式將沒有警告完成,但輸出將是錯誤的。這種情況稱為 "bugs";如果遇到這種情況,請務必報告此情況,並在可能時進行修復… .SH 此模組的狀態 .IX Header "此模組的狀態" 此模組可用於大多數現有手冊頁。 .PP 一些測試定期在 Linux 機器上執行: .IP \(bu 4 三分之一的頁面被拒絕,因為它們是從 po4a 支援的另一種格式 (例如 POD 或 SGML) 生成的。 .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 \& Nicolas François \& Martin Quinson (mquinson#debian.org) .Ve .SH 版權和許可 .IX Header "版權和許可" 版權所有 © 2002\-2008 SPI, Inc. .PP This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file).