Krita 手册标记语言使用指引

本文详细介绍了如何在 Krita 手册中使用 reStructuredText 标记语言。

我们建议参与文档编写和翻译的人员认真阅读 reStructuredText 项目的 官方规范 。该项目在 sourceforge 上面运作，它的服务器不太稳定，可以把该文档保存一份到本地以便日后查阅 )：

用户手册

参考文档

Sphinx 专用文档

由于官方版本的 reStructuredText 和 Sphinx 的文档描述的用法存在差异。本文档会统一介绍我们建议遵循的惯例。

目录

元数据

每个页面起始部分都应该包括下列 4 种要素：

  1. 元描述

    这是对于该页面内容的概述，它的内容会被转换成一组 html meta 标记，方便搜索引擎抓取:

    1. .. meta::
    2.     :description:
    3.         描述文字。

  2. 作者列表和许可证

    用于记录哪些人编辑过该页面并对他们的贡献进行声明。最好把此处标记为注解文本，以免被机器轻易理解。我们的整个手册均使用 GDL 1.3 许可证，所以我们也要在这里对许可证进行声明:

    1. .. metadata-placeholder
    3.    :authors: - 作者 1
    4.              - 作者 2
    5.    :license: GNU free documentation license 1.3 or later.

  3. 索引关键词

    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:

    1. .. index:: 关键词, 带有 空 格 的关键词, ! 主要定义关键词

  4. 标签变量

    标签变量会被 :ref:`label_name` 标记生成的页面链接所使用。请尽量构思简明易懂的变量名:

    1. .. _标签名称 (英语):

    在添加标签变量之后，你还要为页面添加一个标题， :ref:`label_name` 将使用页面的标题文字作为链接显示的文字。

标题

各个级别的标题通过以下顺序生成:

  1. ############
  2. 部分/章节
  3. ############
  5. 用于有许多子页面的页面。
  7. =========
  8. 一级标题
  9. =========
  11. 绝大多数使用手册页面以此类标题开始。
  13. 二级标题
  14. ---------
  16. 三级标题
  17. ~~~~~~~~~
  19. 四级标题
  20. ^^^^^^^^^
  22. 五级标题
  23. '''''''''
  25. 六级标题
  26. """""""""

These conventions were more or less decided by Pandoc’s mediawiki to reStructuredText conversion. If you need more than 4 headings, ask yourself first if the page hasn’t gotten too complicated and needs splitting up.

如需创建链接到页面的内部章节，可在目标章节的标题前面添加一个标签变量。

标题文字不应该以标点结尾，因为它会在生成链接时被用作链接文字。

链接

链接通过 :ref:`label_name` 生成。如需把链接显示成自定义文字，则使用 :ref:`实际显示的文字 <label_name>` 。务必在“label_name”括号的前面保留一个半角空格，否则会把整个页面的代码搞乱！

外部链接通过 `url`_ 和 `链接名称 <url>`_ 生成，它们会被如下显示： 链接名称 。相邻文字和这些链接的代码之间必须保留一个空格，否则整个页面的代码会乱掉！

Pandoc likes to turn these into `link name`__ and then add .. __ :url at the end of the document. This is a so-called ‘anonymous hyperlink’, meaning that depending on the order of the links appearing in the text the order of the links at the end of the text are associated with one another. If this sounds confusing and difficult, it is because it is. That is also the exact reason why we’d like to avoid links like these.

脚注和延伸阅读

脚注可以通过三种方式生成，最常用的是自动编号的引用，示例如下：

1 是对脚注 1 的引用，而 2 则是对脚注 2 的引用。

1

这是脚注 1。

2

这是脚注 2。

3

这是脚注 3。

3 是对脚注 3 的引用。

这是一处引文：[CIT2002] 。

CIT2002

这是引文本身。它和脚注类似，但标签是文本串。

Citation can also be referenced with `citation <CIT2002>`_.

我们在手册中并未使用脚注功能，因为我们觉得这太学术化了。不过我们依然会整理一些相关的文档和链接在页面的末尾列出，用于进一步介绍某些事物。Sphinx 用 .. seealso:: 指令来生成外部链接，而 reStructuredText 为了兼容 LaTex 而建议使用 .. rubic:: Footnotes 来收集脚注。

图像

使用 image 标记可以生成不带说明文字的图像:

  1. .. image:: /images/sample.png
  2.    :width: 800
  3.    :align: center
  4.    :alt: 此处填入图像替代文字。上面的 center 表示居中。

使用 figure 标记可以生成带有说明文字的图像:

  1. .. figure:: /images/sample.png
  2.    :figwidth: 800
  3.    :align: center
  4.    :alt: 此处填入图像替代文字。上面的 center 表示居中。
  6.    说明文字 --  注意说明文字的第一个字母按照图像的 :figwidth: 选项数值对齐。

后一个标记生成的效果如下：

an image.

说明文字——在标记中，说明文字中的第一个字符是按照“:figwidth:”参数进行对齐的。

图像应该上传到 /images 文件夹。使用 /images 而不是 images，这样 Sphinx 就不会把它作为相对路径进行解释了。

文字标记

在一段文字前后各插入一个半角星号可以生成 斜体 ，在一段文字的前后插入两个半角星号可以生成 粗体 。务必留意在星号和内部文字之间 不可以 插入空格，而星号和外部文字之间却 一定要 插入空格，否则整个页面的排版会乱掉。应尽量避免把中文标为斜体，如果原文使用了斜体，可以考虑使用中文引号或者粗体代替。

  1. *斜体*
  2. **粗体**

在一段文本的前后插入三个半角星号是行不通的，你只能在斜体和粗体之间二选一。

You can subscript text and superscript text by using :sub:`text` and :sup:`text` .

切勿滥用文字标记。尽量使用 Sphinx 提供的语义标记，因为它们可以帮助翻译人员理解文本的性质，这些标记包括:

  1. :menuselection:`Settings --> Configure Krita...`
  2. :guilabel:`File`
  3. :kbd:`Ctrl + Z`
  4. :program:`Krita`

不要胡乱加粗文字。那样会把文字变得难以阅读。

置换标记

你可以用以下方式为文字或图像创建速记标签:

  1. .. |速记标签| replace:: 被替换的内容。

如果你在文字中插入 |速记标签|，它会被显示成“该速记标签所代表的内容”。这对于那些会被反复使用的格式繁琐的图像和文字很有用，例如使用了 LaTeX 的情况。

Krita 文档定义了 |mouseleft|、|mousemiddle|、|mousescroll| 和 |mouseright|，它们会被置换为 mouseleft、mousemiddle、mousescroll 和 mouseright 。它们通过 Sphinx 的 conf.py 文件进行定义，然后被附加在每个 rst 文件里面。

对于链接来说，如果需要反复使用同一个链接，你可以在文件的末尾编写类似下面的代码:

  1. .. _bugzilla: https://bugs.kde.org/
  2. .. _Krita 使用说明: https://docs.krita.org/

这样日后在需要插入链接的时候，你只需使用 `bugzilla`_ 即可生成一个文字显示为“bugzilla”，跳传到 bugzilla 的链接。`Krita 使用说明`_ 则会生成一个叫做 “Krita 使用说明” 的超链接并跳传到 docs.krita.org 。

列表

有序列表

  1. 苹果

  2. 梨子

  3. 香蕉

或者

  1. 桌子

  2. 椅子

  3. 衣柜

  4. 奥古斯都

  5. 尼禄

  6. 卡利古拉

  7. 图拉真

它们的用法是:

  1. 1. 苹果
  2. 2. 梨子
  3. 3. 香蕉
  5. #. 苹果
  6. #. 梨子
  7. #. 香蕉
  9. A. 桌子
  10. B. 椅子
  11. C. 柜子
  13. A. 桌子
  14. #. 椅子
  15. #. 柜子
  17. I. 奥古斯都
  18. #. 尼禄
  19. #. 卡利古拉
  20. #. 特洛伊

无序列表

  • 红

  • 黄

  • 绿色

    • 海绿

    • 铜绿

    • 鸭绿

    • viridian

    • 祖母绿

      • 深祖母绿

      • 浅祖母绿

        • 极浅祖母绿
  • 蓝

用法如下:

  1. - red
  2. - yellow
  3. - green
  4.     - seagreen
  5.     - verdigris
  6.     - teal
  7.     - viridian
  8.     - emerald
  9.         - dark emerald
  10.         - light emerald
  11.             - very light emerald.
  12. - blue

定义列表

它们在罗列某个工具面板的各个选项并逐个进行说明时特别好用。我们特别喜欢使用定义列表。

定义名称

说明文字。

另一个定义名称

说明文字。

如何生成定义列表。

方法如下:

  1. Definition
  2.     Explanation.
  3. Another option
  4.     Explanation.

表格

用途

表格类型

列举快捷键

简单型

单元格跨行跨列

网格型

结构简单但超长

列表型

用法如下:

  1. ================== ============
  2. 用途                表格类型
  3. ================== ============
  4. 列举快捷键           简单型
  5. 单元格跨行跨列　      网格型
  6. 结构简单但超长　      列表型
  7. ================== ============
  9. +-----------------+------------+
  10. |用途　            |表格类型　　  |
  11. +=================+============+
  12. |列举快捷键　       |简单型       |
  13. +-----------------+------------+
  14. |单元格跨行跨列　　  |网格型       |
  15. +-----------------+------------+
  16. |结构简单但超长　　  |列表型       |
  17. +-----------------+------------+
  19. .. list-table::
  20.    :header-rows: 1
  22.    - * 用途
  23.      * 表格类型
  24.    - * 列举快捷键
  25.      * 简单型
  26.    - * 单元格跨行跨列
  27.      * 网格型
  28.    - * 结构简单但超长
  29.      * 列表型

完整的网格型表格虽然可以应付复杂的跨行跨列，但却不好制作，所以小型表格最好使用简单型表格的句法。如果是非常长的单列表格，还不如直接用列表标记代替，这样编写和修改都省时省力。

注解和警告信息框

注解

“注解”是一种用来吸引读者注意的独立段落。

我们可以使用下列警告文字 (按照严重程度排列)：

提示

Hints are useful to give a little bit more information on a topic than is useful in the main text. Like, “These packages are named differently in openSuse versus Debian”.

小技巧

Extra information on how to do something, like, “You can make a template of your favourite document setup”, or “Use m to mirror the canvas and see errors more easily in your drawing”.

重要

“重点”可以用来强调一些需要留意的信息，但并不一定是负面的信息。

警告

“警告”一般在描述负面信息时使用。

注意

“注意”可以用来标注那些比“注解”更为重要，但又不至于造成数据损失的事项时使用。

小心

This is for things that could cause dataloss, like forgetting to save, or that Python currently has no undo functionality.

危险

“危险”信息用于标注那些危及计算机整体运行的情况，包括那些导致内存不足死机的操作等。

错误

“错误”信息与手册本身内容无关，Sphinx 在某些情况下会生成这种信息，但我们的配置文件默认没有开启这一功能。

Generic admonition that can have any text

Text.

You can make it like this:

  1. .. admonition:: Generic admonition that can have any text
  3.     Text.

Sphinx 还把“参见”信息作为为此类信息框的一种看待:

  1. .. seealso::
  3.     方便用于集中列出外部链接和参考资料。

水平线

水平线通常用于正文话题发生突然变化的场合。它在叙述性的写作中较为常见，如纪实或小说等。Krita 的使用手册主要采用说明文的写作风格，不会为了介绍一项功能而长篇大论。但有的时候为了交待设计思路，我们可能会展开讲述事情的来龙去脉。在本文档中，如果话题需要发生切换，那么最好另起章节。我们建议尽量使用 .. Topic:: 标记，它生成的标题也会让文章更易于阅读。

上面的便是一条水平线。如需插入一条水平线，使用 ---- 即可。

The rubric directive

单独标题标记可以生成看上去和“章节标题”一样的标题文字。一个章节标题代表了整个章节和它里面的各个段落，而单独标题标记只管生成标题文字本身。它的用法如下:

  1. .. rubric:: The rubric directive

如何选用标题类标记

一般来说应该尽量使用章节，只有在你认为该段文字的重要性不足以作为单独章节时才使用其他的标题类标记。

章节

当文字讨论的话题发生了明显变化，无法跟之前的段落归为同一章时，可以另起一章。

单独标题

当文字讨论的内容依然属于当前章节的一部分，虽然需要给它安排一个标题但用不着给它指定一个正式章节时使用。

注解信息框

信息框的使用要谨慎，只应在文章非常需要对应的信息框时才偶尔使用，尤其是危险和警告类的信息框。如果信息框出现得太频繁，不但页面显得凌乱，读者也会对它们感到麻木。

代码片段

行内代码片段 可用 ``半角反引号`` 生成。

要生成多行代码片段，将前一个段落以 :: 结尾:

  1. 这是一个代码片段，要定义一段预先格式化的代码片段，可以使用::
  3.     记得要在代码片段开始之前插入一个空格和一个 tab 占位符。

你也可以使用 .. code:: 标记。如果你在标记后面注明计算机语言名称，它还可以按此进行语法高亮:

  1. .. code:: python
  3.     # Python comment
  4.     def my_function():
  5.         alist = []
  6.         alist.append(1)
  7.         string = "hello world"

显示为

  1. # Python comment
  2. def my_function():
  3.     alist = []
  4.     alist.append(1)
  5.     string = "hello world"

其他例子

  1. // C++ comment
  2. int myFunction(int i) {
  3.     i += 1;
  5.     // Check if more than 12
  6.     if (i>12) {
  7.         i = 0;
  8.     }
  9.     return i;
  10. }
  1. /* CSS comment */
  2. body {
  3.     margin: 0 auto;
  4.     /* is 800 still sensible? */
  5.     max-width:800px;
  6.     font-size:16px;
  7.     color:#333;
  8.     background-color: #eee;
  9.     padding:1em;
  10.     font-family:serif;
  11.     line-height: 1.4;
  12. }
  1. <p>this <span style="font-style:italic">is</span> <!-- a HTML comment --> a paragraph.</p>

手动断行

你可以

手动断行

文字

只需在

每行文字的前面

插入一个竖线

符号

做法如下:

  1. | 你可以
  2. | 预格式化
  3. | 文本
  4. | 只需在
  5. | 每行之前
  6. | 加一个竖线
  7. | 符号

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 提供的特性。

索引被显示在页面顶部，目前仅使用单一索引项。

词汇表被用于处理某些菜单项的章节，但并非每个菜单项都这样处理。

引用

引用通过下述方式生成:

  1. 我搞不懂为什么在用户手册里要使用引用...
  3. -- 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:

  1. .. only:: non_english
  3.     This content is hidden for the English version, but translatable and
  4.     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:

  1. 床前\ `明月 <https://krita.org/>`_\ 光

Note that when translating from a PO file, you should escape the backslash with another backslash:

  1. 床前\\ `明月 <https://krita.org/>`_\\ 光

The above produces “床前明月光”, instead of “床前 明月 光”.