2. Maharaのマニュアル作成者および翻訳者向け情報

これは進行中のリストです。私が表記規則を作り出した多くのものがあります。これは誰もがそれらにアクセスできるようにそれらを保持するための中心的なスペースです。

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

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

MaharaのマニュアルではコンピュータにSphinxがインストールされている必要があります。Sphinxのインストール方法に関する情報は Sphinxウェブサイト にあります。

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

Note

The setup requires that you can run Docker successfully on your computer. Please refer to the Docker instructions for your operating system to set it up.

  1. まだ作成していない場合、あなたのコンピュータのリポジトリを置く場所にディレクトリを作成してください。例) code

  2. ターミナルでフォルダ 'code' に入ります: cd code

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

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

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

  4. Check that you are on the correct branch of the manual that you want to update: git branch

  5. ターミナルで、フォルダ 'manual' に入ります: cd manual

  6. Build or update the dockerised manual builder: manual-build/build-builder.sh

  7. Build the manual in HTML for the version of Mahara you selected: make html

    Note

    This will create all translations that are available for the manual and will take a bit. If you only want to create the English manual, you can compile it with manual-build/build-manual.sh TRANSLATIONS=en html

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

  8. Open the index.html file in a browser to view the manual. You can find it in the folder build/en/.

    Note

    If you don’t see the icons, you may need to use Chromium and start it from the terminal to temporarily disable the security setting, which prevents you from loading the icons: chromium --disable-web-security --user-data-dir=/tmp

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

コンピュータにマニュアルをインストールしたら、変更を加えることができます。ターミナルでは次のアクションが実行されます。

  1. 'manual' フォルダに入ります: cd code/manual

  2. Make changes in your preferred editor.

  3. Compile a preview of the manual just in English: manual-build/build-manual.sh TRANSLATIONS=en html

  4. Commit your changes.

2.3. スクリーンショット

  • 'figure' 指令を使用して配置されます。

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

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

  • それらで取られるべき手順についてできるだけ少ない指示を持っているべきです。交換できるように手順番号だけが好ましく、手順のテキストはテキストであり、イメージの一部ではないため、翻訳可能です。これは翻訳者が手順を翻訳できるが、スクリーンショットをすぐに変更する必要がないことも意味します。

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

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

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

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

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

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

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

    Note

    *はファイル拡張子を置換して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

Note

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

2.4. 使用中の忠告

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

Note

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

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

Warning

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

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

See also

Sphinxドキュメンテーション はSphinxによってrSTを使用するあなたの知識と理解を深める(deepend)のに最高の場所です。何か質問があれば、Sphinxディスカッショングループ もチェックできます。

やるべきこと: 実行しているやるべきことのリストを保持するために。やるべきことのリストは現在無効です。

2.5. 表記規則

Note

単語間にスペースを入れない言語

Sphinxはコマンドの開始前と終了後には常にスペースがあると仮定します。それがマークアップ文字をSphinxに何をすべきかを伝えるものとして認識する必要がある唯一の方法です。

これは単語の間にスペースがない日本語などの言語では問題になります。

ただし、テキストにスペースを入れる必要はありません。そうでなければ、フォーマットは行われず、索引項目は作成されず、置換は行われません。したがって、英語版に表示されるスペーシングを複製してください。例えば次のような場合はスペースを入れます。

  • |edit| のような置換の前後、

  • :index::ref: の前、および索引項目または参照が終了したときです。

  • 単語の後に続く * の前と閉じた * の後、例えば *word* これはフォーマットが word に変更されたことを示すためです。 ** で始まる単語と終わる単語についても同様です。

  • ナビゲーションメニューアイテムに関連するそれぞれのセクションにはパスの記述が必要です 例) メインメニュー → 作成 → ファイル。正しい矢印を取得するには矢印 ( → ) をコピーします。

  • 保存ページをコピー などのボタン、およびまた 作成共有 などのポートフォリオセクション は (単一の*によって) 強調されたテキストとして強調されます。

  • 小さなボタンは のようにテキストに含めることができます。それらは置換を通して追加されます。すべての置換は、ファイルの最初の行に '.. include:: /shortcuts.rstext' を置くことによって、どの置換が使われるかは個々のファイルに含められているファイル shortcuts.rstext に保持されています。置換は、それらを取り扱う操作が何かを指摘している例として、 '*Edit* button |edit|' のようにテキストで参照されます。翻訳者は置換 '|edit|' 自体を編集するべきではなく、強調表示したワードが出現することを保証するために、 *とテキストの間にどのような空白も置かずに再び* を注意して含める、 '*Edit* button' を変更するだけにすべきです。【訳注】日本語のように分かち書きしない言語では、 '|edit'| の前後(が句読点でない場合)に空白を挿入します。

  • それぞれのセクションに索引のエントリを作成します。

  • 新しい機能は、 'single: Mahara x で新しい; [新しい機能]' というフォームで索引のエントリをよく受け取ります。索引のエントリは全体のセクションの上またはインラインに置くことができます。インラインは、読者が新しい機能に直接連れて行かれるように、小さな機能的な変更のために望ましいです。これは次のように行うことができます:

    :index:`ソート順を決める <single: 'フォルダ' ブロック内のファイルのソート順>`

    Warning

    ':index:' の直前および/または '>`' の直後が句読点でない場合、 ':index:' の直前および/または '>`' の直後に空白を挿入する必要があります。【訳注】なお、 ':index:' の直前が句読点の場合でも、 ':index:' の直後のテキストがダブルクォートやシングルクォートで始まっている場合は、 ':index:' の直前に空白を挿入する必要があります。さらに、 ' <single:' の直前がダブルクォートやシングルクォートで終わっている場合は、 '>`' の直後に空白を挿入する必要があります。

  • 管理のような長いセクションは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.pysmartquotes_excludes = {'languages': [], 'builders': ['man', 'text']} と設定してあるので、 "文字列" のように ダブルクォートで囲んだ文字列は 「文字列」のように 前後を鍵カッコで囲まれます。 開始ダブルクォートの直前と終了ダブルクォートの直後には必ず空白が必要です(終了ダブルクォートの直後が句読点の場合は空白は不要です)。また、 '文字列' のように シングルクォートで囲んだ文字列は 『文字列』のように 前後を二重鍵カッコで囲まれます。 開始シングルクォートの直前と終了シングルクォートの直後には必ず空白が必要です(終了シングルクォートの直後が句読点の場合は空白は不要です)。

2.8. 翻訳者は注意してください

  • < > の間に置かれる内部のリンクのためのターゲットを変更しないでください。その場合、参照は見つけることができなくなります。山括弧のすぐ前に説明的なテキストが常にあるはずです。あなたはそれを変更できます。

  • 同様にあなたはURLのテキストを変更できます。あなたの言語のサイトへのURLを置換する以外、URL自体を変更できません。

  • スクリーンショットおよびその他のイメージを翻訳する場合、例えば Mahara 22.04 のように、Git で編集しているマニュアルのバージョンの個々のブランチに表示される、 'images' フォルダのフォルダ構造を保持することに努めてください。

  • マニュアルで使用されているオリジナルのイメージは 'images_original' フォルダおよびそれぞれのサブフォルダにあります。背景だけを交換し、吹き出しは保持したい場合、自分の翻訳にそれらを使用できます。

  • あなたは例えばブロックアイコン、Maharaのまわりの一般的なボタン、テキストエディタボタン等の「翻訳」しないイメージを作り直す必要はありません。翻訳にないイメージは英語のオリジナルから取得されます。

  • マニュアルは1日に1回更新され、Launchpadから新しい翻訳文字列が取り込まれ、変更があればマニュアルのコンパイル前にGitにイメージがアップロードされます。

Note

あなたの言語のマニュアルの主要な翻訳者の氏名を言及したい場合、「MaharaマニュアルはMaharaコミュニティのメンバによって書かれています。」 の直後に追加できます。この段落は目次の前に表示されます。これは翻訳ではないため、英語のマニュアルに同等の文はありません。