22.8.4 Краткие обзоры и описания

Как мы видели ранее, каждый пакет в GNU Guix включает краткое описание и полное описание (see Описание пакетов). Краткие описания и полные описания важны: по ним производится поиск guix package --search, и это важная информация, которая помогает пользователям определить, насколько пакет соответствует их потребностям. Следовательно, сборщики пакетов должны следить за тем, что туда прописывается.

Краткие описания должны начинаться с заглавной буквы и не должны заканчиваться точкой. Они не должны начинаться с артикля (англ. "a" или "the"), что обычно ничего не значит; например, лучше начать "File-frobbing tool" вместо "A tool that frobs files". Краткое описание должно сообщать о том, что представляет собой пакет, то есть: "Основные утилиты GNU (файлы, текст, оболочка)", - или для чего он используется. Например, краткое описание для GNU grep таково: "Печать строк, содержащих паттерн".

Помните, что краткое описание должно быть понятным для очень широкой аудитории. Например, "Манипулирование выравниванием в формате SAM" может быть понятно продвинутым исследователям в области биоинформатики, но совершенно бесполезно или может ввести в заблужение не специалистов. Хорошая идея — включать в краткое описание идею группы приложений, к которой относится пакет. В данном примере можно предложить такой вариант: "Манипулирование выравниванием нуклеотидных последовательностей", что, в целом, даёт пользователю лучшее представление о том, на что они смотрят.

Описания должны занимать от 5 до 10 строк. Используйте полные предложения и остерегайтесь использовать аббревиатуры, которые до того не были расшифрованы. Пожалуйста, не пишите маркетинговые фразы типа “мировой лидер”, “промышленно устойчивый”, “следующего поколения”, и избегайте превосходную степень типа "самый продвинутый" — это не помогает пользователям найти желанный пакет, и может даже звучать сомнительно. Вместо этого рассказывайте о фактах, упоминая особенности и применение.

Описания могут содержать разметку Texinfo, что полезно для использования подсветки, такой, как @code или @dfn, списков или гиперссылок (see Overview in GNU Texinfo). Будьте, однако, внимательны при пользовании некоторых символов, например ‘@’ и фигурных скобок, которые являются основными спецсимволами в Texinfo (see Special Characters in GNU Texinfo). Пользовательские интерфейсы, вроде guix show, правильно учитывают разметку при построении вывода.

Краткие и полные описания переводятся добровольцами в Weblate, чтобы как можно больше пользователей могли читать их на своем родном языке. Пользовательские интерфейсы производят поиск по ним и отображают их на языке, заданном текущей локалью.

Чтобы позволить команде xgettext извлекать их как текст для перевода, краткие и полные описания должны быть буквенными строками. Это означает, что нельзя пользоваться string-append или format при составлении этих строк:

(package
  ;; …
  (synopsis "Эту строку можно переводить")
  (description (string-append "Эта строка " "*не поддерживает*" " перевод.")))

Перевод — трудоёмкая работа. Как автор пакета, пожалуйста, уделите особое внимание кратким и полным описаниям, поскольку каждое изменение може повлечь за собой дополнительную работу для переводчиков. Чтобы помочь им, можно оставлять видимые им рекомендации или инструкции, вставив особенные комментарии вот так (see xgettext Invocation in GNU Gettext):

;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
(description "ARandR is designed to provide a simple visual front end
for the X11 resize-and-rotate (RandR) extension. …")