openSUSE:软件包描述指南

跳转到：导航，搜索

摘要

  • 摘要应该对软件包的简短而简洁的描述，基本上回答“它是什么？” 因此，它不应该是一个动词短语（“它做什么”，❌ "计算复杂的数学运算”），而应该是一个名词短语 (⭕ "用于计算复杂数学运算的程序/库/模块等" 或 "复杂的数学运算工具")
  • 它应该适用于所有标准情况，并且不假设任何特殊上下文。
  • 它应该单独使用时有帮助，在按字母顺序或无序排列的某些选定软件包列表中，以及在按字母顺序或无序排列的所有软件包列表中。
    • 这意味着，例如，“客户端库”或“开发所必需的文件”作为摘要是不够的，因为什么客户端，什么开发？
  • 它应该描述软件包的主要功能，并指出软件包的任何特殊属性，以帮助用户比较类似的软件包。 例如，这两个词“Web 浏览器”总结了任何 Web 浏览器，添加更详细的信息（例如：基于文本的 Web 浏览器、仅键盘导航的浏览器等）有助于描述特定的软件包。
  • 它不应该以句点结尾。 如果这让你从语法角度感到困扰，请坐下来，深呼吸，克服它。


  • 要简洁。 避免使用“免费”、“开放”、“开源”、“用于 (GNU/)Linux”等填充词。 openSUSE 中的所有内容（极少数例外）已经具有所有这些属性，因此无需在每个软件包的描述中重复说明。
  • 确保相关性。 提及软件包跨平台或在非 openSUSE 目标（如 Windows、MacOS 等）上运行没有意义。
  • 确保中立的观点，并避免使用“快速”、“现代”、“简单”、“强大”等煽动性词语。 描述（和摘要）不是广告，并且这些属性的真实性可能存在疑问。（有关详细列表，请参阅下面的部分。）

这些要点中的一些也适用于摘要和描述。

描述

描述扩展了摘要。 尝试回答软件的作用以及为什么有人需要或想要该软件包。 小心不要逐字复制来自其他地方的描述，因为它们可能存在偏差、包含错误或对 openSUSE 不必要的措辞。 如果有疑问，请用你自己的话来说。

  • 避免提及无关紧要的事情
    • 项目目标/愿景：重要的是软件包可以做什么，以及它现在做什么。 它在未来某个时间想要做什么的目标和愿景对用户当前没有帮助。
    • 可移植性：该程序也适用于其他平台并不重要。 用户在 openSUSE 的上下文中查看该软件包。
    • 无意义/冗余的词语
    • 推荐信
  • 不要在描述中包含安装说明；它不是手册。 如果软件包需要手动配置或对用户有其他重要说明，请将用户推荐到软件包中的文档。 如果您认为有必要，请添加一个README.SUSE 或类似的文件。
  • 描述的理想大小范围在 160 到 700 个字符之间。 （那个上限相当于纯散文的 9 行块，或者大约 15 行，如果你考虑散文和项目符号列表的混合。）
  • 软件的作者信息不属于描述。

软件包描述应该帮助用户决定为预期目的选择正确的软件包，而无需先测试其他类似的软件包。 描述是告知用户有关软件包功能的更精确信息的正确位置。 它应该包含有关功能和与其他可比较软件包之间差异的更多信息。 如果软件包可能会损害用户的安装，则描述应包含有关其潜在风险或副作用的明确说明。

即使 YaST2 的 Qt 和 ncurses 前端都知道如何自动将描述文本转换为 HTML 然后将其包装以进行显示，也要考虑人们将使用各种编辑器来编辑 .spec 文件本身，并且更喜欢不要处理非常长的行，因此请考虑将其包装到与虚线相同的宽度（66 个字符）。

HTML 属性

请尊重这些 HTML 属性：空行会产生段落。 在列表环境中，空行会结束列表。 换行符会产生一个空格，这意味着换行符没有特殊效果。 无序列表环境从以星号或减号开头，后跟至少一个空格的行开始。 继续列表项的行从至少两个空格开始

此外，描述不应超过合理的大小，超过 20 行可能太多了。

请抛开个人喜好，在摘要和描述中使用美式英语拼写。 RPM 规范文件仅包含摘要和描述的英文版本，以保持 RPM 数据库较小。 本地化由 YaST 管理。

作者列表

描述结尾处的作者列表不再需要包含 [注意：自 2011 年夏季以来]。 如果您计划通过提及来表彰作者，请使用单独的 AUTHORS 文件来记录功劳。 如果该文件尚未包含在上游软件包中，您可以创建一个，并像这样使用它

Source2:        AUTHORS
...
%setup
cp %{S:2} .
...
%files
%doc AUTHORS

摘要或描述中的商标

打包者在使用摘要或描述中的商标时应小心。 有一些规则需要遵循

  • 切勿使用“(TM)”或“(R)”（或 Unicode 等效项，™/®）。 正确使用这些内容非常复杂，因此对我们来说不使用它们实际上更安全。
  • 以一种不含糊的方式使用商标。 避免使用“类似于”或“像”之类的短语。 一些例子
  • 错误：它类似于 Adobe Photoshop。
  • 正确：它支持 Adobe Photoshop PSD 文件，…
  • 错误：Microsoft Office 的 Linux 版本
  • 正确：支持 Microsoft Office DOC 文件的文字处理器

如果您不确定，请问自己，有没有可能有人会混淆并认为该软件包是受商标保护的项目？ 如果有疑问，请尝试省略商标。

关于描述的中立性

  • “快速”：其他所有软件都声称“快速”。 但是与什么相比“快速”？ 因为没有软件声称故意慢速，所以你的“快速”实际上只是平均水平。
  • “免费”：openSUSE 中的所有内容都必须是免费的（openSUSE:Factory:NonFree 除外），因此这不是使软件包在所有软件包中脱颖而出的属性。
  • “漂亮”、“现代”、“简单”、“轻巧”、“强大”……：这些是个人印象，不能代表公正的观点。
  • “功能齐全”：严格来说，任何程序都可以拥有无限数量的附加功能，因此从定义上讲，它不能拥有所有功能。 最好写它实现了某个规范的功能。
  • 极其、超：冗余的副词，不会使软件与现在不同。
  • 企业级/等级、获奖、领先、获胜：拒绝使用流行语。 他们是谎言。
从 "https://en.opensuse.net.cn/index.php?title=openSUSE:Package_description_guidelines&oldid=130790" 检索