22.4.4 Sinopses e descrições

Como vimos anteriormente, cada pacote no GNU Guix inclui uma sinopse e uma descrição (see Definindo pacotes). Sinopses e descrições são importantes: são o que o guix package --search pesquisa e uma informação crucial para ajudar os usuários a determinar se um determinado pacote atende às suas necessidades. Consequentemente, os empacotadores devem prestar atenção ao que entra neles.

As sinopses devem começar com uma letra maiúscula e não devem terminar com um ponto. Elas não devem começar com “a” ou “the”, que geralmente não traz nada; por exemplo, prefira “Tool-frobbing tool” em vez de “A tool that frobs files”. A sinopse deve dizer o que é o pacote – por exemplo, “Core GNU utilities (file, text, shell)” – ou para que é usado – por exemplo, a sinopse do GNU grep é “Print lines matching a pattern”.

Lembre-se de que a sinopse deve ser significativa para um público muito amplo. Por exemplo, “Manipulate alignments in the SAM format” pode fazer sentido para um pesquisador experiente em bioinformática, mas pode ser bastante inútil ou até enganoso para um público não especializado. É uma boa ideia apresentar uma sinopse que dê uma ideia do domínio do aplicativo do pacote. Neste exemplo, isso pode fornecer algo como “Manipulate nucleotide sequence alignments”, o que, esperançosamente, dá ao usuário uma melhor ideia de se é isso que eles estão procurando.

Descrições devem levar entre cinco e dez linhas. Use sentenças completas e evite usar acrônimos sem primeiro apresentá-los. Por favor, evite frases de marketing como “inovação mundial”, “força industrial” e “próxima geração”, e evite superlativos como “a mais avançada” – eles não ajudam o usuário procurando por um pacote e podem atém parece suspeito. Em vez idsso, tente se ater aos fatos, mencionando casos de uso e recursos.

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.

Para permitir que xgettext extrai-as com strings traduzíveis, as sinopses e descrições devem ser strings literais. Isso significa que você não pode usar string-append ou format para construir essas strings:

(package
  ;; …
  (synopsis "Isso é traduzível")
  (description (string-append "Isso " "*não*" " é traduzível.")))

Tradução é muito trabalhoso, então, como empacotador, por favor, tenha ainda mais atenção às suas sinopses e descrições, pois cada alteração pode implicar em trabalho adicional para tradutores. Para ajudá-loas, é possível tornar recomendações ou instruções visíveis inserindo comentários especiais como esse (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. …")