22.8.4 Sinopses e descrições

Como vimos anteriormente, cada pacote no GNU Guix inclui uma sinopse e uma descrição (veja 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.

As descrições podem incluir marcação Texinfo, que é útil para introduzir ornamentos como @code ou @dfn, listas de marcadores ou hiperlinks (veja Overview em GNU Texinfo). No entanto, você deve ter cuidado ao usar alguns caracteres, por exemplo ‘@’ e chaves, que são os caracteres especiais básicos em Texinfo (veja Special Characters em GNU Texinfo). Interfaces de usuário como guix show cuidam de renderizá-lo apropriadamente.

Sinopses e descrições são traduzidas por voluntários no Weblate para que o maior número possível de usuários possam lê-las em seu idioma nativo. As interfaces de usuário os pesquisam e os exibem no idioma especificado pelo código do idioma atual.

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 (veja xgettext Invocation em 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. …")