Krita 文档写作指南

欢迎参加 Krita 文档的编写工作！

Krita 的文档网站基于 Sphinx 构建。文档以英文版为准，其他语言为英文版的翻译。本文介绍的是英文版的写作方式，但其中的指导思想是各语言共通的。无论是参加编写还是翻译文档，你都应该通读本文。

Krita 的全套文档大致分为下面几个部分：

使用手册/参考手册

使用手册从日常使用的角度出发，按自然步骤介绍使用过程中遇到的功能，相当于按功能分类的教程。参考手册就是 Krita 的“说明书”。它按照软件的界面结构，逐一说明每个功能的用法和选项的含义，便于速查和知识补遗。

数字绘画基础知识

使用手册和参考手册假设读者对数字绘画本身有基本认识。如果用户不只是 Krita 的新手，而是对数字绘画，甚至是绘画本身都一无所知的菜鸟，那么我们就要从数字绘画基础讲起了。这部分的文档会介绍美术、数字影像技术的关键知识，让用户理解各种相关的名词、概念和基本操作流程。这些知识不仅适用于 Krita，也适用于任何数字绘画软件。

Krita 中的某些概念，如色彩管理和滤镜图层等，对于有经验的画师来说不难搞懂，可对于外行人而言却非常抽象复杂。在网上并没有专门面向画师介绍这些知识的教程，因此我们也在这里准备了相关章节。

除此之外，Krita 有许多方面与其他软件有所区别。例如笔刷系统、变形蒙版、透明度继承方式和透视辅助尺等。考虑到许多用户对最基本的数字绘画流程都不熟悉，他们很难拿着一篇面向 SAI 或者 Photoshop 教程，然后把里面的思路套用到 Krita 下面。所以我们也要针对这些方面编写自己的教程。

实例教程

实例教程可以带着用户从头到尾完成一个作品的绘制，以自然直观的方式介绍一个典型绘画流程中要用到的各种工具，对于入门期的用户很有帮助。我们相信每位画师都有自己惯用的独特流程，我们可以鼓励他们在这里分享这些经验。

参与者手册

Krita 是一个自由、开源的软件项目，这意味着我们也是一个由社区推动的项目，有众多志愿者们在为 Krita 的发展贡献力量。对于新加入的志愿者，我们准备了参与者手册来，教会他们如何参与项目工作。要注意的是，Krita 项目的协作是国际性的，除了当地社区工作外，绝大多数情况下需要使用英语交流。参与者手册中有一部分技术性的内容是刻意保留为英语的。

扩展包和第三方教程

把用户提供的各种笔刷包、纹理包、外部教程和视频、Python 插件等在这个分类中列出，方便其他用户利用。

常见问题解答

此页面罗列了可以简单解答的常见问题。它的内容会根据我们收到的社区反馈持续更新。

新手指引

与 Mediawiki 不同，为 Sphinx 编写文档的流程更像是我们为 Krita 编写代码的流程。

首先你要与我们建立联系。你可以通过 Matrix 加入我们的 “#krita” 网络聊天室。先前往 webchat.kde.org 网站并创建一个 Matrix 账户，然后加入 #krita:kde.org 频道。Matrix 的详细使用方式请访问 此页面 。但更重要的是在 KDE Identity 网站 上面创建一个账户，这个账户可以用来访问我们的开发平台：invent.kde.org 和 Phabricator 网站。

Sphinx 文档是通过基于 reStructuredText 标记语言的纯文本编写的。在你贡献的新内容同步后，Sphinx 程序会自动把你编写的纯文本代码转换成网页版手册和电子书。我们通过一个叫做 Git 的版本控制系统来跟踪 Krita 文档的内容变化。

更改内容

在 Git 系统下面，只有部分开发人员有权限向文档源代码的主要分支推送内容。如果你想要对手册内容作出更改，你必须把作出的改动提交审核。

使用网站的 Edit 模式创建合并请求

注解

此方法面向没有 KDE 代码仓库的 push 权限的用户。因为按照我们的代码贡献指导方针，一般用户不应该对代码仓库的内容进行直接更改。

如果你不了解相关技术，请使用此方式进行协作。

不推荐需要同时更改多个文件时使用。（如需更改多个文件，请参见 使用 WebIDE 来创建合并请求 ，如使用每次合并请求编辑一个文件的方式，请参见 通过命令行创建合并请求 ）。

如果你打算对文档进行大量改动，我们建议你按照下述方法进行协作。

1. 注册一个 KDE Identity 账户。

2. 登录到 KDE_gitlab 网站。

3. 访问 repository 页面并点击 fork 。

4. 你会被跳传到你的 fork 所在的代码仓库页面。它通常位于 invent.kde.org/你的 KDE 登录名/docs-krita-org 。

5. 返回官方代码仓库，确保你浏览的是 Documentation > Krita.org Documentation ，而不是你自己的 fork ，否则本方法将不能正确工作。

1. Gitlab 提供了直接在网页中编辑文件的功能。要使用该功能，请前往 Repository ‣ Files 。

2. 在页面靠上方显示了一个选单，它已经选中了 master 。

3. 找到你想要编辑的文件，打开它然后点击 Edit 。

4. 对文件进行更改。(注意：在此模式下你只能每次编辑一个文件)。

5. 转到下方较小的文本框，在 commit message 处将你所做的更改总结为一则简要的描述。填好后，点击 Commit changes 即可创建合并请求，请按照 新建合并请求规范 填写所需字段。

   这个方法有一个缺点，那就是在编辑时不能自动检测并提示 Sphinx 标记的错误。你可以使用 在线 Sphinx 编辑器 ，将编辑后的整段文字粘贴进去，检查是否存在问题。

注意

Edit 和 WebIDE 是完全不同的功能！确保你选中的是 Edit 。

使用 WebIDE 来创建合并请求

如果你略懂 Git ，而且想要同时修改多个文件，我们推荐你使用此方式。

如果你不懂什么叫做 branch ，我们不推荐你使用此方式 (请改用 使用网站的 Edit 模式创建合并请求 方式)。

1. 按照前面介绍过的方法登录 KDE_gitlab 网站，并建立你的 fork 。

2. 前往你的 fork 页面，如前文所述，确保 URL 包含你的用户名。

3. 确保你在 master branch 上。

4. 点击 WebIDE 。这将跳传到一个网页，页面的左侧有一个文件列表，右侧较大的空间用于显示文件的内容。

5. 打开你需要编辑的文件，进行修改。

6. 点击 Commit… 。在 Unstaged changes 分类里双击每个文件，把他们移动到 Staged changes 中去。

7. 再次点击 Commit… ，这将展开一个 commit message 文本框。请填写你修改了什么，并说明原因。

8. 确保设置正确：你必须点击 Create a new branch (branch 名称为： [用户名]/[概括更改内容的短语])。在完成更改后，确保勾选了 Start a new merge request ，否则你事后还要手动创建一个新的合并请求。

9. 点击 Stage & Commit 。

10. 正确填写所有字段：参见 新建合并请求规范 。

11. 如需手动创建一个新的合并请求，请前往 Krita Manual 的官方代码库 (确保 URL 不 包含你的用户名) 并点击 Create a new merge request (左侧的亮绿色按钮)。选择你的 fork，然后选择你在 WebIDE 中创建的 branch 。

注解

如果你不具备在官方代码库中执行 push 的权限，又不小心在官方代码库中进行了编辑，Gitlab 网站不会允许你保存更改 ( Create a merge request 也没有作用：因为你依然需要把你的更改提交到你的 branch ，但如果你不具备 push 权限，你是提交不了的)。页面将显示下述信息： An error occurred whilst committing your changes. Please try again.

在这种情况下，请将你更改过的所有文件的内容复制下来，然后前往你的 fork ，找到同名文件，通过 WebIDE 进行粘贴。

通过命令行创建合并请求

如果你了解 Git 的工作方式，而且能够使用命令行，我们推荐你使用此方式。

如果你不懂什么叫做 branch ，我们不推荐你使用此方式 (请改用 使用网站的 Edit 模式创建合并请求 方式)。

1. 按照前面介绍过的方法登录 KDE_gitlab 网站，并建立你的 fork 。

2. 使用 git clone 把代码库克隆到本地。代码库的页面显示了用于 git clone 的 URL，你可以在之后通过该 URL 将改动 push 回你的 fork。此方式的优点是你可以使用本机的任意工具来编辑这些源文件，也可以在本机手动构建 Krita 文档项目来检查错误。(你只需执行本步骤一次)。

   # 通过 SSH 访问
   git clone [email protected]:<username>/docs-krita-org.git
   git remote add upstream [email protected]:documentation/docs-krita-org.git
   # 通过 HTTPS 访问
   git clone https://invent.kde.org/<username>/docs-krita-org.git
   git remote add upstream https://invent.kde.org/documentation/docs-krita-org.git

3. 每次编辑之前，请务必从官方代码库将其最新改动 pull 到本机：

   git pull upstream master

4. 请确保你更改的内容创建一个新 branch 。自 2019 年起，所有的改动都必须从 master branch 出来。

   git checkout master
   # 然后执行：
   git checkout -b "<用户名>/<新改动内容概括短语>"

5. 在你完成修改后，commit 这些改动，并将它们 push 到你的 fork 中。想要了解如何在命令行中操作 Git 以完成此流程，请参见 Forking on Gitlab 页面。

   # 为本机安装 python3-sphinx 软件包。以 Ubuntu 为例：
   sudo apt install python3-sphinx
   # 构建使用手册 (它将报告可能遇到的错误，并方便在浏览器中检查更改)
   make html
   # 检查所有源代码是否正确
   git status
   git diff
   # 添加所有文件
   git add .
   # commit 你的更改
   git commit
   # push 你的更改到你的 fork
   git push

6. 最后，访问原始代码库的网站，然后访问 Merge Request。选择你的 fork，然后选中正确的 branch ，创建一个新的 merge request 。想要了解如何填写这些字段，请参见 新建合并请求规范 。

新建合并请求规范

1. 请按照： How to Write a Git Commit Message 页面介绍的规范填写 Commit Message 栏。

2. 在 Title 和 Description 栏填写你改动的内容和原因，它们和 commit message 的填写要求是一样的，请按照上面链接内的规范填写。

3. Target 应该指向 master 。

4. 如果你觉得这个 merge request 还要进行修改，请在 merge request 的 title 前方加入 [WIP] 前缀。

5. 确保你选中了 Allow commits from members who can merge to the target branch. 项。这是因为 merge request 经常因为技术原因需要被 rebase 到 master，而这个操作被系统视作对该 merge request 进行了改动 (尽管它的实际内容并未改动)。你本人和审核人都可以 rebase ，所以如果想减少日后的麻烦，请勾选此选项，以便审核人自行完成所需操作。

6. 在大多数情况下，勾选 Delete source branch when merge request is accepted 项是安全的。

7. 除非你的审核人告诉你不要这样做，请勾选 Squash commits when merge request is accepted 。commit message 的第一行来自 merge request 的 Title 栏中填写的内容，其余部分则是 Description 栏中填写的内容。

8. 创建 merge request 后，请访问Krita 的 IRC (参见 互联网中继聊天 (IRC) 页面)，找一位具备 push 权限的开发人员为该 merge request 添加 Needs Review 标签。

9. 如果别人在你的 merge request 中发现了错误，请在你的 branch 下面按下述方式进行订正：

   • 如果你想使用 Edit 模式进行修改，请前往该 merge request 的 Changes 栏目，点击“铅笔”图标 (鼠标悬浮时显示 Edit) 即可进入 Edit 模式。

   • 如果你想使用 WebIDE 模式，请前往你的 fork 页面，选中你的更改所在的 branch，然后进入它的 WebIDE 模式。

   • 如果你想在本机或者通过命令行终端编辑文件，请确保你在正确的 branch 上进行编辑，然后 push 你的更改。Gitlab 会自动更新你的 merge request。

   在进行上述改动后，请记得找人把该 merge request 的标签重新改为 Needs Review 。

想要了解更多信息，请参考 Forking on Gitlab 页面的介绍。

注解

在本文写作期间，只有具备 write 权限的贡献者才可以为官方库的合并请求设置标签。(如果你不知道这是什么意思，你大概也不会有这个权限)。因此，在你创建或更改合并请求后，必须到 IRC 上 (参见 Krita 社区介绍) 找其他人帮你设置标签。

使用命令行模式构建文档

对于那些打算先测试更改再提交合并请求的编写者 (同时懂得如何使用 git 和命令行模式)，请参考 通过命令行创建合并请求 第 5 小节的介绍。

指导思想

任何一篇文章都会表现出一定的文风，它同时体现在文字的实用层面和审美层面。文章的写作目的和作者秉持的指导思想都会对文风造成影响。为了确定 Krita 文档的文风，我们首必须确定文档是写来干什么的，它的读者又是哪些人。

用户群体特性分析

Krita 的用户基数庞大，来自五湖四海、各行各业，我们为拥有如此多样化的用户群体而感到自豪。但也正因如此，我们不能粗暴地将 Krita 的用户群体当成是同一类人。

尽管如此，我们的用户群体还是具有一些共同点：

• 他们都是画师，而画师就是我们要服务的目标人群。

  • 他们喜欢精美的画作。

  • 他们以视觉方式思考。

  • 他们想要创作出精美的画作。

所以，Krita 文档的目标应该是教会用户活用 Krita 的特性去创作出精美的画作。

在上面的基础上，我们还可以对 Krita 的用户群体进一步细分：

• 学生群体，尤其是那些正在尝试各种不同绘画软件的高中生和大学生。他们一般对绘画软件并不陌生，可能已经用过 Paint Tool SAI 或 Photoshop 等软件，但对 Krita 的用法并不熟悉。这个群体的优势在于他们会积极地探讨问题，分享知识，如绘画技巧和教程等。

• 从业人员，这些人使用绘画软件谋生。这个群体的优势是他们具备丰富的行业经验，具备一定的经济能力，更有可能为了 Krita 的发展提供捐款。他们又可以被进一步细分为两类：

  • 非技术性从业人员。这些人不一定能理解软件里面比较数学化的部分，不过他们在长年累月与软件打交道的过程里磨练出了敏锐的直觉，建立了可靠的工作流程。他们大多是画师和负责印刷环节的人员。

  • 技术性从业人员。他们把 Krita 部署在工作流水线的一个环节，往往会更加关注色彩运算的精确性和像素信息的处理方式。他们大多供职于游戏和电影特效行业，但我们有时也会发现科研人员的身影。

• 绘画爱好者，尤其是未经系统培训的成年和老年人。他们不熟悉计算机技术，容易被教程忽略的某个步骤给卡住。相比起欠缺人生经验的学生和无暇探索未知的从业人员，他们的优势是可以从生活实际出发建立一套独辟蹊径的工作流程。他们在社区中还能对浮躁的学生群体起一定的稳定作用。

在这四个群体中，我们可以发现下述情况：

• 只有一个群体熟悉计算机技术。因此我们必须要为其他三个群体撰写数字绘画基础知识章节，让他们可以读懂文档的其他部分。

• 有三个群体很有可能已经使用过别的绘画软件。他们在改用 Krita 时可能需要一些引导，介绍原本熟悉的功能如何在 Krita 中找到/复现。

• 有两个群体需要学习如何配合 Krita 使用其他软件。

• 有两个群体严重缺乏数字绘画的经验和知识，可能需要在最基础的环节开始为他们提供指引。

总结上面的分析，我们可以得出下列写作规范：

文字规范

文档原文以用美式英语为准，中文翻译以标准现代汉语为准

Krita 的界面默认使用美式英语，所以 Krita 的文档以美式英语为准。中文翻译以现代汉语的书面语为准。

避免粗俗，也要避免学究

无论是粗俗的语言还是过于学究的语言，都不是友好的语言。文档就是说明书，它应当以尽可能友好、易懂的方式帮助 Krita 用户，而不是把他们吓跑。

避免使用 GIF 动画

癫痫患者易受快速移动的图像影响而发病。如果非得使用 GIF，或许应该在页面的导入部分对读者进行相关提示。GIF 动图制作起来也很麻烦，而且离线文档被转换为 PDF 后 GIF 动图将失效。这并不是一个硬性要求，我们明白某些情况下动图是最好的说明方式。我们欢迎更多人就此进一步讨论。

让文章便于翻译

这包括在信息图中使用 SVG 图像，为文字选用合适的 Sphinx 标记等。

传统画作和照片使用规范

• 我们不鼓励大家在 Krita 的文档中使用照片和传统画作，除非它们必须被用来解释某种概念。这背后的理由也很简单：使用 Krita 绘制的数字绘画作品多不胜数，又何必非得在 Krita 的界面里祭出伦勃朗的名作进行演示？这搞不好还会被人认为我们在虚假宣传。Pepper & Carrot 漫画是用 Krita 创作的，它们的源文件也是自由、公开的，你可以把它们用作素材。另一方面，Krita 的定位是绘画软件，要是在文档中使用过多照片，会给人一种 Krita 是修图软件的错觉，这并不是我们的目标。

• 当然，我们在介绍某些基础概念时可以用到世界名画或者照片，例如在解释厚涂法和环境光时。在使用世界名画和照片时请为图像配上说明文字。如果是名画，请介绍作品名称和作者。如果是照片，请注明它是一张照片。

• 在照片拼接画法中我们无可避免地要用到照片，在这种情况下允许例外。

图像使用规范

• 避免在图像中直接嵌入文本，尽量使用配图文字。你可以用 figure 标记生成带说明文字的图像。

• 如果必须使用文字，请将图像制作成 SVG 格式以便于日后修改，或者将字数控制在最小限度。

• 文档的配图应该尽可能画得好看，毕竟 Krita 是一款绘画软件。

• 请切记：Krita 的全套文档是在 GFDL 1.3 许可证下发布的，它包含的图像也是如此。如果使用的图像是在 CC-BY-SA/CC-BY 许可证下进行授权的，必须用 figure 标记为它们的作者进行署名。切勿使用那些无法通过上述许可证发布的图像。

写作流程

下面我们会介绍 Krita 文档的写作流程。

标记和分支

Krita 文档的增删作业在 draft branch 中进行。

对已有页面进行的审校将被视作一次缺陷修复，因此它会被 push 到 master branch ，然后再按需 merge 到 draft 分支。

每次 draft branch 被 merge 到一个新正式版文档之前：

• 当前 master branch 会被标记为旧版文档。

• 检查当前 draft branch 是否更新了版本号和新版 epub 封面图。

当前 draft branch 直到新正式版文档发布的前一天才会被 merge ，这是为了尽可能保持全套文档的一致性。

新版的 epub 文件也要随新版文档一起上传。

移除页面

如果 Krita 软件的某项特性在新版中被移除了，它的文档页面要如下处理：

1. 标记相关页面为“已废弃”。

   在文档的源文件中加入以下 Sphinx 标记:

   .. deprecated:: 版本号
       文字说明，告诉用户在失去此特性后该怎么办。

2. 该页面的链接将在“已废弃”页面中列出。

3. 如果 Krita 软件在下一大版本中维持此废弃决定，已废弃章节所链接的页面将会被移除。

新增页面

1. 确保把新页面添加到正确的位置。

2. 按照 Krita 文档 Sphinx 标记使用指南 的规范撰写页面，确保标记格式无误。

3. 将新页面添加到目录。

4. 如果新页面介绍了某项新特性，请将它首次出现的 Krita 版本用 versionadded 进行标记:

   .. versionadded:: 版本号
       可选的文字描述。

与图像的使用规范一样，页面中的文字也必须有合适的授权。文字要么是你的原创作品，要么得到了原作者的许可。Krita 的全套文档在 GFDL 1.3+ 许可证下发布，它所含的所有文字也必须能够在该许可证下重新发布。

修改页面

如果你完全重写了某个页面，而不是单纯地进行审校，你应该将重写后的页面提交审核。

如果你根据软件特性的变化修改了页面内容，而且你拥有 commit 权限，那么你可以直接 push 修改后的页面，无需提交审核 (除非你认为有这个必要)。不过你要在页面中加入以下标记:

.. versionchanged:: 版本号
    说明被改动的内容。

页面顶部的元数据区含有用于记录作者的 author 标签，请自由选择是否加入你的名字。

带有 deprecated、versionadded 或者 versionchanged 等标记和版本号的页面可以通过 grep 命令来进行查找：

grep -d recurse versionadded * --exclude-dir={_build,locale}

报告文档页面缺陷

如果你发现某个页面的内容存在问题，请通过下述方式来进行报告：

• 按照 更改内容 一节的指引创建一个 merge request 。

• 在 Phabricator 网站的 Manual Project Workboard 中创建一个 task 。

• 在 bugzilla 的 Krita 项目的“documentation (文档)”组件处提交程序缺陷报告。

审校工作

我们需要做两种审校工作：一、审核其他人的某次改动；二、审核某个文档页面的整体状况。

第一种，也是平时最主要的审核工作就是 审核其他人的单次改动。你可以在 KDE_gitlab 网站通过下述两种方式对改动进行审核：

1. 审核其他人提交的 merge request

   你可以协助审核人们提交的 merge request。merge request 审核的初衷是让程序员可以互相发现代码中的错误。Krita 文档的源文件和程序的源代码一样是纯文本，所以我们可以像程序员那样来检查 Krita 文档中存在的问题。

   一个 merge request 记录了某个文件发生的全部变化 (包括内容的增删)，它被保存为计算机能够读取的格式。 当有人提交了一个 merge request (在 gitlab 和 github 系统里叫做 merge 或者 pull request) 时，负责维护原始文件的人员要检查发生的改动。如果这些改动需要进一步修改，他们还要为此撰写评语，如拼写错误、文风不端，信息错误等。一个 merge request 的 patch 只有在被审核人员接受后，才可以被 push 到 Krita 文档源代码库对应的 branch 中。

2. 给 Krita 文档的改动撰写评语

   这里指的是在文档改动被提交后撰写的评语。请前往某次文档改动的 commit message (在 repository 页面，前往 history 然后点击其中一项)，在那里你可以针对此次改动撰写评语。

在上述两种情况中，网站的界面都会显示修改前后版本的区别。左栏显示旧版内容，右栏显示新版内容。新增的行标记为绿色，被删除的行显示成红色。你可以点击对话泡泡图标，添加一条内联评语。

第二种审校工作是 针对整个页面 进行的。一个页面没有检查出拼写和语法错误，不代表它的文字就一定流畅，文风就一定合适。整体审校可以改进这些问题。

要进行整页审校，请参考 更改内容 一节的说明，获取页面的完整访问权限以进行编辑。

翻译工作

Krita 是 KDE 社区 的一个子项目，它的翻译是各种语言的 KDE 本地化小组 组织进行的。要参加 Krita 的中文翻译工作，请访问 Krita 中文翻译参与指南 页面。你也可以加入 Krita 的开发团队，指出或者改正那些妨碍翻译工作的代码，让 Krita 项目的文字在任何一种语言下面都能保持自然流畅。

KDE 本地化小组成员有权限访问 Krita 文档的 PO 文件。PO 文件是一种专门用于翻译的文件格式，可用 POEdit 和 Lokalize 等程序打开。各个本地化小组的任务是翻译这些 PO 文件，然后上传至 KDE Translation 项目的 SVN 系统。SVN 配有专门的脚本，它每天都会将最新的 PO 文件同步到 Krita 的文档网站。

图像也是可以被翻译的，但翻译人员必须自行制作翻译后的图像版本。在 Krita 文档源文件的 image 文件夹中，所有图像的语言都默认为“en”(英语)。如果你要翻译某张图像，请在 image 文件夹中添加一个以你的语言代码命名的文件夹 (简体中文为 zh_CN)，然后把翻译后的图像文件放到里面。例如：Sphinx 会把 /images/Pixels-brushstroke.png 的荷语版本定位到 /images/nl/Pixels-brushstroke.png ；把 /images/dockers/Krita-tutorial2-I.1-2.png 的荷语版本定位到 /images/dockers/nl/Krita-tutorial2-I.1-2.png 。

翻译的成果还需要被添加到编译脚本，完成编译后才能在网上显示。如果某个本地化小组需要编译他们的最新翻译，请通过 kimageshop 邮件列表 (kimageshop@kde.org) 或者电邮地址 foundation@krita.org 联系 Krita 核心团队协助处理。

更多信息

如需了解 restructured 标记的使用范例，请查阅 Krita 文档 Sphinx 标记使用指南 。