2. Maharaユーザマニュアル執筆者および翻訳者のための情報

by Kristina D.C. Hoeppner

これは私がユーザマニュアルを作成する際に進行中のリストです。私が表記規則を作り出した多くのものがあります。私はそれらを中央の空間に残して、他の人がそれらにアクセスできるようにし、それらを参照できるようにしたいのです。;-)

リストは特定の順序には並べられていません。

2.1. Sphinxをインストールする

MaharaユーザマニュアルはSphinxがあなたのコンピュータにインストールされることを必要とします。あなたはSphinxをインストールする方法についての情報を Sphinxウェブサイト で見つけることができます。

次の手順はDebianまたはUbuntuに基づくシステムに対するもので、あなたがターミナルで作業することを要求します。 【訳注】RedHat系Linux（CentOSなど）では、apt-getの代わりにyum（OSバージョン8以降ではdnf）を使用します。それ以外はこの手順でよいです。

  1. Python仮想環境をインストールします: sudo apt-get install python-virtualenv

  2. PDFを生成したい場合、あなたはすべてのLaTeX依存関係をインストールする必要があります: sudo apt-get install texlive-xetex texlive-lang-all texlive-fonts-extra

  3. まだ作成していない場合、あなたのコンピュータのリポジトリを置く場所にフォルダを作成します。例) code

  4. ターミナルでフォルダ「code」に入ってください: cd code

  5. ユーザマニュアルのコードをチェックアウトします:

    • SSH経由: git clone git@git.mahara.org:user-manual/manual.git または

    • HTTS経由: git clone https://git.mahara.org/user-manual/manual.git

  6. ターミナルでフォルダ「manual」に入ってください: cd manual

  7. このフォルダの仮想環境をインストールします: virtualenv venv

  8. 仮想環境を活性化します: . venv/bin/activate

  9. すべての要件をインストールします: pip install -r requirements.txt

  10. ユーザマニュアルをHTMLで構築します: make html

    注釈

    これはユーザマニュアルで利用可能なすべての翻訳を作成し、少し時間がかかります。英語版だけを作成したい場合、make preview MAHARA=17.04 でコンパイルできます。

    あなたがPDFをコンパイルしたい場合、make latexpdf でコンパイルできます。

  11. ユーザマニュアルを見るためにブラウザで index.html ファイルを開きます。あなたはフォルダ build/en/17.04 にそのファイルを見い出すことができます。

  12. いったんあなたがユーザマニュアルを編集が完了したら、ターミナルで deactivate を入力することであなたは仮想環境を非活性化できます。

2.2. ユーザマニュアルを変更する

いったんあなたがユーザマニュアルをあなたのコンピュータにインストールしたら、あなたは変更できます。次の行動はターミナルで実行されます。

  1. あなたのユーザマニュアルフォルダに入ります: cd code/manual

  2. Sphinxを使用してユーザマニュアルをコンパイルできるので、仮想環境を開始します: . venv/bin/activate

  3. あなたの好みのエディタで変更を行います。

  4. 英語でマニュアルのプレビューをコンパイルします: make preview MAHARA=17.04

    注釈

    あなたがコンパイルしているMaharaのバージョンに応じてバージョン番号を変更します。

  5. いったん編集が終了したら仮想環境を非活性化します: deactivate

2.3. スクリーンショット

  • 「figure」ディレクティブを使用して配置されます。

  • 常に代替テキスト(alt text)と図の説明を含みます。それは代替テキスと図の説明をテキストから分離します。

  • それらがステップバイステップの指示の一部である場合、一般にリストの上に置かれます。

  • それらに取り入れられるべきステップについてできるだけ少ないインストラクションを持つべきです。できれば、ステップ番号だけを交換することができ、ステップのテキストはテキストでありイメージの一部ではないため、翻訳可能です。それは翻訳者がステップを翻訳できるけれども、直ちにスクリーンショットを変更する必要がないことも意味しています。

  • あらかじめ作られた呼び出し（【訳注】callout: 図の一部を線で引き出して説明するテキスト）を得ます。Gimp ファイル /images_originals/z_callouts.xcf に見い出すことができます。

  • アイテムが指摘されるが関係するステップがない場合、矢印を得るだけです。矢印はファイル /images_originals/z_arrow.png に見い出すことができます。

  • 実行する必要があり図の下で説明されるステップが参照される呼び出し (callout) を持っています。

  • 必要なエリアを表示すべきだけで、必要ではない全体の画面、URLアドレスバー等は表示すべきではありません。

ほとんどのスクリーンショットは figure ディレクティブによって追加されます。

スクリーンショットを含む例

スクリーンショットを含む例

  1. 最初の行はファイルのパスを提供します。

    注釈

    *はファイル拡張子を置換して、Sphinx は最も適切なファイルを選択します。したがって、ファイルは異なるイメージ拡張子を持つことができるか、またはマニュアルの最終フォーマットに最も適するようにプログラムによってそのとき選択される別のファイルフォーマットで、同じスクリーンショットをあなたは持つことができます。

    Maharaユーザマニュアルのために、私達がスクリーンショットを取り扱うとき、私達は一般に.pngファイルを使います。いつかファイルフォーマットが変更されるのに備えて、.png拡張子の代わりに*を使うのがまだよいです。

  2. 2行目はイメージに移動するとき、イメージが表示されないとき、または画面リーダでページを見るときに表示される代替テキストを表しています。

  3. 3行目は空行に続ける必要があります。これはスクリーンショットの下に図の説明として表示されるテキストです。PDF出力では説明は連続的に番号を付けられます。

  4. あなたが画面からのすべての情報を表示したくないけれども、トップおよび下部を表示したい場合、あなたはファイル /images_originals/z_omission.xcf を使い、それをあなたのスクリーンショットに置くことができます。正弦波は次の設定によって、gimpプラグイン 図形パス を用いて作成されました：

    • 正弦波

    • 開始 X: 0

    • 開始 Y: 200および線の間のギャップを得るためにセカンドラン215の上

    • 振幅: 3

    • 波長: 25

    • 繰り返し数: 40 (スクリーンショットの幅に依存します)

    • ストロークパスのための印

    • ストローク色: CCCCCC

注釈

イメージをインラインでテキストに含めたい場合で、標準の図を使用したくない、または使用できない場合、あなたは置換を作成し、それをshortcuts.rstextファイルに配置する必要があります。すでにショートカットファイルに多くの例があります。

2.4. 使用中の忠告

注意: 少しだけ注意が必要なすべてのことです。

注釈

注意は箇条書き（ビュレット付きのリスト）内に直接置けます。いつものように、注意の前後に空行を置く必要があり、忠告は三つの空白で字下げする必要があります。

警告: 注意しながら実施する必要のあるすべてのことです。

警告

本当に重要な情報を失ってしまうため、すべてを警告内に入れないようにします。

参照: 他の文書の参照のために、それらに特別な配慮が必要です 。他の文書の参照はまた、テキストインラインに含めることができます。

参考

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:」 の前（が句読点でない場合）と 「>`」 の後（が句読点でない場合）に空白を挿入します。

  • 管理のような長いセクションは一つの非常に長いページにすべてを持っている代わりに、編集することをもっと扱いやすくするために数ページに分割されます。

  • reStructuredTextは見出しのレベルの階層セットを持っていません。それらは個々のファイルに依存します。しかし、一貫するように次の表記規則が存在します：

    • 見出し1 例) 1.: ===============

    • 見出し2 例) 1.1.: —————

    • 見出し3 例) 1.1.1.: ~~~~~~~~~~~~~~~

    • 見出し4 例) 1.1.1.1.: ^^^^^^^^^^^^^^^

  • h4より下の見出しは避けるべきです。

  • 索引ページは主見出しの他に見出しを持っていません。これにより、目次や見出しを持つその他のセクションがマニュアルの主要な章になるのを防ぐことができます。** によって索引ページの見出しを正しいボールドに保持します。（【訳注】 index ディレクティブで明示的に指定された 「セクション」 も見出しとなっています。さらに、本文テキスト中の上記 :index: により作成された見出しもあります。）

2.6. インテキストフォーマット

  • 箇条書きリストはそれぞれの箇条書きの前に * 記号を付けます。

  • 番号付きリストにはそれぞれの番号付きアイテムの最初に #. が付けられます。

  • あなたが字下げされた箇条書きまたは番号を付けられたリストを必要とする場合、字下げされたリストの前に空行を置き、それから、三つの空白で個々の行を字下げします。字下げされたリストの終わりは空行である必要もあります。

  • 強調テキストは一つの* で開始し、終了します。例) *this* は次のようになります。 this 【訳注】日本語のように分かち書きしない言語では *this* の前後（が句読点でない場合）に空白を挿入します。

  • ボールド体テキストは二つの* で開始し、終了します。例) **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.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**" （日本語： 「貢献者」））。それは翻訳ではないので、英語のマニュアルに相当する文はありません。