名稱

       Locale::Po4a::TeX - 將 TeX 文件和衍生品從/轉換為 PO 檔案

描述

       Po4a (PO For Anything) 專案的目標是在文件等不需要翻譯的領域使用 gettext 工具簡化翻譯(更有
       趣的是，簡化翻譯的維護)。

       Locale::Po4a::TeX 是一個幫助將 TeX 文件翻譯成其他 [人類] 語言的模組。它還可以用作構建基於
       TeX 文件的模組的基礎。

       使用者可能應該使用 LaTeX 模組，它繼承自 TeX 模組幷包含常見 LaTeX 命令的定義。

使用 PO4A::TEX 進行翻譯

       此模組可直接用於處理通用 TeX 文件。這將把您的文件拆分成更小的塊 (段落、逐字塊，甚至更小的
       塊，如標題或索引)。

       有一些選項(將在下一節中介紹)可以自定義此行為。如果這不適合您的文件格式，我們鼓勵您編寫自己
       的派生模組，以描述您的格式的詳細資訊。有關流程描述，請參閱下面的 WRITING DERIVATIVE
       MODULES 小節。

       該模組還可以透過 TeX 檔案中以 "% po4a:" 開頭的行進行定製。此過程在 INLINE CUSTOMIZATION 一
       節中介紹。

此模組接受的選項

       以下是此模組的特定選項：

       debug
           啟用此模組某些內部機制的除錯。 使用源檢視哪些部件可以除錯。

       no_wrap
           不應重新封裝的環境的逗號分隔列表。

           請注意，逐字和 no_wrap 環境之間存在差異。在逐字逐句的塊中沒有命令和註釋分析。

           如果此環境尚未註冊，則 po4a 將考慮此環境不會接受任何引數。

       exclude_include
           不應由 \input 和 \include 包含的檔案的冒號分隔列表。

       definitions
           包含 po4a 定義的檔案的名稱，如 INLINE CUSTOMIZATION 部分中定義。 如果無法將定義放在要
           翻譯的文件中，可以使用此選項。

       verbatim
           應逐字處理的環境的逗號分隔列表。

           如果此環境尚未註冊，則 po4a 將考慮此環境不會接受任何引數。

       使用這些選項可以替代已定義命令的預設行為。

線上定製

       TeX 模組可以使用以 % po4a: 開頭的行進行自定義。這些行被解釋為解析器的命令。可以識別以下命
       令：

       % po4a: command command1 alias command2
           指示 command1 命令的引數應作為 command2 命令的引數處理。

       % po4a: command command1 parameters
           這詳細描述了 command1 命令的引數。此資訊將用於檢查引數的數量及其型別。

           您可以在 command1 之前加上

           一個星號 (*)
               po4a 將從段落中提取此命令 (如果它位於段落的開頭或結尾)。然後，翻譯者必須翻譯標記為
               可翻譯的引數。

           一個加號 (+)
               對於星號，如果它出現在塊的末端，命令將被提取，但引數不會單獨轉換。翻譯器將不得不翻
               譯連線到其所有引數的命令。這保留了更多的上下文，並且對於引數中包含較小單詞的命令非
               常有用，這些命令可以有多種含義(和翻譯)。

               注意：在這種情況下，您不必指定哪些引數是可翻譯的，但 po4a 必須知道引數的型別和數
               量。

           一個減號 (-)
               在這種情況下，不會從任何塊中提取命令。但是如果它單獨出現在塊上，那麼只有標記為可翻
               譯的引數才會顯示給翻譯器。這對於字型命令很有用。這些命令通常不應該與它們的段落分
               開(以保持上下文)，但是如果整個字串都包含在這樣的命令中，就沒有理由用它們來煩擾翻譯
               人員。

           引數是一組 [] (表示可選的。 引數) 或 {} (指示強制引數)。 您可以在這些方括號之間加一個
           下劃線 (_) 來表示。 必須翻譯該引數。例如：
            % po4a: command *chapter [_]{_}

           這表明章節命令有兩個引數：可選的。 (簡稱) 和強制性的，都必須翻譯。 如果要指定 href 命
           令有兩個必需引數， 您不想轉換 URL (第一個引數)，並且您。 我不希望此命令與其段落 (允
           許。 翻譯器移動句子中的連結)，您可以使用：
            % po4a: command -href {}{_}

           在這種情況下，僅當段落僅由此 href 命令組成時，才使用指示必須翻譯哪些引數的信息。

       % po4a: environment env parameters
           這允許定義 env 環境接受的引數。 此資訊稍後將用於檢查。 \begin 命令，並允許指定必須翻譯
           哪一個。 Parameters 引數的語法與。 其他命令。 \begin 命令的第一個引數是環境的名稱。 不
           能在引數列表中指定此引數。以下是。 下面是一些示例：
            % po4a: 環境多層 {}
            % po4a: 環境方程

           至於命令，i<env> 前面可以有一個加號 (+)，表示 \begin 命令必須使用其所有引數進行轉換。

       % po4a: separator env "regex"
           指示應根據給定正則表示式拆分環境。

           正則表示式由引號分隔。它不應該建立任何反向引用。如果需要組，應使用 (?:)。它可能還需要
           一些逃脫。

           例如，LaTeX 模組使用 "(?:&|\\\\)" 正則表示式分別翻譯表的每個單元格(行用 '\\' 分隔，單
           元格用 '&' 分隔)。

           環境的概念擴充套件為 PO 檔案中顯示的型別。這可用於拆分 title 命令的第一個強制引數中的
           "\\\\"。在本例中，環境是 title{#1}。

       % po4a: verbatim environment env
           指示 env 是一個逐字環境。在此環境中將忽略註釋和命令。

           如果此環境尚未註冊，則 po4a 將考慮此環境不會接受任何引數。

編寫衍生模組

       pre_trans
       post_trans
       add_comment
           新增字串作為要在下一個翻譯元素周圍新增的註釋。 這對於 texinfo 模組非常有用，因為註釋在
           TeX 中自動處理。

       translate
           封裝在轉換器的翻譯上，帶有前後處理過濾器。

           段落註釋作為此段落第一個翻譯字串的 PO 註釋插入。

       get_leading_command($buffer)
           此函式返回：

           命令名稱
               如果在給定緩衝區的開頭未找到命令，則此字串將為空。只考慮可以分隔的命
               令。%separated_command 雜湊包含這些命令的列表。

           變種
               這表明是否使用了變數。例如，可以在 sections 命令的末尾新增星號(*)，以指定不應對其
               進行編號。在本例中，此欄位將包含 "*"。如果沒有變數，則該欄位為空字元串。

           元組陣列（引數型別、引數）
               引數型別可以是 '{' (對於強制引數) 或 '[' (對於可選引數)。

           剩餘的緩衝區
               刪除此前導命令及其引數後緩衝區的其餘部分。如果未找到命令，則不會觸及原始緩衝區，並
               在此欄位中返回。

       get_trailing_command($buffer)
           與 get_leading_command 相同，但適用於緩衝區末尾的命令。

       translate_buffer
           透過將前導命令和尾隨命令(應該分別轉換的命令)從緩衝區中分離出來，遞迴地轉換緩衝區。

           如果在 %translate_buffer_env 中為當前環境定義了函式，則此函式將用於轉換緩衝區，而不是
           translate_buffer()。

       read
           過載翻譯器的 read()。

       read_file
           遞迴讀取檔案，追加 @exclude_include 陣列中未列出的包含檔案。包含的檔案是使用 KpathSea
           庫中的 kpseWhich 命令進行搜尋的。

           除了檔案包含部分，它是從翻譯提取器的讀取中剪下並貼上的。

       parse_definition_file
           用於使用 po4a 指令解析檔案的子例程 (新命令的定義)。

       parse_definition_line
           解析格式為 "% po4a: " 的定義行。

           有關更多詳細資訊，請參閱 INLINE CUSTOMIZATION 部分。

       is_closed
       parse
       docheader

用於編寫派生解析器的內部函式

       命令和環境函式接受以下引數(除了 $self 物件之外)：

       命令名稱
       變種
       (型別、引數)元組的陣列
       當前環境

       前 3 個引數由 get_leading_command 或 get_trailing_command 提取。

       命令和環境函式返回命令及其引數和新環境的轉換。

       當找到 \begin 命令時，將呼叫環境函式。它們由 \begin 命令及其引數呼叫。

       TeX 模組只提出一個命令函式和一個環境函式：generic_command 和 generic_environment。

       generic_command 使用由指定的資訊。 register_generic_command 或透過將定義新增到 TeX 檔案：
        % po4a: command command1 parameters

       generic_environment 使用 register_generic_environment 或透過向 TeX 檔案新增定義：
        % po4a: environment env parameters

       這兩個函式將僅轉換指定為可翻譯的引數(帶 '_')。generic_environment 將把環境的名稱附加到環境
       堆疊中，而 generic_command 將在命令的名稱後面加上引數的識別符號(如 {#7} 或 [#2])。

此模組的狀態

       此模組需要更多測試。

       它在一本書上進行了測試，並使用 Python 文件進行了測試。

待辦事項清單使用PO4A：：XML進行轉換

       自動檢測新命令
           Tex 模組可以解析 newcommand 引數，並嘗試猜測引數的數量、它們的型別以及是否應該轉換它
           們。

       環境分隔符的翻譯
           當 \item 用作環境分隔符時，item 引數附加到以下字串。

       應將某些命令新增到環境堆疊
           These commands should be specified by couples.  This can be used to specify commands
           beginning or ending a verbatim environment.

       其它
           各種其他點在原始碼中都標記為 TODO。

已知缺陷

       原始碼中的各個點都被標記為 FIXME。

參見

       Locale::Po4a::LaTeX(3pm), Locale::Po4a::TransTractor(3pm), po4a(7)

作者

        Nicolas François <nicolas.francois@centraliens.net>

版權和許可

       版權所有 © 2004, 2005 Nicolas FRANÇOIS <nicolas.francois@centraliens.net>.

       此程式是自由軟體；您可以根據 GPL 條款重新分發和/或修改它(請參閱複製檔案)。