#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_) 寄封 email。

為了處理你的申請，需要以下資料：

1. 指定你想要扮演的分工角色 (請先參閱本計畫的編輯手冊，即 HANDBOOK.rst)。

2. 說明你的聯絡方式；如果你註冊 roundup 的 email 是主要聯絡方式，那麼不附也可以，但請確定要能收得到 roundup 系統寄發的信 (最近系統寄出的信常被當成 spam)。

3. 指定你想要用的帳號密碼。這很簡單，請提供 ``htpasswd -n YOUR_USER_NAME`` 輸出的結果 (僅一行) 即可。

帳號開好了，你會知道 :)

如何 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`` 目錄下。

根目錄下的檔案說明
==================

* chtdoc: 繁體中文譯稿。未譯的部分是 origdoc_rREV 的複製檔。

* origdoc_rREV: revision 為 REV 的上游原文。

* clone.py: 協助取得上游文件與製作譯稿結構的指令稿。

* HANDBOOK.rst: 編輯手冊，包含翻譯執行方式與各種慣例。
 
* README.rst: 本說明檔。

* glossary.rst: 詞彙表。

.. vim: ff=unix: