2. Maharaのマニュアル作成者および翻訳者向け情報¶
これは進行中のリストです。私が表記規則を作り出した多くのものがあります。これは誰もがそれらにアクセスできるようにそれらを保持するための中心的なスペースです。
リストは特定の順序には並べられていません。
2.1. Sphinxをインストールする¶
MaharaのマニュアルではコンピュータにSphinxがインストールされている必要があります。Sphinxのインストール方法に関する情報は Sphinxウェブサイト にあります。
次の手順はDebianまたはUbuntuに基づくシステムに対するもので、あなたがターミナルで作業することを要求します。 【訳注】RedHat系Linux(CentOSなど)では、apt-getの代わりにyum(OSバージョン8以降ではdnf)を使用します。それ以外はこの手順でよいです。
Python仮想環境をインストールします:
sudo apt-get install python-virtualenv
PDFを生成したい場合、あなたはすべてのLaTeX依存関係をインストールする必要があります:
sudo apt-get install texlive-xetex texlive-lang-all texlive-fonts-extra
まだ作成していない場合、あなたのコンピュータのリポジトリを置く場所にディレクトリを作成してください。例)
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
このフォルダの仮想環境をインストールします:
virtualenv venv
仮想環境を活性化します:
. venv/bin/activate
すべての要件をインストールします:
pip install -r requirements.txt
HTMLでマニュアルを作成します:
make html
注釈
これにより、マニュアルで使用可能なすべての翻訳が作成され、少し時間がかかります。英語のマニュアルだけを作成する場合、
make preview MAHARA=22.04
でコンパイルできます。あなたがPDFをコンパイルしたい場合、
make latexpdf
でコンパイルできます。ユーザマニュアルを見るためにブラウザで
index.html
ファイルを開きます。あなたはフォルダbuild/en/22.04
にそのファイルを見い出すことができます。マニュアルの編集が完了したら、ターミナルで
deactivate
と入力して仮想環境を非アクティブ化できます。
2.2. マニュアルを変更する¶
コンピュータにマニュアルをインストールしたら、変更を加えることができます。ターミナルでは次のアクションが実行されます。
'manual'
フォルダに入ります:cd code/manual
Sphinxを使ってマニュアルをコンパイルできるように仮想環境を起動する:
. venv/bin/activate
あなたの好みのエディタで変更してください。
英語でマニュアルのプレビュをコンパイルします:
make preview MAHARA=22.04
注釈
あなたがコンパイルしているMaharaのバージョンに応じてバージョン番号を変更します。
いったん編集が終了したら仮想環境を非活性化します:
deactivate
2.3. スクリーンショット¶
'figure'
指令を使用して配置されます。常に代替テキスト(alt text)と図の説明を含みます。それは代替テキスと図の説明をテキストから分離します。
それらがステップバイステップの指示の一部である場合、一般にリストの上に置かれます。
それらで取られるべき手順についてできるだけ少ない指示を持っているべきです。交換できるように手順番号だけが好ましく、手順のテキストはテキストであり、イメージの一部ではないため、翻訳可能です。これは翻訳者が手順を翻訳できるが、スクリーンショットをすぐに変更する必要がないことも意味します。
あらかじめ作られた呼び出し(【訳注】callout: 図の一部を線で引き出して説明するテキスト)を得ます。Gimp ファイル
/images_originals/z_callouts.xcf
に見い出すことができます。アイテムが指摘されるが関係するステップがない場合、矢印を得るだけです。矢印はファイル
/images_originals/z_arrow.png
に見い出すことができます。実行する必要があり図の下で説明されるステップが参照される呼び出し (callout) を持っています。
必要なエリアを表示すべきだけで必要ではない全体の画面、URLアドレスバー等は表示すべきではありません。
ほとんどのスクリーンショットは figure ディレクティブによって追加されます。
![スクリーンショットを含む例](_images/figure_directive.png)
スクリーンショットを含む例¶
最初の行はファイルのパスを提供します。
注釈
*はファイル拡張子を置換して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. 表記規則¶
注釈
単語間にスペースを入れない言語
Sphinxはコマンドの開始前と終了後には常にスペースがあると仮定します。それがマークアップ文字をSphinxに何をすべきかを伝えるものとして認識する必要がある唯一の方法です。
これは単語の間にスペースがない日本語などの言語では問題になります。
ただし、テキストにスペースを入れる必要はありません。そうでなければ、フォーマットは行われず、索引項目は作成されず、置換は行われません。したがって、英語版に表示されるスペーシングを複製してください。例えば次のような場合はスペースを入れます。
|edit|
のような置換の前後、
:index:
や:ref:
の前、および索引項目または参照が終了したときです。単語の後に続く
*
の前と閉じた*
の後、例えば*word*
これはフォーマットが word に変更されたことを示すためです。**
で始まる単語と終わる単語についても同様です。
ナビゲーションメニューアイテムに関連するそれぞれのセクションにはパスの記述が必要です 例) メインメニュー → 作成 → ファイル。正しい矢印を取得するには矢印 ( → ) をコピーします。
保存 や ページをコピー などのボタン、およびまた 作成 や 共有 などのポートフォリオセクション は (単一の*によって) 強調されたテキストとして強調されます。
小さなボタンは 、 のようにテキストに含めることができます。それらは置換を通して追加されます。すべての置換は、ファイルの最初の行に
'.. include:: /shortcuts.rstext'
を置くことによって、どの置換が使われるかは個々のファイルに含められているファイル shortcuts.rstext に保持されています。置換は、それらを取り扱う操作が何かを指摘している例として、'*Edit* button |edit|'
のようにテキストで参照されます。翻訳者は置換'|edit|'
自体を編集するべきではなく、強調表示したワードが出現することを保証するために、 *とテキストの間にどのような空白も置かずに再び* を注意して含める、'*Edit* button'
を変更するだけにすべきです。【訳注】日本語のように分かち書きしない言語では、'|edit'|
の前後(が句読点でない場合)に空白を挿入します。それぞれのセクションに索引のエントリを作成します。
新しい機能は、
'single: Mahara x で新しい; [新しい機能]'
というフォームで索引のエントリをよく受け取ります。索引のエントリは全体のセクションの上またはインラインに置くことができます。インラインは、読者が新しい機能に直接連れて行かれるように、小さな機能的な変更のために望ましいです。これは次のように行うことができます::index:`並べ替え順序を決定する <single: Mahara22.04の新機能; 'フォルダ' ブロック内のファイルの並べ替え順序>`
警告
':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.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:
の前に空白を挿入します。` はアクセントマークです。垂直の一重引用符ではありません。
テキスト中ターゲットはアンダスコアが先行するアクセントマーク内でリンクされるテキストを置くことで達成できます:
_`内部の参照`
。参照することは通常の:ref:`[リンクされるテキスト] <内部の参照>`
です。
2.8. 翻訳者は注意して¶
< >の間に置かれる内部のリンクのためのターゲットを変更しないでください。あなたが変更する場合、参照は見つけることができません。山括弧のすぐ前に説明的なテキストが常にあるはずです。あなたはそれを変更できます。
同様にあなたはURLのテキストを変更できます。あなたの言語のサイトへのURLを置換する以外、URL自体を変更できません。
スクリーンショットおよびその他のイメージを翻訳する場合、例えば Mahara 22.04 のように、Git で編集しているマニュアルのバージョンの個々のブランチに表示される、
'images'
フォルダのフォルダ構造を保持することに努めてください。マニュアルで使用されているオリジナルのイメージは
'images_original'
フォルダと、それぞれのサブフォルダにあります。背景だけを交換し、吹き出しは保持したい場合、自分の翻訳にそれらを使用できます。『翻訳』 しないイメージ、例えばブロックアイコン、Maharaのまわりの一般的なボタン、テキストエディタボタンを作り直す必要はありません。翻訳にないイメージは英語のオリジナルから取得されます。
マニュアルは1日に1回更新され、Launchpadから新しい翻訳文字列が取り込まれ、変更があればマニュアルのコンパイル前にGitにイメージがアップロードされます。
注釈
あなたの言語のマニュアルの主要な翻訳者の名前を言及したい場合、 『MaharaマニュアルはMaharaコミュニティのメンバによって書かれています。』 の直後に文を追加できます。その段落は目次の前に表示されます。これは翻訳ではないため英語のマニュアルには同等の文はありません。