Krita 文档 Sphinx 标记使用指南

Krita 文档 Sphinx 标记使用指南

Krita 当前的文档系统是 Sphinx，它使用一种基于 reStructuredText 的简易标记语言来控制格式。本页面对 Krita 文档中经常出现的标记的使用方式进行介绍。

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

使用手册

参考文档

Sphinx 专用文档

Sphinx 的 restructured 标记用法说明文档 – 该文档介绍了如何使用 Sphinx 标记生成诸如目录等元素的特定指令和角色。

reStructuredText 的官方版本和 Sphinx 实际使用的标记略有差异。本页面将介绍 Krita 文档网站建议使用的规则。

Krita 文档 Sphinx 标记使用指南

元数据

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

元描述

这是对于该页面内容的概述，它的内容会被转换成一组 html 元标记，以供搜索引擎抓取:
```
.. meta::
    :description:
        描述文字。
```
作者列表和许可证

用于记录哪些人编辑过该页面并对他们的贡献进行声明。最好把它注释掉，以避免被机器人读取。Krita 文档网站的所有页面均使用 GFDL 1.3 许可证，所以我们也要在此对许可证进行声明:
```
.. metadata-placeholder
   :authors: - 作者 1
             - 作者 2
   :license: GNU free documentation license 1.3 or later.
```
索引关键词

关键词以半角逗号进行区分。页面会在索引处按照这些关键词进行排列。手册自动生成的索引对于 PDF 和不了解内容关键词的人们来说非常有用。关键词的定义方式如下:
```
.. index:: 关键词, 含 空 格 关 键 词, ! 主要定义关键词
```
链接代号

你可以在其他页面插入 :ref:`链接代号` 标记，生成一个内部链接到此页面。请尽量使用易于理解的链接代号:
```
.. _链接代号 (必须以英语和下划线组成):
```
除链接代号外，你还要建立一个页面标题。使用 :ref:`链接代号` 标记插入的链接将会使用页面标题显示链接文字。

标题

各级标题可以使用下列标记生成:

############
子页面标题
############
用于具有大量子页面的页面。
=========
一级标题
=========
如无特殊情况，文档页面一律以一级标题开头。
二级标题
---------
三级标题
~~~~~~~~~
四级标题
^^^^^^^^^
五级标题
'''''''''
六级标题
"""""""""

上述标记参考了 Pandoc 将 Mediakiwi 页面转换为 reStructuredText 时的处理方式。为避免页面排版混乱，不建议在同一页中使用超过四级标题。如果内容层级过于复杂，建议将页面拆分成多页。

如需创建内部链接到页面的某个章节，请在该章节标题之前添加链接代号。

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

内部链接通过 :ref:`链接代号` 生成。如需获取某个页面的链接代号，请点击页面右上角的 </> 显示页面源代码，在开头附近找到以 _ 作为开头和空格的一串文字，在第一个 _ 和 : 之间的部分便是该页面的链接代号。如需把链接显示成自定义文字，则使用 :ref:`实际显示的文字 <链接代号>` 。请留意：实际显示的文字和<链接代号>之间必须保留一个半角空格，否则内链将失效。这些标记和相邻文字必须以半角空格隔开，否则将会破坏排版。

外部链接通过 `网址`_ 和 `链接名称 <网址>`_ 生成，它们的显示效果如下：链接名称。这些标记和相邻文字必须以半角空格隔开，否则将会破坏排版。

Pandoc 喜欢把这些上述要素改成 `链接名称`__ 然后添加 .. __ :url 到文档末尾。这便是所谓的 ‘匿名超链接’，它们在文档末尾的先后顺序取决于链接本身在文中出现的先后顺序，文末链接的排序也因此相互关联。如果你觉得这很难理解，你并没有错。这也是为什么我们希望避免使用类似的链接。

脚注和延伸阅读

脚注可以通过三种方式生成，最常用的是自动编号的引用标记，示例如下：[#]_ 可在文中插入脚注编号，.. [#] 脚注内容 可在文中插入脚注的实际内容。实际显示效果如下：

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

这是脚注 1。

这是脚注 2。

这是脚注 3。

3 是对脚注 3 的引用。

[引用标题]_ 可以在文中插入带标题的引用， .. [引用标题] 引用文字内容 可以在文中插入实际引用的内容。实际效果如下：这是一处引文：[CIT2002] 。

CIT2002

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

引文还可以通过如下方式： `citation <CIT2002>`_ 进行引用。

我们不在 Krita 文档中使用脚注，因为作为说明书，脚注不但没有意义，还造成阅读不便。我们可以在页面末尾插入一些相关的内部/外部链接，用于延伸介绍相关知识。Sphinx 用 .. seealso:: 指令来生成外部链接，而 reStructuredText 为了兼容 LaTex 而建议使用 .. rubic:: Footnotes 来收集脚注。

图像

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

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

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

.. figure:: /images/sample.png
   :figwidth: 800
   :align: center
   :alt: 此处填入图像替代文字。
   说明文字 --  注意：说明文字的第一个字母按照图像的 :figwidth: 选项数值对齐。

后者生成的图像/说明文字效果如下：

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

图像应该上传到 /images 文件夹。标记中的链接应使用 /images 而不是 images，这样 Sphinx 才会把它视作绝对路径。

文字格式标记

在一段文字前后各插入一个半角星号可以生成斜体，在一段文字的前后插入两个半角星号可以生成粗体。请注意：切勿在星号和内部文字之间插入半角空格，务必在星号和外部文字之间插入半角空格，否则文字格式将不正常。在翻译时避免把中文标为斜体，如果原文使用了斜体，可以考虑使用中文引号或者粗体代替。标记用法如下:

*斜体*
**粗体**

你只能在斜体和粗体之间二选一。三个星号不会生成加粗斜体。

用 :sub:`下标文字` 可以生成下标文字，而用 :sup:`上标文字` 则可以生成上标文字。

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

:menuselection:`设置 --> 配置 Krita (菜单点击序列标记)`
:guilabel:`文件 (界面元素标记)`
:kbd:`Ctrl + Z (按键标记)`
:program:`Krita (程序名称标记)`

使用加粗应有所节制，否则会把排版变得乱七八糟。

置换标记

你可以使用短代码标记来插入需要反复使用的复杂内容:

.. |短代码标记| replace:: 短代码标记的实际内容。

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

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

.. _bugzilla: https://bugs.kde.org/
.. _Krita 使用手册: https://docs.krita.org/

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

列表

有序列表

苹果
梨子
香蕉

或者

桌子
椅子
衣柜
奥古斯都
尼禄
卡利古拉
图拉真

以上列表的对应标记如下:

1. 苹果
2. 梨子
3. 香蕉
#. 苹果
#. 梨子
#. 香蕉
A. 桌子
B. 椅子
C. 柜子
A. 桌子
#. 椅子
#. 柜子
I. 奥古斯都
#. 尼禄
#. 卡利古拉
#. 图拉真

无序列表

红
黄
绿色
- 海绿
- 铜绿
- 鸭绿
- 鲜绿
- 祖母绿
  - 深祖母绿
  - 浅祖母绿
    - 极浅祖母绿

上述列表的标记如下:

- 红
- 黄
- 绿
    - 海绿
    - 铜绿
    - 鸭绿
    - 鲜绿
    - 祖母绿
        - 深祖母绿
        - 浅祖母绿
            - 极浅祖母绿
- 蓝

名词定义列表

名词定义列表适合罗列一系列相关选项，并逐个进行介绍。Krita 文档经常使用它们。

定义名称

说明文字。

另一个定义名称

说明文字。

如何生成定义列表

上述名词定义列表的标记如下:

定义名称
     说明文字。
另一个定义名称
    说明文字。

表格

用途	表格类型
列举快捷键	简单型
单元格跨行跨列	网格型
结构简单但超长	列表型

上述表格的简单型、网格型、列表型标记如下:

================== ============
用途                表格类型
================== ============
列举快捷键           简单型
单元格跨行跨列　      网格型
结构简单但超长　      列表型
================== ============
+-----------------+------------+
|用途　            |表格类型　　  |
+=================+============+
|列举快捷键　       |简单型       |
+-----------------+------------+
|单元格跨行跨列　　  |网格型       |
+-----------------+------------+
|结构简单但超长　　  |列表型       |
+-----------------+------------+
.. list-table::
   :header-rows: 1
   - * 用途
     * 表格类型
   - * 列举快捷键
     * 简单型
   - * 单元格跨行跨列
     * 网格型
   - * 结构简单但超长
     * 列表型

完整的网格型表格虽然可以应付复杂的跨行跨列，但制作起来相当费劲，所以小型表格最好使用简单型表格标记。如果是非常长的单列表格，还不如直接用列表标记代替，省时省力。

信息框

注解

需要引起读者注意的文字，可使用信息框。本信息框为“注解 (note 标记)”。

信息框有还下面几种 (按照严重程度排列)：

提示

“提示 (hint 标记)”可以用来在正文之外补充少量信息。例如，提示：这些软件包在 OpenSUSE 和 Debian 中使用不同的名字。

小技巧

“小技巧 (tip 标记)”可以用来介绍一些额外的使用技巧，例如：“你可以为你习惯的文档设定制作一个模板”，或者“按下 M 可以水平翻转画布视图以便发现画面的问题”。

重要

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

警告

“警告 (warning 标记)”一般在描述负面信息时使用。

注意

“注意 (attention 标记)”可以用来标注那些比“警告”更严重，但又不至于造成数据损失的事项时使用。

小心

“小心 (caution 标记，Sphinx 的中文翻译误作‘警告’)”信息用于标注可能会造成数据损失的情况，例如提示读者不要忘记保存文件，或者让读者当心 Python 插件进行的操作目前无法撤销等事项。

危险

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

错误

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

自定义信息框

示例文字。

上述自定义信息框的标记如下:

.. admonition:: 自定义信息框
    示例文字。

在 Sphinx 中，“参见”信息也是信息框的一种:

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

水平线

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

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

单独标题标记

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

.. rubric:: 单独标题标记

如何选用标题类标记

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

章节标题

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

单独标题

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

信息框

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

代码片段

正文中出现的代码片段可用 ``代码片段`` 标签生成。

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

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

你也可以使用 .. 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>

手动断行

你可以

手动断行

文字

只需在

每行文字的前面

加一条竖线

和一个空格

做法如下:

| 你可以
| 预格式化
| 文本
| 只需在
| 每行之前
| 加一条竖线
| 和一个空格

此格式标识一般不建议在文档中使用。仅在特殊情况下出于实用理由必须如此排版时才应该使用，不应为了排版美观使用。

词汇表、术语和索引

这些都是 Sphinx 提供的特性。

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

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

引用

引用通过下述方式生成:

我搞不懂为什么在使用手册里需要引用...
-- Wolthera

它会变成下面的引用文字：

我搞不懂为什么在使用手册里需要引用…

—Wolthera

但如果我们真的在文章里面引用了别人的发言，最好把发言人名字制作成链接，跳传到引用文字的出处。