HAYASHI Kentaro
null+****@clear*****
Wed Oct 30 12:12:16 JST 2013
HAYASHI Kentaro 2013-10-30 12:12:16 +0900 (Wed, 30 Oct 2013) New Revision: 5c91bd47c29db69c1c435bea988eb70536923d3a https://github.com/groonga/groonga.org/commit/5c91bd47c29db69c1c435bea988eb70536923d3a Message: blog: add entry about "Groonga" notation Added files: ja/_posts/2013-10-30-use-capitalized-notation.textile Added: ja/_posts/2013-10-30-use-capitalized-notation.textile (+220 -0) 100644 =================================================================== --- /dev/null +++ ja/_posts/2013-10-30-use-capitalized-notation.textile 2013-10-30 12:12:16 +0900 (c77e007) @@ -0,0 +1,220 @@ +--- +layout: post.ja +title: groongaからGroongaへ - ドキュメントの表記を一緒に更新しませんか? +description: ドキュメントの表記を一緒に更新しませんか? +--- + +h2. groongaからGroongaへ - ドキュメントの表記を一緒に更新しませんか? + +リリースアナウンスや、公式ドキュメントをみてもうすでに気づいた人がいるかもしれませんが、Groonga関連のソフトウェアの表記を「Groonga」（先頭が大文字）へ統一する作業をすすめています。 + +それなりに分量があるので、ドキュメントに散らばっている「groonga」表記の統一をお手伝いしてくれる人を募集します。 +詳細は後述する「協力者募集」を参照してください。コードを書かなくてもできることです。 + +h3. 表記の統一について + +これまでは、日本語の文の中や英語の文の途中では「groonga」（先頭も小文字）という表記で、英語の文の先頭では「Groonga」（先頭が大文字）という表記を使ったりしていました。これからは、日本語のときでも「Groonga」（先頭が大文字）を使うようにします。 + +h3. 表記の統一の理由について + +先頭を大文字に統一する理由は世界中で広く使われるようにしたいからです。 + +* 英語での表記 - テキストで大文字始まりだと固有名詞として認識してもらいやすい +* 日本語での表記 - 英語との統一性を重視して大文字に揃える + +海外の人と英語でやりとりをすると、こちらは「groonga」（先頭小文字）で書いても「Groonga」（先頭大文字）で返ってくることが何度もありました。（あったと森さんから聞いています。）このことから、英語圏の人にとってはソフトウェアの名前は先頭大文字が普通なんだろうと感じるようになりました。Groonga関連の +ソフトウェアは海外でも広く使われるようにしたいので、より海外でなじみやすい表記に統一することにしました。 + +h3. ロゴへの影響について + +ロゴについては見栄えを重視しているので「groonga」（先頭も小文字）のままです。 +したがってこれまで通り変更はありません。 + +次のように、テキストとロゴで表記が違う例というのはそれなりにあるためです。 + +* "Ubuntu":http://www.ubuntu.com/ （ロゴは小文字） +* "Debian":http://www.debian.or.jp/ （ロゴは大文字） +* "Red Hat":http://jp.redhat.com/ （ロゴはスペースなしの小文字） + +h3. 協力者募集 + + +具体的にどんなことをやればいいのかを説明します。基本的にはドキュメントのソースファイルごとにごとにpull requestを送ってもらうと進めやすいです。 + +対象となるファイルはdoc/sourceディレクトリ以下の拡張子が「.txt」となっているファイルです。 + +あまりGitHubでの作業に慣れていなくてもできるように、「最初にやること」と「作業ごとにやること」、「ファイルごとにやること」に分けて順に説明します。 + +* 最初にやること +* 作業ごとにやること +* ファイルごとにやること + +h4. 最初にやること + +以下では、最初に一度だけ実施しておけば良いことを説明します。 + +h5. 最初の設定 + +まずは、gitの設定をしましょう。すでにある程度gitを使っている場合には初期設定はすでに完了しているかも知れません。その場合には飛ばして構いません。 + +<pre> +% git config --global user.name "あなたのユーザー名" +% git config --global user.email "あなたのメールアドレス" +</pre> + +上記はコミットログに使われます。公開しても差し支えないユーザ名もしくはメールアドレスを設定します。 + +h5. GitHubでforkする + +GitHubにアカウントがなければ用意してください。アカウントが用意できたら、ログインした状態で以下のURLにアクセスします。 + +* "Groongaリポジトリをforkする":https://github.com/groonga/groonga/fork + +リポジトリ選択画面でご自分のリポジトリへとforkしてください。 + +h5. 作業用リポジトリの初期設定 + +次は作業用にforkしたリポジトリを手元にcloneします。このとき、本家の変更に追従するための設定を行います。 + +<pre> +% git clone git �� github.com:(あなたのGitHubのアカウント)/groonga.git +% cd groonga +% git remote add upstream git �� github.com:groonga/groonga +</pre> + +h5. ドキュメントビルド用の初期設定 + +ドキュメントを生成するために以下を実行します。 + +<pre> +% ./autogen.sh +% ./configure --enable-document +</pre> + +ここまでで、「最初にやること」は完了です。次は「作業ごとにやること」へと進みます。 + +h4. 作業ごとにやること + +以下では作業ごとにやることを説明します。 + +h5. Groonga本家に追従する + +Groonga本家の最新状態に追従して、作業がかぶらないようにします。 + +<pre> +% git fetch --all +% git checkout master +% git rebase upstream/master +</pre> + +最新の状態に追従できたら、「ファイルごとにやること」へと進みます。 + +h4. ファイルごとにやること + +以下では、例えば http://groonga.org/docs/install/windows.html を更新する場合で説明します。作業対象となるファイルは、リポジトリのdoc/source/ディレクトリ以下にあります。 今回は、doc/source/install/windows.txtを変更する例で説明します。 + +もうすでに統一作業が完了しているファイルについてはファイルの先頭に次のマークアップがしてあります。 +実際の作業をするときには、まだそのマークアップがされていないファイルを選んでください。 + +<pre> +.. -*- rst -*- +.. Groonga Project +</pre> + +h5. 作業用のブランチを作成 + +作業対象のブランチを作成します。install/windows.txtを変更するので、 ブランチ名を @use-capitalized-notation-install-windows@ とします。 + +<pre> +% git checkout -b use-capitalized-notation-install-windows +</pre> + +h5. 編集作業 + +ドキュメントの「groonga」という表記を「Groonga」へと変更します。 + +文章だけでなく実行例も含むので単純に一括で置換するのは問題があります。 +そこで「変更する箇所」と「変更しない箇所」について説明します。 + +変更する箇所: + +* groongaという単語をGroongaに置き換える + +変更しない箇所: + +* groongaをURLの一部として使っている箇所 +* groongaをパッケージ名として使っている箇所 +* groongaをコマンド名として使っている箇所 +* groongaを実行例として使っている箇所 + * 行末が::で終わっている箇所の次のブロックは実行例となります。 + +例: + +<pre> + Start command prompt ``cmd.exe`` and download x64 zip archive by default browser:: + + > "c:\\Program Files\\Internet Explorer\\iexplore.exe" http://packages.groonga.org/windows/groonga/groonga-3.0.9-x64.zip +</pre> + +* groongaを特別な記法として扱っている箇所 + * 行の先頭が".. "となっている箇所に含まれるgroongaという単語は実行時のログを埋め込んだりするためのマークアップです。 + +例: + +<pre> +.. groonga-command +.. database: groonga-httpd +.. include:: ../../example/reference/executables/groonga-httpd.log +.. /d/status +</pre> + +h4. ドキュメントの確認 + +マークアップに問題がないか、HTMLを確認します。HTMLを生成するには以下のコマンドを実行します。 + +<pre> +% cd doc/locale/en +% make html +</pre> + +いつも使っているブラウザで該当ファイルを確認して、変更した内容が反映されていればOKです。 + +<pre> +% firefox html/install/windows.html +</pre> + + +h4. コミット + +HTMLに問題がないことを確認できたら、コミットします。 + +<pre> +% cd ${cloneしたディレクトリーのトップディレクトリー} +% git add doc/source/install/windows.txt +% git commit +</pre> + +コミットするときのメッセージについては、例えば以下のようにします。 + +<pre> +doc: use "Groonga" notation +</pre> + +h4. pushとpull request + +ご自分のリポジトリにpushして変更点をとりこめるように公開します。 + +<pre> +% git push -u origin use-capitalized-notation-install-windows +</pre> + +ここで @use-capitalized-notation-install-windows@ は前の方の作業で作ったブランチ名です。 + +"GitHub #121":https://github.com/groonga/groonga/pull/121 はpull requestのサンプルです。 + +ブラウザで https://github.com/(GitHubのアカウント)/groonga を開くと「 @use-capitalized-notation-install-windows@ 」ブランチをpull requestする！みたいなUIができているので、そこのボタンを押してpull requestしてください。入力フォームがでてきますが、コミットしたときメッセージで十分なのでそのままpull requestしてOKです！ + +これで、ひととおりの作業は完了しました。 + +まだまだできるよ!という人は 「作業ごとにやること」の「Groonga本家に追従」に戻って繰り返します。 + -------------- next part -------------- HTML����������������������������...Download