248
說明:
|
10080
|
這個顏色代表刪除的 | 這個顏色代表增加的 |
行號 1: | 行號 1: |
pydoccht 計畫將 Python 2.6 以後的 Python official documentation 譯為台灣繁體中文。請參見 pydoccht 的 [http://project.python.org.tw/pydoccht/ issue tracker] 與 [http://hg.seety.org/translating/pydoccht/ mercurial repository]。 | #FORMAT rst =================== Python 文件中譯計畫 =================== .. contents:: 簡介 ==== 緣起 ++++ Python 是方便強大的動態語言,在西方世界有許多的使用者。然而,在台灣一直沒有突破性的發展。身處軟體工業並不發達的國家,Python 無法在台灣流行有許多原因,但缺乏適當的中文文件,確是理由之一。 為此,\ PyTUG_ 決定開始 Python 文件的繁體中譯計畫,將最新的 Python 官方文件譯為符合本地用語的繁體中文版。本中譯計畫暫定名為 pydoccht。 .. _PyTUG: http://wiki.python.org.tw/ 目標 ++++ 完整翻譯 Python official documentation 至繁體中文,並持續自上游更新。 信條 ++++ 必求正確,力求精準。 成果授權 ++++++++ 因 pydoccht 為文件翻譯計畫,故完全遵照原始文件之授權。 如何開始 ======== 取得貯庫資料 ++++++++++++ 如果你只想檢視 pydoccht 目前的工作成果,請先安裝 Mercurial_\ 。安裝好了之後,請在你要存放 pydoccht 的目錄內執行: :: hg clone http://hg.python.org.tw/pydoccht/ .. _Mercurial: http://www.selenic.com/mercurial/wiki/ 便會把最新的 pydoccht 工作成果 clone 到你的電腦中。 取得 push 權力 ++++++++++++++ 如果你想要協助翻譯,有兩個條件: 1. 對 Python 有\ **愛**\ , 2. 先把 pydoccht 的貯庫 clone 下來看看。 這樣的條件很容易符合,歡迎加入!現在你需要取得該貯庫的 push 權限。請向 coordinator (yungyuc_) 申請,聯絡方法有二: * (**這是比較建議的方式**) 到 pydoccht roundup (http://project.python.org.tw/pydoccht/) 給 coordinator 送一個 ticket。 * 用 im、email、irc 等各種方法找到 coordinator。 為了處理你的申請,需要以下資料: 1. 指定你能夠扮演的工作角色 (見後文)。 2. 說明你的聯絡方式;如果你註冊 roundup 的 email 是主要聯絡方式,那麼不附也可以,但請確定要能收得到 roundup 系統寄發的信 (最近系統寄出的信常被當成 spam)。 3. 指定你想要用的帳號密碼。這很簡單,請提供 ``htpasswd -n YOUR_USER_NAME`` 輸出的結果 (僅一行) 即可。 coordinator 會和你討論,並把你的資料交給 MIS 建入 pydoccht 的貯庫。\ **注意**\ ,密碼一類的敏感資訊請私下 email,不要放在 roundup 上。 如何 push +++++++++ push 前請先對你 clone 的 pydoccht 貯庫進行設定 (以下的 ``$REPO`` 表示 pydoccht 貯庫的路徑): 1. 在 ``$REPO/.hg/hgrc`` 內設定上傳時的個人資訊,如: :: [ui] username = "王大明 <wangdaming@a.b.c>" 注意,這個 username **並不必要是**\ 你申請時的帳號名稱。你可以用更易識別的名稱,而通常我們都會如上例後綴 email。 2. 並在該檔內設定預設的上傳路徑: :: [paths] default = http://YOUR_USER_NAME@hg.python.org.tw/pydoccht/ default-push = http://YOUR_USER_NAME@hg.python.org.tw/pydoccht/ 設定完畢後即可直接以 ``hg push`` 開始上傳。 技術需求 ++++++++ pydoccht 的進行需要一些技術基礎,茲列出如下。 1. mercurial pydoccht 的 VCS 使用 mercurial,canonical repository 為 http://hg.python.org.tw/pydoccht/\ ;關於如何操作系統,請參考 hgbook_\ 。 此系統的建置與維護由 MIS 負責。 .. _hgbook: http://hgbook.red-bean.com/hgbook.html 2. roundup 本計畫利用 roundup issue tracker 紀錄與分派工作,進行團隊合作;此 roundup 系統位於 http://project.python.org.tw/pydoccht/\ 。同時也以 roundup 進行工作討論。 此系統的建置與維護由 MIS 負責。 3. docutils/rst and sphinx 新版 Python official document (以下稱 pydoc) 在 Python 2.6 trunk 中已捨 LaTeX 改採 reStructuredText_\ 。事實上,這是 yungyuc_ 決定發起 pydoccht 計畫的主因;相較於 LaTeX,reStructuredText 對中文非常友善,pydoc 所使用的文件工具將可能可以直接套用在 pydoccht 上。 sphinx_ 是新版 pydoc 所使用的文件產生框架。 .. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html .. _yungyuc: http://blog.seety.org/everydaywork/ .. _sphinx: http://svn.python.org/projects/doctools/trunk/ 4. make pydoc 使用 make 作為 build tool,故需熟悉 Makefile 與 make。 5. subversion Python trunk 使用 subversion,故為了自 trunk checkout 最新的 pydoc 與相關工具,我們也要使用 subversion。 此外 pydoccht 將會以 http://groups.google.com/group/pythontw 作為正式的消息發佈管道;希望所有參與者注意其中的訊息。同時鼓勵團隊成員使用 #python.tw/Freenode 頻道即時討論。 時程規畫 ======== pydoccht 開始於 2007/Nov。初步預期於兩年內,即 2009 時完成所有文件的中譯。 初期先從 tutorial 開始翻譯,視情況漸次進行其它部分。 建構 ==== clone 完成後,進入 ``chtdoc`` 目錄,執行 ``make html``\ 。Python doc framework 會自動建構 HTML 版的文件。另外,也可以用 ``make web`` 和 ``make htmlhelp`` 建構不同版本的文件成品。建好的文件將置於 ``build`` 目錄下。 編輯手冊 ======== 未來在本計畫漸次執行之後,本節將會獨立寫成 pydoccht 的\ **編輯手冊**\ 。 pydoc 簡述 ++++++++++ pydoc 是本計畫的上游,翻譯的目標。主要分為數部文件: * What's New:「更新說明」,位於 ``whatsnew`` 目錄。 * Tutorial:「Python 入門手冊」,位於 ``tutorial`` 目錄。 * Using Python:「使用 Python」,位於 ``using`` 目錄。 * Language Reference:「Python 語言參考手冊」,位於 ``reference`` 目錄。 * Library Reference:「Python 程式庫參考手冊」,位於 ``library`` 目錄。 * Python HOWTOs:「Python HOWTOs」,位於 ``howto`` 目錄。 * Extending and Embedding:「延伸與嵌入 Python 直譯器」,位於 ``extending`` 目錄。 * Python/C API:「Python/C API 參考手冊」,位於 ``c-api`` 目錄。 * Installing Python Modules:「安裝 Python 模組」,位於 ``installing`` 目錄。 * Distributing Python Modules:「散佈 Python 模組」,位於 ``distutils`` 目錄。 * Documenting Python:「Python 文件」,位於 ``documenting`` 目錄。 分工 ++++ 以下為 pydoccht 計畫的分工。\ **注意**\ ,一人兼多角是常態: * 資訊系統管理 (MIS):現由 mat_ 負責 pydoccht 的資訊系統,主要為 roundup。 * 協調員 (coordinator):最初的 coordinator 為計畫的發起人 yungyuc_\ ,目前仍為 yungyuc。 * 譯者 (translator):負責翻譯,以章為單位。因 pydoc 基本上一章一檔,故每位譯者負責一個檔案。 譯者應以註解的方式署名於文稿內,並照英文姓名或代號順序,列於文件的譯者欄。 若某譯者未譯完負責章節,在其表達無力完成或擱置逾時並未予處理,而由另名譯者接手完成該章,則前者不可列名,惟後者列名;finisher takes all。 * 校對者 (reviser):負責校稿,主要負責比較中文與原文,糾正譯稿中的錯誤。校對者也要負責維護詞彙的一致性。 校對者也應列名,但不署名於文稿內,而列於獨立的說明文字中。出現順序依照英文姓名或代號。 * 潤飾者 (polisher):也屬於校稿工作的一環,但主要負責修正中文譯稿文意不通之處,不需注重原文。潤飾者也要負責維護詞彙的一致性。 潤飾者的 credit 與校對者同。 * 編輯 (editor):負責總成每部 (volume) 文件的翻譯成果,包含文件的發佈。 .. _mat: http://del.icio.us/MatLinuxer2/ 細分工作種類,是為了讓更多同好可以參與 pydoccht 計畫;各人興趣不同,能力各異,可以選擇適合的工作進行。然而 pydoccht 也不可能有太多人手,並且大家都是利用閒暇時間來執行計畫,故身兼數角應是常態。 欲加入 pydoccht 的同好,請明白指出你想要幫忙的角色。目前的分工表紀錄在 http://wiki.python.org.tw/PythonProjects/pydoccht/JobTable\ 。 執行模式 ++++++++ 如同專業的翻譯工作,pydoccht 採用翻譯、校對、出版的執行模式。 pydoccht 雖是一個專案,但翻譯的對象 pydoc 本身是好幾部文件的集合。因此,翻譯工作會以一部完整的文件 (如 tutorial 即為一例) 為單位,分章翻譯、分章校對。 與台灣的專業電腦書籍翻譯不同的地方是: 1. 為了品質,我們真的要作\ **校對**\ 。 2. 因應上游的更新,我們要有一套修訂作業流程。 3. 我們主要作網路出版,最多作到 PDF 出版,基本上不付印。 翻譯規則 ++++++++ 所有的翻譯工作將在 ``chtdoc`` 下進行。目前 pydoccht 針對 trunk rev 58893 進行翻譯,原稿均置於 origdoc_r58893,而 chtdoc 是 ``hg cp origdoc_r58893 chtdoc`` 的結果。 Python 將會持續更新其文件。未來,在適當的時間點,新的文件會被拉進 pydoccht 貯庫,我們可以參考新 origdoc 與舊 origdoc 間的 diff,來對 chtdoc 進行修改。為了修改的效率,可能需要設計一些指令稿來輔助。 .. note:: 在 commit 稿件的時候,請使用\ **英文**\ 撰寫 log 訊息。 根目錄下的檔案說明 ================== * chtdoc: 繁體中文譯稿。未譯的部分是 origdoc_rREV 的複製檔。 * origdoc_rREV: revision 為 REV 的上游原文。 * clone.py: 協助取得上游文件與製作譯稿結構的指令稿。 * CONVENTION.rst: 翻譯文稿的慣例。 * README.rst: 本說明檔。 * REPOSITORY.rst: pydoccht 貯庫說明。 * glossary.rst: 詞彙表。 .. vim: ff=unix: |
Python 文件中譯計畫
簡介
緣起
Python 是方便強大的動態語言,在西方世界有許多的使用者。然而,在台灣一直沒有突破性的發展。身處軟體工業並不發達的國家,Python 無法在台灣流行有許多原因,但缺乏適當的中文文件,確是理由之一。
為此,PyTUG 決定開始 Python 文件的繁體中譯計畫,將最新的 Python 官方文件譯為符合本地用語的繁體中文版。本中譯計畫暫定名為 pydoccht。
目標
完整翻譯 Python official documentation 至繁體中文,並持續自上游更新。
信條
必求正確,力求精準。
成果授權
因 pydoccht 為文件翻譯計畫,故完全遵照原始文件之授權。
如何開始
取得貯庫資料
如果你只想檢視 pydoccht 目前的工作成果,請先安裝 Mercurial。安裝好了之後,請在你要存放 pydoccht 的目錄內執行:
hg clone http://hg.python.org.tw/pydoccht/
便會把最新的 pydoccht 工作成果 clone 到你的電腦中。
取得 push 權力
如果你想要協助翻譯,有兩個條件:
- 對 Python 有愛,
- 先把 pydoccht 的貯庫 clone 下來看看。
這樣的條件很容易符合,歡迎加入!現在你需要取得該貯庫的 push 權限。請向 coordinator (yungyuc) 申請,聯絡方法有二:
- (這是比較建議的方式) 到 pydoccht roundup (http://project.python.org.tw/pydoccht/) 給 coordinator 送一個 ticket。
- 用 im、email、irc 等各種方法找到 coordinator。
為了處理你的申請,需要以下資料:
- 指定你能夠扮演的工作角色 (見後文)。
- 說明你的聯絡方式;如果你註冊 roundup 的 email 是主要聯絡方式,那麼不附也可以,但請確定要能收得到 roundup 系統寄發的信 (最近系統寄出的信常被當成 spam)。
- 指定你想要用的帳號密碼。這很簡單,請提供 htpasswd -n YOUR_USER_NAME 輸出的結果 (僅一行) 即可。
coordinator 會和你討論,並把你的資料交給 MIS 建入 pydoccht 的貯庫。注意,密碼一類的敏感資訊請私下 email,不要放在 roundup 上。
如何 push
push 前請先對你 clone 的 pydoccht 貯庫進行設定 (以下的 $REPO 表示 pydoccht 貯庫的路徑):
在 $REPO/.hg/hgrc 內設定上傳時的個人資訊,如:
[ui] username = "王大明 <wangdaming@a.b.c>"
注意,這個 username 並不必要是你申請時的帳號名稱。你可以用更易識別的名稱,而通常我們都會如上例後綴 email。
並在該檔內設定預設的上傳路徑:
[paths] default = http://YOUR_USER_NAME@hg.python.org.tw/pydoccht/ default-push = http://YOUR_USER_NAME@hg.python.org.tw/pydoccht/
設定完畢後即可直接以 hg push 開始上傳。
技術需求
pydoccht 的進行需要一些技術基礎,茲列出如下。
mercurial
pydoccht 的 VCS 使用 mercurial,canonical repository 為 http://hg.python.org.tw/pydoccht/;關於如何操作系統,請參考 hgbook。
此系統的建置與維護由 MIS 負責。
roundup
本計畫利用 roundup issue tracker 紀錄與分派工作,進行團隊合作;此 roundup 系統位於 http://project.python.org.tw/pydoccht/。同時也以 roundup 進行工作討論。
此系統的建置與維護由 MIS 負責。
docutils/rst and sphinx
新版 Python official document (以下稱 pydoc) 在 Python 2.6 trunk 中已捨 LaTeX 改採 reStructuredText。事實上,這是 yungyuc 決定發起 pydoccht 計畫的主因;相較於 LaTeX,reStructuredText 對中文非常友善,pydoc 所使用的文件工具將可能可以直接套用在 pydoccht 上。
sphinx 是新版 pydoc 所使用的文件產生框架。
make
pydoc 使用 make 作為 build tool,故需熟悉 Makefile 與 make。
subversion
Python trunk 使用 subversion,故為了自 trunk checkout 最新的 pydoc 與相關工具,我們也要使用 subversion。
此外 pydoccht 將會以 http://groups.google.com/group/pythontw 作為正式的消息發佈管道;希望所有參與者注意其中的訊息。同時鼓勵團隊成員使用 #python.tw/Freenode 頻道即時討論。
建構
clone 完成後,進入 chtdoc 目錄,執行 make html。Python doc framework 會自動建構 HTML 版的文件。另外,也可以用 make web 和 make htmlhelp 建構不同版本的文件成品。建好的文件將置於 build 目錄下。
編輯手冊
未來在本計畫漸次執行之後,本節將會獨立寫成 pydoccht 的編輯手冊。
pydoc 簡述
pydoc 是本計畫的上游,翻譯的目標。主要分為數部文件:
- What's New:「更新說明」,位於 whatsnew 目錄。
- Tutorial:「Python 入門手冊」,位於 tutorial 目錄。
- Using Python:「使用 Python」,位於 using 目錄。
- Language Reference:「Python 語言參考手冊」,位於 reference 目錄。
- Library Reference:「Python 程式庫參考手冊」,位於 library 目錄。
- Python HOWTOs:「Python HOWTOs」,位於 howto 目錄。
- Extending and Embedding:「延伸與嵌入 Python 直譯器」,位於 extending 目錄。
- Python/C API:「Python/C API 參考手冊」,位於 c-api 目錄。
- Installing Python Modules:「安裝 Python 模組」,位於 installing 目錄。
- Distributing Python Modules:「散佈 Python 模組」,位於 distutils 目錄。
- Documenting Python:「Python 文件」,位於 documenting 目錄。
分工
以下為 pydoccht 計畫的分工。注意,一人兼多角是常態:
資訊系統管理 (MIS):現由 mat 負責 pydoccht 的資訊系統,主要為 roundup。
協調員 (coordinator):最初的 coordinator 為計畫的發起人 yungyuc,目前仍為 yungyuc。
譯者 (translator):負責翻譯,以章為單位。因 pydoc 基本上一章一檔,故每位譯者負責一個檔案。
譯者應以註解的方式署名於文稿內,並照英文姓名或代號順序,列於文件的譯者欄。
若某譯者未譯完負責章節,在其表達無力完成或擱置逾時並未予處理,而由另名譯者接手完成該章,則前者不可列名,惟後者列名;finisher takes all。
校對者 (reviser):負責校稿,主要負責比較中文與原文,糾正譯稿中的錯誤。校對者也要負責維護詞彙的一致性。
校對者也應列名,但不署名於文稿內,而列於獨立的說明文字中。出現順序依照英文姓名或代號。
潤飾者 (polisher):也屬於校稿工作的一環,但主要負責修正中文譯稿文意不通之處,不需注重原文。潤飾者也要負責維護詞彙的一致性。
潤飾者的 credit 與校對者同。
編輯 (editor):負責總成每部 (volume) 文件的翻譯成果,包含文件的發佈。
細分工作種類,是為了讓更多同好可以參與 pydoccht 計畫;各人興趣不同,能力各異,可以選擇適合的工作進行。然而 pydoccht 也不可能有太多人手,並且大家都是利用閒暇時間來執行計畫,故身兼數角應是常態。
欲加入 pydoccht 的同好,請明白指出你想要幫忙的角色。目前的分工表紀錄在 http://wiki.python.org.tw/PythonProjects/pydoccht/JobTable。
執行模式
如同專業的翻譯工作,pydoccht 採用翻譯、校對、出版的執行模式。
pydoccht 雖是一個專案,但翻譯的對象 pydoc 本身是好幾部文件的集合。因此,翻譯工作會以一部完整的文件 (如 tutorial 即為一例) 為單位,分章翻譯、分章校對。
與台灣的專業電腦書籍翻譯不同的地方是:
- 為了品質,我們真的要作校對。
- 因應上游的更新,我們要有一套修訂作業流程。
- 我們主要作網路出版,最多作到 PDF 出版,基本上不付印。
翻譯規則
所有的翻譯工作將在 chtdoc 下進行。目前 pydoccht 針對 trunk rev 58893 進行翻譯,原稿均置於 origdoc_r58893,而 chtdoc 是 hg cp origdoc_r58893 chtdoc 的結果。
Python 將會持續更新其文件。未來,在適當的時間點,新的文件會被拉進 pydoccht 貯庫,我們可以參考新 origdoc 與舊 origdoc 間的 diff,來對 chtdoc 進行修改。為了修改的效率,可能需要設計一些指令稿來輔助。
Note
在 commit 稿件的時候,請使用英文撰寫 log 訊息。
根目錄下的檔案說明
- chtdoc: 繁體中文譯稿。未譯的部分是 origdoc_rREV 的複製檔。
- origdoc_rREV: revision 為 REV 的上游原文。
- clone.py: 協助取得上游文件與製作譯稿結構的指令稿。
- CONVENTION.rst: 翻譯文稿的慣例。
- README.rst: 本說明檔。
- REPOSITORY.rst: pydoccht 貯庫說明。
- glossary.rst: 詞彙表。