Krita マニュアルのマークアップ規約¶
ここでは、Krita マニュアルで reStructuredText を使用するための構文規則について詳しく説明します。
reStructuredText の 公式仕様書 にアクセスし、あなたのパソコンにドキュメントのコピーを保存することをお勧めします。(SourceForge は、この記事を執筆している時点で、サーバの稼働状況に関していくつかの問題を抱えています。):
- ユーザマニュアル:
- リファレンスドキュメント:
- Sphinx 固有のドキュメント:
Sphinx' page on restructured text -- これは目次などの生成に使用する Sphinx 特有の directives と roles の記述に便利です。
There are differences between the official reStructuredText and the sphinx docs multiple ways to do things. This document specifies the suggested conventions to go with.
Meta data¶
各ページは次の3つの項目から始める必要があります。
- meta の記述
ページの一般的な記述です。これは検索エンジンで使用される html meta tag に変換されます。
.. meta:: :description: Description.
- 著者リストとライセンス項目
誰がページを編集したかを追跡し、称賛するためです。システムが命令と勘違いしないように、コメントに含める必要があります。マニュアル全体のライセンスは GDL 1.3 であり、ここにも記載する必要があります:
.. metadata-placeholder :authors: - Author 1 - Author 2 :license: GNU free documentation license 1.3 or later.
- 索引用の単語
These are comma-separated terms under which the page will be indexed in 索引. The generated index is quite useful for both PDF as well as people who are not sure what the exact name is of the term they are looking for. They are defined as follows:
.. index:: Keyword, Keyword with Spaces, ! Main Definition Keyword
- ラベル
:ref:`label_name`を使用してページに簡単にリンクできるようにするためのものです。良いラベル名を考えて作成してみてください:.. _label_name:
:ref:`label_name`がリンクのテキスト用に見出しを参照するので、ラベル使用後は見出しを追加する必要があります。
見出し¶
見出しは次のような順序で作成されます:
############
Part/Section
############
For pages that have a lot of subpages.
=========
Heading 1
=========
Start most manual pages with this.
Heading 2
---------
Heading 3
~~~~~~~~~
Heading 4
^^^^^^^^^
Heading 5
'''''''''
Heading 6
"""""""""
これらの規約はほとんど Pandoc' による mediawiki から reStructuredText への変換の際に決定されました。4段落以上の見出しが必要な場合は、ページが複雑すぎないか、分割する必要があるかを確認します。
ページの小節(サブセクション)にリンクする必要がある場合は、見出し内でラベルを追加します。
見出しは、ラベルにリンクするときにリンク名として使用されるため、句読点を末尾に使用できません。
リンク¶
リンクは :ref:`label_name` で行われます。リンクのテキストを別のものに変更したい場合は、:ref:`(表示したいテキスト) <label_name>` を使用します。
外部リンクは `url`_ もしくは `link name <url>`_ と記述します。これはどちらも link name と表示されます。
Pandoc は `link name`__ となっている場合、.. __ :url をテキストの最後に自動的に追加します。いわゆる「anonymous hyperlink (匿名ハイパーリンク)」であり、テキストのリンクの順番に応じて、テキスト最後のリンクが暗黙的に関連付けられることを意味します。この仕組みは混乱を引き起こし、理解の妨げになります。そして、このリンクの使用を避けたい理由でもあります。
脚注と出典¶
脚注は次の3つの方法で記述できます。最も一般的な方法は、参照に従った自動番号割り当てです。
[1] は脚注 1 を参照し、[2] は脚注 2 を参照します。
[3] は脚注 3 を参照します。
引用文献はここです: [CIT2002]
これが引用です。ラベルがテキストであることを除けば、脚注と同じです。
引用は `citation <CIT2002>`_ と記述して参照させることもできます。
このマニュアルにおいて、脚注の使用は読者に若干学術的に見えるため、実際には使用していません。ただし、ページの末尾にこの情報をもう少し詳しく示すドキュメントやリンクをまとめています。Sphinx には外部リンク用の .. seealso:: がありますが、reStructuredText では 特に脚注として LaTeX でうまく動作する .. rubic:: Footnotes を提案しています。
画像¶
見出しなしで画像を表示したい場合は次のように記述します:
.. image:: /images/sample.png
:width: 800
:align: center
:alt: an image.
見出しを付ける場合は次のようになります:
.. figure:: /images/sample.png
:figwidth: 800
:align: center
:alt: an image.
A caption -- notice how the first letter is aligned with the :figwidth: option.
このように表示されます:
A caption -- notice how the first letter of the caption in the directive is aligned with the :figwidth: option.¶
画像は /images フォルダに保存されます。images の代わりに /images を使用すると、Sphinx はファイルのパスが相対ではない(絶対パスである)と解釈します。
テキスト表示¶
emphasized と strong のように文字をそれぞれ単一か二重の「*」で囲むことで強調できます:
*emphasize*
**strong**
*二種類の強調表示* の両方を使用することはできないので、どちらか選択してください。
You can subscript text and superscript text by using :sub:`text` and :sup:`text`.
ただし、使用は最小限にしてください。どのような場合でも Sphinx の既存のセマンティックマークアップを使用することを推奨します。これにより、翻訳者がテキストの意味を判断しやすくなります。
:menuselection:`Settings --> Configure Krita...`
:guilabel:`File`
:kbd:`Ctrl + Z`
:program:`Krita`
手当たり次第に太字にすることは避けてください。文章が読みやすくなるわけではありません。
参照の置き換え¶
次のように記述するとテキストや画像の短縮形を定義できます:
.. |shorthand| replace:: something or the other.
つまり、テキスト中に上のように定義された |shorthand| を使用すると、'something or the other' に置き換えられます。これは "LaTeX" のように複雑な構文が必要な画像やテキストに便利です。
Krita ドキュメントには |mouseleft| , |mousemiddle| , |mousescroll| , |mouseright| が既に定義されており、それぞれ 
, 
, 
, 
のように表示されます。これらは Sphinx の conf.py で定義され、各 rst ファイルに追加されます。
同じリンクを何度も使用する場合において、ファイルの末尾に次のように記述することができます:
.. _bugzilla: https://bugs.kde.org/
.. _Krita Manual: https://docs.krita.org/
リンクを入力するときに `bugzilla`_ を使用すると、"bugzilla" をリンクのテキストとして bugs.kde.org にリンクできます。`Krita Manual`_ は "Krita Manual" の表示で docs.krita.org にリンクします。
リスト¶
順序ありのリスト¶
Apple
Pear
Banana
もしくは
Table
Chair
Wardrobe.
Augustus
Nero
Caligula
Trajan
これらは次のように定義できます:
1. Apple
2. Pear
3. Banana
#. Apple
#. Pear
#. Banana
A. Table
B. Chair
C. Wardrobe
A. Table
#. Chair
#. Wardrobe
I. Augustus
#. Nero
#. Caligula
#. Trajan
順序なしのリスト¶
red
yellow
- green
seagreen
verdigris
teal
viridian
- emerald
dark emerald
- light emerald
very light emerald.
blue
このように定義されています:
- red
- yellow
- green
- seagreen
- verdigris
- teal
- viridian
- emerald
- dark emerald
- light emerald
- very light emerald.
- blue
定義リスト¶
お気に入りの機能です！ 定義リストは、例えば Docker のすべてのオプションを列挙し、そこに簡単な説明を追加しようとする場合などに特に便利です。
- Definition
Explanation.
- Another option
Explanation.
- 作成する場合。
このように作成できます:
Definition Explanation. Another option Explanation.
表¶
Purpose |
Table type |
|---|---|
listing shortcuts |
Simple table |
lots of colspans |
Grid table |
Simple but long |
List Table |
以下のようにします:
================== ============
Purpose Table type
================== ============
listing shortcuts Simple table
lots of colspans Grid table
Simple but long List Table
================== ============
+-----------------+------------+
|Purpose |Table Type |
+=================+============+
|listing shortcuts|Simple table|
+-----------------+------------+
|lots of colspans |Grid table |
+-----------------+------------+
|Simple but long |List table |
+-----------------+------------+
.. list-table::
:header-rows: 1
- * Purpose
* Table Type
- * listing shortcuts
* simple table
- * lots of colspans
* grid table
- * simple but long
* list table
完全なグリッド形式の表(grid table)は、複雑な列作成や行の間隔調整などのすべての機能を必要とする場合に最適ですが、作成が容易ではありません。そのため、小さな表は単純な構文(simple table)で処理するのが良いです。表が長くなりそうだったら list-table で処理するのが良いでしょう。これは list-table の方が記述と管理が簡単だからです。
注意事項と補足¶
注釈
注意事項は、読者が注意しなければならない別の項目のようなものです。
使用できる注意事項は次のとおりです(重要度順):
ヒント
ヒントはメインのテキストよりも役立つ情報を少しだけ追加する場合に役立ちます。例えば "これらのパッケージは OpenSuse と Debian では名前が異なります" のような情報です。
Tip
「お気に入りのドキュメント設定のテンプレートを作成できます」や「m キーを使用するとキャンバスを左右反転し、作画のミスをより簡単に確認できます」などの操作方法に関する追加情報に使用します。
重要
重要ですが、必ずしもネガティブではない情報です。
警告
これはネガティブ(目を通しておくことが必要)な情報を示します。
注意
「warning」よりも重要ですが、それほど重要ではない情報に注意を引きたい場合に使用します。
注意
「保存を忘れる」、「現在 Python スクリプト実行時に元に戻す機能がない」など、データ損失を引き起こす可能性がある事項を示すことを目的としています。
危険
This should be for things that are dangerous for the computer in general, this includes things that can cause out of memory style freezes.
エラー
このマニュアルにはおそらく関係しないでしょう。Sphinx はいくつかの状況でこの警告を手動で作成することができますが、現在の構成においてデフォルトでは作成しません。
任意のテキストを含むことができる一般的な警告欄
Text.
このように作成できます:
.. admonition:: Generic admonition that can have any text
Text.
Sphinx ではこのようにも作成できます:
.. seealso::
Which is useful to collect external links and references.
一応、言及しておくと、区切り線は ---- で作成できます。
rubric directive
rubric directive は見出し用の directive (命令)で、一見すると "topic" と同じように見えますが、トピックが複数の段落にわたっている場合、rubric 自体は次のように見出しのみを処理します。
.. rubric:: The rubric directive
どのような場面で使用するか？
見出しを付けるにはテーマの内容が少なすぎると思われる場合にのみ使用してください。
- Topic とする場合
記述したテキストが主題から離れていってしまう場合、それは別の話題として成立するでしょう。
- Rubric とする場合
テキストは主題に沿っているが、見出しは必要ない場合。
- Admonishments とする場合
(「注意事項」の項目で説明している使用場面と)意味的に一致する場合のみ。ユーザは注意喚起の表示を頻繁に見ると必要な情報を見過ごすことがあるため、使いどころが重要です。
Code Snippets¶
Inline code snippets (行内のコードスニペット) は ``backticks (バッククオート)`` で行われます。
複数行のコードスニペットは、前述のテキストの末尾に :: を付加することで作成されます。下記のような形です:
This is a paragraph, and we define a preformated snippet like so::
Be sure to add a white space and a tab afterwards before starting the snippet.
.. code:: を使用することもできます。後ろにプログラミング言語名を追加すると、適切な構文強調表示が行われます。
.. code:: python
# Python comment
def my_function():
alist = []
alist.append(1)
string = "hello world"
下記のように表示されます
# Python comment
def my_function():
alist = []
alist.append(1)
string = "hello world"
他の例も...
// C++ comment
int myFunction(int i) {
i += 1;
// Check if more than 12
if (i>12) {
i = 0;
}
return i;
}
/* CSS comment */
body {
margin: 0 auto;
/* is 800 still sensible? */
max-width:800px;
font-size:16px;
color:#333;
background-color: #eee;
padding:1em;
font-family:serif;
line-height: 1.4;
}
<p>this <span style="font-style:italic">is</span> <!-- a HTML comment --> a paragraph.</p>
その他の整形テキスト¶
このように記載します:
| One can
| preformat
| text by
| prepending
| each line
| with a pipe
| symbol
This is generally not used in the manual, and should only be used where it is absolutely required to represent content that needs exact formatting, but never merely for aesthetic reasons.
用語集、用語および索引¶
これらの機能は Sphinx の特徴です。
索引はページの一番上で使用されますが、現在は単一の索引のみが使用されています。
用語集は、一部のメニュー項目で使用されますが、すべてではありません。
引用¶
引用は次のように記述します:
ユーザマニュアルに引用が必要な理由がわからない…
-- Wolthera
これは引用のための特殊表示になります。
ユーザマニュアルに引用が必要な理由がわからない…
—Wolthera
実際に引用を使用しているページもあります。名前に対してリンクを追加して、名前の由来を定義してみてください。
Text for Non-English Translations Only¶
You can use the following to include text that only makes sense for non-English translations of the manual, for example to provide non-English readers with the English names of an item for reference:
.. only:: non_english
This content is hidden for the English version, but translatable and
shows up in non-English versions.
Notes for Translators¶
If you are translating the manual for a language that does not usually use whitespaces around words (e.g. Chinese and Japanese), you can use an escaped whitespace to separate markup and words. This is particularly useful for page links, like this:
床前\ `明月 <https://krita.org/>`_\ 光
Note that when translating from a PO file, you should escape the backslash with another backslash:
床前\\ `明月 <https://krita.org/>`_\\ 光