Next: Snippets versus Phases, Previous: Números de versão, Up: Diretrizes de empacotamento [Contents][Index]
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. …")
Next: Snippets versus Phases, Previous: Números de versão, Up: Diretrizes de empacotamento [Contents][Index]