22.8.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.

Las descripciones pueden incluir marcado Texinfo, lo que es útil para introducir ornamentos como @code o @dfn, listas de puntos o enlaces (see Overview in GNU Texinfo). Por consiguiente, debe ser cuidadosa cuando use algunos caracteres, por ejemplo ‘@’ y llaves, que son los caracteres especiales básicos en Texinfo (see Special Characters in GNU Texinfo). Las interfaces de usuaria como guix show se encargan de su correcta visualización.

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. …")