22.4.4 Zusammenfassungen und Beschreibungen

Wie wir bereits gesehen haben, enthält jedes Paket in GNU Guix eine (im Code englischsprachige) Zusammenfassung (englisch: Synopsis) und eine Beschreibung (englisch: Description; siehe Pakete definieren). Zusammenfassungen und Beschreibungen sind wichtig: Sie werden mit guix package --search durchsucht und stellen eine entscheidende Informationsquelle für Nutzer dar, die entscheiden wollen, ob das Paket Ihren Bedürfnissen entspricht, daher sollten Paketentwickler achtgeben, was sie dort eintragen.

Zusammenfassungen müssen mit einem Großbuchstaben beginnen und dürfen nicht mit einem Punkt enden. Sie dürfen nicht mit den Artikeln „a“ oder „the“ beginnen, die meistens ohnehin nichts zum Verständnis beitragen. Zum Beispiel sollte „File-frobbing tool“ gegenüber „A tool that frobs files“ vorgezogen werden. Die Zusammenfassung sollte aussagen, um was es sich beim Paket handelt – z.B. „Core GNU utilities (file, text, shell)“ –, oder aussagen, wofür es benutzt wird – z.B. ist die Zusammenfassung für GNU grep „Print lines matching a pattern“.

Beachten Sie, dass die Zusammenfassung für eine sehr große Leserschaft einen Sinn ergeben muss. Zum Beispiel würde „Manipulate alignments in the SAM format“ vielleicht von einem erfahrenen Forscher in der Bioinformatik verstanden, könnte für die Nicht-Spezialisten in Guix’ Zielgruppe aber wenig hilfreich sein oder würde diesen sogar eine falsche Vorstellung geben. Es ist eine gute Idee, sich eine Zusammenfassung zu überlegen, die eine Vorstellung von der Anwendungsdomäne des Pakets vermittelt. Im Beispiel hier würden sich die Nutzer mit „Manipulate nucleotide sequence alignments“ hoffentlich ein besseres Bild davon machen können, ob das Paket ist, wonach sie suchen.

Beschreibungen sollten zwischen fünf und zehn Zeilen lang sein. Benutzen Sie vollständige Sätze und vermeiden Sie Abkürzungen, die Sie nicht zuvor eingeführt haben. Vermeiden Sie bitte Marketing-Phrasen wie „world-leading“ („weltweit führend“), „industrial-strength“ („industrietauglich“) und „next-generation“ („der nächsten Generation“) ebenso wie Superlative wie „the most advanced“ („das fortgeschrittenste“) – davon haben Nutzer nichts, wenn sie ein Paket suchen, und es könnte sogar verdächtig klingen. Versuchen Sie stattdessen, bei den Fakten zu bleiben und dabei Anwendungszwecke und Funktionalitäten zu erwähnen.

Beschreibungen können wie bei Texinfo ausgezeichneten Text enthalten. Das bedeutet, Text kann Verzierungen wie @code oder @dfn, Auflistungen oder Hyperlinks enthalten (siehe Overview in GNU Texinfo). Sie sollten allerdings vorsichtig sein, wenn Sie bestimmte Zeichen wie ‘@’ und geschweifte Klammern schreiben, weil es sich dabei um die grundlegenden Sonderzeichen in Texinfo handelt (siehe Special Characters in GNU Texinfo). Benutzungsschnittstellen wie guix show kümmern sich darum, solche Auszeichnungen angemessen darzustellen.

Zusammenfassungen und Beschreibungen werden von Freiwilligen bei Weblate übersetzt, damit so viele Nutzer wie möglich sie in ihrer Muttersprache lesen können. Mit Schnittstellen für Benutzer können sie in der von der aktuell eingestellten Locale festgelegten Sprache durchsucht und angezeigt werden.

Damit xgettext sie als übersetzbare Zeichenketten extrahieren kann, müssen Zusammenfassungen und Beschreibungen einfache Zeichenketten-Literale sein. Das bedeutet, dass Sie diese Zeichenketten nicht mit Prozeduren wie string-append oder format konstruieren können:

(package
  ;; …
  (synopsis "This is translatable")
  (description (string-append "This is " "*not*" " translatable.")))

Übersetzen ist viel Arbeit, also passen Sie als Paketentwickler bitte umso mehr auf, wenn Sie Ihre Zusammenfassungen und Beschreibungen formulieren, weil jede Änderung zusätzliche Arbeit für Übersetzer bedeutet. Um den Übersetzern zu helfen, können Sie Empfehlungen und Anweisungen für diese sichtbar machen, indem Sie spezielle Kommentare wie in diesem Beispiel einfügen (siehe 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. …")