2. Maharaユーザマニュアル執筆者および翻訳者のための情報¶
by Kristina D.C. Hoeppner
これは私がユーザマニュアルを作成する際に進行中のリストです。私が表記規則を作り出した多くのものがあります。私はそれらを中央の空間に残して、他の人がそれらにアクセスできるようにし、それらを参照できるようにしたいのです。;-)
リストは特定の順序には並べられていません。
2.1. Sphinxをインストールする¶
MaharaユーザマニュアルはSphinxがあなたのコンピュータにインストールされることを必要とします。あなたはSphinxをインストールする方法についての情報を Sphinxウェブサイト で見つけることができます。
2.2. コードを取得する¶
Maharaユーザマニュアルで使用されるコードはgitで管理されています。
まだ作成していない場合、あなたのコンピュータのリポジトリを置く場所にフォルダを作成します。例)
codeターミナルでフォルダ「code」に入ってください:
cd codeコードをチェックアウトします:
SSH経由:
git clone git@git.mahara.org:user-manual/manual.gitまたはHTTS経由:
git clone https://git.mahara.org/user-manual/manual.git
ターミナルでフォルダ「manual」に入ってください:
cd manualユーザマニュアルを英語だけでコンパイルします。以下のコマンドはあなたがMahara15.10のためにそれをコンパイルしたいと仮定しています:
make preview MAHARA=15.10マニュアルを見るために、ブラウザに
index.htmlファイルを開きます。あなたはそれをbuild/en/15.10というフォルダに見い出すことができます。
2.3. スクリーンショット¶
「figure」 指令を使用して配置されます。
常に代替テキスト(alt text)と図の説明を含みます。それは代替テキスと図の説明をテキストから分離します。
それらがステップバイステップの指示の一部である場合、一般にリストの上に置かれます。
それらに取り入れられるべきステップについてできるだけ少ないインストラクションを持つべきです。できれば、ステップ番号だけを交換することができ、ステップのテキストはテキストでありイメージの一部ではないため、翻訳可能です。それは翻訳者がステップを翻訳できるけれども、直ちにスクリーンショットを変更する必要がないことも意味しています。
あらかじめ作られた呼び出し（【訳注】callout: 図の一部を線で引き出して説明するテキスト）を得ます。Gimp ファイル
/images_originals/z_callouts.xcfに見い出すことができます。アイテムが指摘されるが関係するステップがない場合、矢印を得るだけです。矢印はファイル
/images_originals/z_arrow.pngに見い出すことができます。実行する必要があり図の下で説明されるステップが参照される呼び出し (callout) を持っています。
必要なエリアを表示すべきだけで、必要ではない全体の画面、URLアドレスバーなどは表示すべきではありません。
ほとんどのスクリーンショットは figure 指令によって追加されます。
スクリーンショットを含む例¶
最初の行はファイルのパスを提供します。
注釈
*はファイル拡張子を置換して、Sphinx は最も適切なファイルを選択します。したがって、ファイルは異なるイメージ拡張子を持つことができるか、またはマニュアルの最終フォーマットに最も適するようにプログラムによってそのとき選択される別のファイルフォーマットで、同じスクリーンショットをあなたは持つことができます。
Maharaユーザマニュアルのために、私達がスクリーンショットを取り扱うとき、私達は一般に.pngファイルを使います。いつかファイルフォーマットが変更されるのに備えて、.png拡張子の代わりに*を使うのがまだよいです。
2行目はイメージに移動するとき、イメージが表示されないとき、または画面リーダでページを見るときに表示される代替テキストを表しています。
3行目は空行に続く必要があります。これはスクリーンショットの下に図の説明として表示されるテキストです。PDF出力では説明は連続的に番号を付けられます。
あなたが画面からのすべての情報を表示したくないけれども、トップおよび下部を表示したい場合、あなたはファイル
/images_originals/z_omission.xcfを使い、それをあなたのスクリーンショットに置くことができます。正弦波は次の設定によって、gimpプラグイン 図形パス を用いて作成されました：正弦波
開始 X: 0
開始 Y: 200および線の間のギャップを得るためにセカンドラン215の上
振幅: 3
波長: 25
繰り返し数: 40 (スクリーンショットの幅に依存します)
ストロークパスのための印
ストローク色: CCCCCC
注釈
イメージをインラインでテキストに含めたい場合で、標準の図を使用したくない、または使用できない場合、あなたは置換を作成し、それをshortcuts.rstextファイルに配置する必要があります。すでにショートカットファイルに多くの例があります。
2.4. 使用中の忠告¶
注意: 少しだけ注意が必要なすべてのことです。
注釈
注意は箇条書き（ビュレット付きのリスト）内に直接置けます。いつものように、注意の前後に空行を置く必要があり、忠告は3つの空白で字下げする必要があります。
警告: 注意しながら実施する必要のあるすべてのことです。
警告
本当に重要な情報を失ってしまうため、すべてを警告内に入れないようにします。
参照: 他の文書の参照のために、それらに特別な配慮が必要です 。他の文書の参照はまた、テキストインラインに含めることができます。
参考
Sphinxユーザドキュメンテーション はSphinxによってrSTを使用するあなたの知識と理解を深める(deepend)のに最高の場所です。何か質問があれば、あなたは Sphinxディスカッショングループ もチェックできます。
やるべきこと: 実行しているやるべきことのリストを保持するために。やるべきことのリストは現在無効です。
2.5. 表記規則¶
ナビゲーションメニューアイテムに関連するそれぞれのセクションにはパスの記述が必要です 例) コンテンツ → ファイル。正しい矢印を取得するには矢印 ( → ) をコピーします。
保存 や ページをコピー などのボタン、およびまた コンテンツ や ポートフォリオ などのポートフォリオセクション は (単一の*によって) 強調されたテキストとして強調されます。
小さなボタンは 、 のようにテキストに含めることができます。それらは置換を通して追加されます。すべての置換はファイルの最初の行に
".. include:: /shortcuts.rstext"を置くことによって、どの置換が使われるかは個々のファイルに含められているファイル shortcuts.rstext に保持されています。置換はあなたがそれらを取り扱う操作が何かを指摘している例として、"*Edit* button |edit|"のようにテキストで参照されます。翻訳者は置換"|edit|"自体を編集するべきではなく、強調表示したワードが出現することを保証するために、 *とテキストの間にどのような空白も置かずに再び* を注意して含める、"*Edit* button"を変更するだけにすべきです。【訳注】日本語のように分かち書きしない言語では"|edit|"の前後（が句読点でない場合）に空白を挿入します。それぞれのセクションに索引のエントリを作成します。
新しい機能は
"single: Mahara x で新しい; [新しい機能]"というフォームで索引のエントリをよく受け取ります。索引のエントリは全体のセクションの上またはインラインに置くことができます。インラインは読者が新しい機能に直接連れて行かれるように、小さな機能的な変更のために望ましいです。これは次のように行うことができます：:index:`並べ替えの順序を決めます <single: Mahara 15.04 で新しい; "フォルダ" ブロックのファイルの並べ替えの順序>`【訳注】日本語のように分かち書きしない言語では 「:index:」 の前（が句読点でない場合）と 「>`」 の後（が句読点でない場合）に空白を挿入します。管理のような長いセクションは1つの非常に長いページにすべてを持っている代わりに、編集することをもっと扱いやすくするために数ページに分割されます。
reStructuredTextは見出しのレベルの階層セットを持っていません。それらは個々のファイルに依存します。しかし、一貫するように次の表記規則が存在します：
見出し1 例) 1.: ===============
見出し2 例) 1.1.: —————
見出し3 例) 1.1.1.: ~~~~~~~~~~~~~~~
見出し4 例) 1.1.1.1.: ^^^^^^^^^^^^^^^
h4より下の見出しは避けるべきです。
索引ページは主見出しの他に見出しを持っていません。これにより、目次や見出しを持つその他のセクションがマニュアルの主要な章になるのを防ぐことができます。** によって索引ページの見出しを正しいボールドに保持します。（【訳注】
indexディレクティブで明示的に指定された 「セクション」 も見出しとなっています。さらに、本文テキスト中の上記:index:により作成された見出しもあります。）
2.6. インテキストフォーマット¶
箇条書きリストはそれぞれの箇条書きの前に * 記号を付けます。
番号付きリストにはそれぞれの番号付きアイテムの最初に #. が付けられます。
あなたが字下げされた箇条書きまたは番号を付けられたリストを必要とする場合、字下げされたリストの前に空行を置き、それから、3つの空白で個々の行を字下げします。字下げされたリストの終わりは空行である必要もあります。
強調テキストは1つの* で開始し、終了します。例)
*this*は次のようになります。 this 【訳注】日本語のように分かち書きしない言語では*this*の前後（が句読点でない場合）に空白を挿入します。ボールド体テキストは2つの* で開始し、終了します。例)
**this**は次のようになります。 this 【訳注】日本語のように分かち書きしない言語では**this**の前後（が句読点でない場合）に空白を挿入します。ここで、 日本語の場合のDocutilsのSmart Quotesという機能について補足します。 Sphinx のconfig.pyで、smartquotes = (True, 'env', [])とsmartquotes_excludes = ({'languages': [ja], 'builders': ['man', 'text']}, 'env', [])が設定されているため、ダブルクォートやシングルクォートで囲んだ文字列は英文と同じようにシングルクォートとダブルクォートはそのまま表示されます。 しかし、 Mahara マニュアルのmanual-buildにあるconf-common.pyでsmartquotes_excludes = {'languages': [], 'builders': ['man', 'text']}と設定してあるので、"文字列"のように ダブルクォートで囲んだ文字列は 「文字列」のように 前後を鍵カッコで囲まれます。 開始ダブルクォートの直前と終了ダブルクォートの直後には必ず空白が必要です（終了ダブルクォートの直後が句読点の場合は空白は不要です）。また、'文字列'のように シングルクォートで囲んだ文字列は 『文字列 』のように 前後を二重鍵カッコで囲まれます。 開始シングルクォートの直前と終了シングルクォートの直後には必ず空白が必要です（終了シングルクォートの直後が句読点の場合は空白は不要です）。
2.7. ハイパーリンク¶
外部リンク: 「
`[text that is linked] <URL>`_」 - 翻訳者は 「[text that is linked]」 だけを置換します。【訳注】日本語のように分かち書きしない言語では`[text that is linked] <URL>`_の前後（が句読点でない場合）に空白を挿入します。マニュアルの他の場所からリンクできる内部の参照は見出しのすぐ前の行に 「
.. [reference_text]:」を置くことによって作成されます。私は通常参照と見出しの間の空行を置いています。内部の参照にリンクする: 「
:ref:`[リンクされるテキスト] <内部の参照>`」 - 翻訳者は 「[リンクされるテキスト]」 を置き換えるだけにすべきです。【訳注】日本語のように分かち書きしない言語では:ref:`[リンクされるテキスト] <内部の参照>`の前後（が句読点でない場合）に空白を挿入します。` はアクセントマークです。垂直の一重引用符ではありません。
テキスト中ターゲットはアンダースコアが先行するアクセントマーク内でリンクされるテキストを置くことによって達成できます:
_`内部の参照`。参照することは通常の:ref:`[リンクされるテキスト] <内部の参照>`です。
2.8. 翻訳者は注意して¶
< >の間に置かれる内部のリンクのためのターゲットを変更してはいけません。あなたが変更する場合、参照は見つけることができません。山カッコのすぐ前に説明的なテキストが常にあるはずです。あなたはそれを変更できます。
同様にあなたはURLのテキストを変更できます。あなたの言語のサイトへのURLを置換する以外、URL自体を変更できません。
あなたがスクリーンショットおよび他のイメージを翻訳する場合、どうぞ、例えば Mahara 15.10 のために、Git においてあなたが編集するマニュアルのバージョンの個々のブランチであなたが見ることができるので、あなたが 「images」 フォルダのフォルダ構造を保持することを保証してください。
あなたは 「images_original」 フォルダと、そしてそれらの個々のサブフォルダでマニュアルのためにオリジナルのイメージが使われるのを見つけることができます。あなたが、背景を交換して呼び出しを保持したいだけの場合、あなたはあなた自身の翻訳のためにそれらを使うことができます。
あなたが 「翻訳」 しないイメージ、例えば、ブロックアイコン、Maharaのまわりの一般的ボタン、テキストエディタボタンを作り直す必要はありません。あなたの翻訳にないイメージは英語のオリジナルから受け継がれます。
ユーザマニュアルは1日1回更新されます。新しい翻訳およびはマニュアルの編集に先立ってGitにアップロードされたイメージはLaunchpadより取得されます。
現在、すべてがSphinxで翻訳されているわけではありません。今後のバージョンで対応されることを希望します。
注釈
あなたがあなたの言語のユーザマニュアルの主要な翻訳者の名前に言及したい場合、 "The Mahara user manual is written by Mahara community members." （日本語： 「MaharaユーザマニュアルはMaharaコミュニティメンバーにより書かれています。」）のすぐ後に、あなたが文を追加できます。パラグラフは目次の前に出現します（訳注： "index.html" ページの "**Contributors**" （日本語： 「貢献者」））。それは翻訳ではないので、英語のマニュアルに相当する文はありません。