null+****@clear*****
null+****@clear*****
2011年 5月 29日 (日) 12:28:39 JST
Kouhei Sutou 2011-05-29 03:28:39 +0000 (Sun, 29 May 2011)
New Revision: c965e4794178a3a24565b8185efd9b7f445e23e4
Log:
[doc] add more information about I18N.
Added files:
doc/source/contribution/documentation/c-api.txt
doc/source/contribution/documentation/i18n.txt
Modified files:
doc/source/contribution.txt
doc/source/contribution/documentation.txt
Modified: doc/source/contribution.txt (+1 -1)
===================================================================
--- doc/source/contribution.txt 2011-05-29 01:27:45 +0000 (416383b)
+++ doc/source/contribution.txt 2011-05-29 03:28:39 +0000 (60c36e7)
@@ -14,7 +14,7 @@ Use:
Introduction:
Please talk your friends about groonga.
Bug report, development and documentation:
- We describe about them in section.
+ We describe about them in this section.
.. toctree::
:maxdepth: 3
Modified: doc/source/contribution/documentation.txt (+5 -18)
===================================================================
--- doc/source/contribution/documentation.txt 2011-05-29 01:27:45 +0000 (8d0aef6)
+++ doc/source/contribution/documentation.txt 2011-05-29 03:28:39 +0000 (9368fca)
@@ -5,25 +5,12 @@
How to contribute in documentation topics
=========================================
-I18N
-----
-
-We only had documentation in Japanese. We start to support
-I18N documentation. We'll use English as base language and
-translate English into other languages such as
-Japanese. We'll put documentations into doc/source/ and
-process them by Sphinx_.
+We use Sphinx_ for documentation tool.
.. _Sphinx: http://sphinx.pocoo.org/
-But we still use Japanese in doc/source/ for now. We need to
-translate Japanese documentation in doc/source/ into
-English. We welcome to you help us by translating
-documentation.
-
-C API
------
+.. toctree::
+ :maxdepth: 1
+ :glob:
-We still have C API documentation in include/groonga.h. But
-we want to move them into doc/source/c-api/. We welcome to
-you help us by moving C API documentation.
+ documentation/*
Added: doc/source/contribution/documentation/c-api.txt (+14 -0) 100644
===================================================================
--- /dev/null
+++ doc/source/contribution/documentation/c-api.txt 2011-05-29 03:28:39 +0000 (e2cd536)
@@ -0,0 +1,14 @@
+.. -*- rst -*-
+
+.. highlightlang:: none
+
+C API
+=====
+
+We still have C API documentation in include/groonga.h. But
+we want to move them into doc/source/c-api/*.txt. We welcome
+to you help us by moving C API documentation.
+
+We will use `the C domain markup`_ of Sphinx.
+
+.. _the C domain markup: http://sphinx.pocoo.org/latest/domains.html#the-c-domain
Added: doc/source/contribution/documentation/i18n.txt (+184 -0) 100644
===================================================================
--- /dev/null
+++ doc/source/contribution/documentation/i18n.txt 2011-05-29 03:28:39 +0000 (cef777c)
@@ -0,0 +1,184 @@
+.. -*- rst -*-
+
+.. highlightlang:: none
+
+I18N
+====
+
+We only had documentation in Japanese. We start to support
+I18N documentation by gettext based `Sphinx I18N feature`_.
+We'll use English as base language and translate
+English into other languages such as Japanese. We'll put
+all documentations into doc/source/ and process them by
+Sphinx.
+
+.. _Sphinx I18N feature: http://sphinx.pocoo.org/latest/intl.html
+
+But we still use Japanese in doc/source/ for now. We need to
+translate Japanese documentation in doc/source/ into
+English. We welcome to you help us by translating
+documentation.
+
+Translation flow
+----------------
+
+After doc/source/\*.txt are updated, we can start translation.
+
+Here is a translation flow:
+
+1. Clone groonga repository.
+2. Update .po files.
+3. Edit .po files.
+4. Generate HTML files.
+5. Confirm HTML output.
+6. Repeat 2.-4. until you get good result.
+7. Send your works to us!
+
+Here are command lines to do the above flow. Following
+sections describes details.
+
+::
+
+ # Please fork https://github.com/groonga/groonga on GitHub
+ % git clone https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga.git
+ % ./autogen.sh
+ % ./configure
+ % cd doc/locale/${LANGUAGE}/LC_MESSAGES # ${LANGUAGE} is language code such as 'ja'.
+ % make update # *.po are updated
+ % editor *.po # translate *.po # you can use your favorite editor
+ % cd ..
+ % make html
+ % browser html/index.html # confirm translation
+ % git add LC_MESSAGES/*.po
+ % git commit
+ % git push
+
+How to clone groonga repository
+-------------------------------
+
+First, please fork groonga repository easily on GiHub. You
+just access https://github.com/groonga/groonga and press
+`Fork` button. Now you can pull your groonga repository::
+
+ % git clone https://github.com/${YOUR_GITHUB_ACCOUNT}/groonga.git
+
+Then you need to configure your cloned repository::
+
+ % cd groonga
+ % ./autogen.sh
+ % ./configure
+
+The above steps are just needed at the first setup.
+
+If you have troubles on the above steps, you can use source
+files available on http://packages.groonga.org/source/groonga/ .
+
+How to update .po files
+-----------------------
+
+You can update .po files by running `make update` on
+doc/locale/${LANGUAGE}/LC_MESSAGES. (Please substitute
+`${LANGUAGE}` with your language code such as 'ja'.)::
+
+ % cd doc/locale/ja/LC_MESSAGES
+ % make update
+
+How to edit .po
+---------------
+
+There are some tools to edit .po files. .po files are just
+text. So you can use your favorite editor. Here is a
+specialized editor for .po file edit list.
+
+Emacs's po-mode_
+ It is bundled in gettext.
+
+Poedit_
+ It is a .po editor and works on many platform.
+
+gted
+ It is also a .po editor and is implemented as Eclipse plugin.
+
+.. _po-mode: http://www.gnu.org/s/hello/manual/gettext/PO-Mode.html
+.. _Poedit: http://www.poedit.net/
+.. _gted: http://www.gted.org/
+
+How to generate HTML files
+--------------------------
+
+You can generate HTML files with updated .po files by
+running `make html` on doc/locale/${LANGUAGE}. (Please
+substitute `${LANGUAGE}` with your language code such as
+'ja'.)::
+
+ % cd doc/locale/ja/
+ % make update
+
+.. note::
+
+ .mo files are updated automatically by `make update`. So
+ you don't care about .mo files.
+
+How to confirm HTML output
+--------------------------
+
+HTML files are generated in
+doc/locale/${LANGUAGE}/html/. (Please substitute
+`${LANGUAGE}` with your language code such as 'ja'.) You can
+confirm HTML output by your favorite editor::
+
+ % firefox doc/locale/ja/html/index.html
+
+How to send your works
+----------------------
+
+We can receive your works via pull request on GitHub or
+E-mail attachment patch or .po files themselves.
+
+How to send pull request
+++++++++++++++++++++++++
+
+Here are command lines to send pull request::
+
+ % git add doc/locale/ja/LC_MESSAGES/*.po
+ % git commit
+ % git push
+
+Now you can send pull request on GitHub. You just access
+your repository page on GitHub and press `Pull Request`
+button.
+
+.. seealso:: `Help.GitHub - Sending pull requests`_.
+
+.. _Help.GitHub - Sending pull requests: http://help.github.com/pull-requests/
+
+How to send patch
++++++++++++++++++
+
+Here are command lines to create patch::
+
+ % git add doc/locale/ja/LC_MESSAGES/*.po
+ % git commit
+ % git format-patch origin/master
+
+You can find 000X-YYY.patch files in the current
+directory. Please send those files to us!
+
+How to send .po files
++++++++++++++++++++++
+
+Please archive doc/locale/${LANGUAGE}/LC_MESSAGES/ (Please
+substitute `${LANGUAGE}` with your language code such as
+'ja'.) and send it to us! We extract and merge them to the
+groonga repository.
+
+How to add new language
+-----------------------
+
+Here are command lines to add new translation language::
+
+ % cd doc/locale
+ % make add LOCALE=${LANGUAGE} # specify your language code such as 'de'.
+
+Please substitute `${LANGUAGE}` with your language code such
+as 'ja'.