22.4.4 Sinopsis y descripciones

Como hemos visto previamente, cada paquete en GNU Guix incluye una sinopsis y una descripción (see Definición de paquetes). Las sinopsis y descripciones son importantes: son en lo que guix package --search busca, y una pieza crucial de información para ayudar a las usuarias a determinar si un paquete dado cubre sus necesidades. Consecuentemente, las empaquetadoras deben prestar atención a qué se incluye en ellas.

Las sinopsis deben empezar con mayúscula y no deben terminar con punto. No deben empezar con un artículo que habitualmente no aporta nada; por ejemplo, se prefiere “Herramienta para chiribizar” sobre “Una herramienta que chiribiza archivos”. La sinopsis debe decir qué es el paquete—por ejemplo, “Utilidades básicas GNU (archivos, texto, intérprete de consola)”—o para qué se usa—por ejemplo, la sinopsis de GNU grep es “Imprime líneas aceptadas por un patrón”.

Tenga en cuenta que las sinopsis deben tener un claro significado para una audiencia muy amplia. Por ejemplo, “Manipula la alineación en el formato SAM” puede tener sentido para una investigadora de bioinformática con experiencia, pero puede ser de poca ayuda o incluso llevar a confusión a una audiencia no-especializada. Es una buena idea proporcionar una sinopsis que da una idea del dominio de aplicación del paquete. En ese ejemplo, esto podría ser algo como “Manipula la alineación de secuencias de nucleótidos”, lo que con suerte proporcionará a la usuaria una mejor idea sobre si esto es lo que está buscando.

Las descripciones deben tener entre cinco y diez líneas. Use frases completas, y evite usar acrónimos sin introducirlos previamente. Por favor evite frases comerciales como “líder mundial”, “de potencia industrial” y “siguiente generación”, y evite superlativos como “el más avanzado”—no son útiles para las usuarias que buscan un paquete e incluso pueden sonar sospechosas. En vez de eso, intente ceñirse a los hechos, mencionando casos de uso y características.

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 a xgettext extraerlas como cadenas traducibles, las sinopsis y descripciones deben ser cadenas literales. Esto significa que no puede usar string-append o format para construir estas cadenas:

(package
  ;; …
  (synopsis "Esto es traducible")
  (description (string-append "Esto " "*no*" " es traducible.")))

La traducción requiere mucho trabajo, por lo que, como empaquetadora, le rogamos que ponga incluso más atención a sus sinopsis y descripciones ya que cada cambio puede suponer trabajo adicional para las traductoras. Para ayudarlas, es posible hacer recomendaciones o instrucciones insertando comentarios especiales como este (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. …")