22.4.4 简介和描述

我们已经看到，GNU Guix里的每个软件包都包含一个简介（synopsis）和一个描述（description）（see 定义软件包）。简介和描述很重要：它们是guix package --search搜索的信息，并且是帮助用户决定一个软件包是否符合自己需求的重要信息。因此，打包的人应该关注怎样写它们的内容。

简介必须以大写字母开头，并且不能以句号结尾。它们不能以 “a” 或者 “the” 等没有意义的词开头。例如 “File-frobbing tool” 要比 “A tool that frobs files” 更好。简介需要说明软件包是什么－－如 “Core GNU utilities (file, text, shell)”，或者它的用途－－如 GNU grep 的简介是 “Print lines matching a pattern”。

记住，简介必须能被广大的听众理解。例如，“以SAM格式修改对齐”可能对经验丰富的生物信息科研工作者来说能理解，但是对普通对听众则是无用的甚至是令人误解的。简介最好说明软件包应用的领域。在这个例子中，应该这样描述“修改核苷酸序列的对齐格式”，这会让用户更容易判断这是不是他们想要的。

描述应该在5至10句话之间。使用完整的句子，并且避免在未介绍的情况下使用缩写。请避免推广营销性对词汇，如“世界领先”，“行业最强”，“下一代”，并且避免高级的形容词，如“最先进的”–他们对用户寻找软件包是无用的，甚至是可疑的。相反的，尽量务实，提及用例和功能。

Descriptions can include Texinfo markup, which is useful to introduce ornaments such as @code or @dfn, bullet lists, or hyperlinks (see Overview in GNU Texinfo). However you should be careful when using some characters for example ‘@’ and curly braces which are the basic special characters in Texinfo (see Special Characters in GNU Texinfo). User interfaces such as guix show take care of rendering it appropriately.

Synopses and descriptions are translated by volunteers at Weblate so that as many users as possible can read them in their native language. User interfaces search them and display them in the language specified by the current locale.

为了让xgettext可以把它们提取成待翻译的字符串，简介和描述必须是文字字符串。这意味着你不能使用string-append或format来合成字符串：

(package
  ;; …
  (synopsis "这是可以翻译的")
  (description (string-append "这是" "*不可以*" "翻译的")))

翻译是很繁重的工作，所以，作为打包者请更加注意你的简介和介绍，每一个改动都会增加翻译的工作量。为了帮助他们，你可以插入这类可以被他们看到的建议和指示（see xgettext Invocation in GNU Gettext）：

;; TRANSLATORS: "X11 resize-and-rotate"不需要翻译。
(description "ARandR为X11 resize-and-rotate (RandR)扩展提供简单的图形界面。…")