Wiki Editing Hints/ja

From Qt Wiki
Jump to navigation Jump to search

日本語 English Français Deutsch Polski Português Русский Italian Magyar Spanish 한국어 عربي [toc align_right="yes" depth="3"]

wiki の使い方

はじめに

  1. Qt に関する何らかのノウハウをお持ちならば、この wiki で共有しましょう。 ただし、Qt に関連した話題に限ります
  2. 作成しようとしているページが、既存のページと重複しないように注意してください。 wiki box の右上にある検索フィールドを活用してください。
  3. 既にそのトピックのページが作成されていれば、検索結果で見つけられるでしょう。
  4. ほとんどのページで、全ての内容が編集できます。(WikiSyntax のページが書式を知る助けとなります)
  5. 該当するページが見つからない場合、"Create new page" をクリックして作成できます。
  6. スペースやアンダーバーを記事とカテゴリの 双方 に使用してください。 — forum poll の投票機能を利用した "フォーラムの関連スレッド":http://developer.qt.nokia.com/forums/viewthread/2262/ を参照してください。
  7. wiki の記述をテストするために既存のページを使って履歴を汚さないでください。 Playground を使ってテストしてください。

ページの編集方法

エディタはキッチンシンクのようにほとんどの一般的な機能を提供しています。それらの機能を使えば編集は難しくないはずです。

wiki のコードを直接書く方が好みであれば、"this cheat sheet":http://warpedvisions.org/projects/textile-cheat-sheet/ を参照して、 "Textism.com":http://textism.com/tools/textile/ でスキルを磨いてください。そこでは Textile(この wiki で使用しているマークアップ言語) を HTML でプレビューできます。

編集した結果の確認には Preview 機能を使用して、120% 確実にミスが 絶対に 無いと確信できるまでは保存(Submit)しないでください。

C++ のコードはこの wiki のページでは自動的にハイライトされます!

ページを使いやすくするために

他の開発者があなたが共有したい素晴らしい洞察を見つけられるように、以下の簡単なガイドラインに従ってください。

コードのように記述してください

よい wiki は良いコードに似ています。簡単に調べられ、メンテナンスできます。各記事は(クラスのように)一つのトピックだけを扱ってください。各段落は(関数のように)そのトピックの一つの局面に寄与すべきです。そうしておけば、考えが変わった場合でも段落の変更だけで済みます。見つけにくい場所に素晴らしい知見を埋め込まずに済みます。

ヘッダを使って一覧性を高める

わかりやすいヘッダを付けておけば長い記事でも読みやすくなります。h1 レベルを導入に、h2 と h3 を記載内容の概略を示すのに使用してください。(エディタにはそのためのボタンがあります。) ヘッダを記述して、記事の概略を説明してください。

目次を追加してください

読者が記事を見つけたとき、その記事が探している記事なのかどうかを判断するために最初のページを確認するでしょう。もし記事が1ページに収まる程度の長さであれば、あまり気にせずにそのまま記事を書いてください。それよりも長めの記事を書くのであれば、目次で読者に記事の内容を示してください。最初の段落と目次で、読者にこの記事を読むべきか他の記事を読むべきかを判断させるべきです。

目次を追加するためには、このタグ "["toc align_right="yes" depth="3"] を記述してください(最初の括弧の周りのダブルクォーテーション「”」は消してください)。wiki のエンジンが目次を生成してくれます。タグはどこに書いてもかまいませんが、メンテナンス性を高めるためには記事の最初にある方がいいでしょう。

カテゴリーの追加

カテゴリータグを記事に挿入して、適切なサマリーページへリンクしてください。既存のカテゴリーに記事を追加することで、読者が記事を見つけやすくなります。

新しいカテゴリーとサマリーページを作成したい場合、まだ存在しないそのカテゴリーへのタグを記事に追加してください。*(注意: スペルを間違えると予期せず新しいカテゴリーを作成することになります!)*

よく使われるカテゴリータグはこちらです:

現在、アップデート中です。- Kevin

ページの翻訳方法

wiki のページを翻訳した後は、そのページが既存の他の言語のページからアクセスできるようにすることを覚えておいてください。記事の最初にそのナビゲーションを追加したり拡張したりするのは非常に簡単です。ナビゲーションは以下のパターンで記述します そのページの言語 言語1 言語2 … 対応するリンクを横に並べてください。

例えばこのページでは以下のコードが使われています("[ ["の括弧の間にあるスペースは削除してください):

'''日本語''' [ [WikiHelp|English]] [ [WikiHelpFrench|Français]]<code>

多くの場合翻訳したページには元のページのタイトルの最後に言語を追加するのがよいでしょう。(元の記事が英語で書かれていたと仮定しますページ '''How to Foo''' を日本語に訳した場合にはその名前は '''How to Foo Japanese''' としてください)

=== 翻訳したページにカテゴリーを付ける方法 ===

全ての翻訳されたページは元のページと同じカテゴリーにまず分類してください('''How to Foo'''  <code>Category: How To

タグでカテゴリーされます。) そうしておけば、例えば How To カテゴリーを閲覧する開発者は How To Foo 記事の全ての翻訳をアルファベット順に見つけられます。

最初のカテゴリーが付け終わったら、その他の追加はご自由に。ここは共同作業を行う wiki です。例えば、日本語に翻訳された全ての記事を持つトップレベルカテゴリーはどうでしょう。日本語の記事だけを探している人には最適でしょう。

共同作業

wiki とはすなわち、共同で編集する場のことです。全員が使いやすくするためにも、以下の基本的なルールを守ってください。

  • ページについての議論は "Wiki forum":/forums/viewforum/16/ で行ってください
  • 理解出来るように、役に立つように、それでいて堅苦しくならずに書いてください。
  • サブヘッダによるページ構成と適切な分量の段落は、そのページを読みやすく理解しやすくします。
  • 略語を使う場合には最初に説明してください。
  • ページの名前には意味のある内容をそのまま指し示すものを使ってください。
  • 他の人々の成果を不注意で無駄にしないでください。
  • タグ付け して、ページをトピックごとにまとめてください。

シンタックスハイライト

エディタのツールバーある code タグ(アットマークが目印です)はコードを下記のようにハイライトすることが出来ます:

  1. include <QtGui>
  2. include "window.h"

int main(int argv, char **args)

{
QApplication app(argv, args);

Window window;

window.show();

return app.exec(); }

行にコードを埋め込む場合はこのようにタグを付けます: &amp;lsaquo;code&amp;amp;rsaquo;someCode(here);&amp;lsaquo;/code&amp;amp;rsaquo; その結果はこうなります <code>someCode(here);

Qt のクラスももちろんサポートしています。

カテゴリーページ

編集したページで新しくカテゴリーを作った場合、wiki は自動的にその導入ページを作成します。そのページは他のページのように編集が可能です。ページに表示されているリンクをクリックして、その先で編集してください。カテゴリーのページではそのカテゴリーに属する全てのページが表示されます。最初はそのトピックの紹介から初めてはどうでしょうか。

ヘルプ

"help forum":/forums/viewforum/4/ か "FAQ (Qt DN FAQ)":/static/devnet_faq/ を参照してください。