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

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

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

Помните, что краткое описание должно быть понятным для очень широкой аудитории. Например, "Манипулирование выравниванием в формате 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.

Синопсисы и описания перевелены волонтерами at 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. …")