Alea Aquarius Wiki
Advertisement
Alea Aquarius Wiki

Auf dieser Seite wird der Umgang mit den Kapitelvisualisierungen erklärt, insbesondere deren Erstellung und Modifikation.

Grundlagen

Die Kapitelvisualisierungen werden automatisiert mit einem Skript erzeugt, welches sich book-barify (bb) nennt. Kleines Filmröllchen schrieb dieses Skript für genau einen solchen Zweck, und es ist hier frei verfügbar. Das Skript ist ein kleines Programm, welches SVG-Dateien erstellt; das sind spezielle Grafikdateien, die jeder Webbrowser öffnen kann. Eine SVG-Datei kann direkt auf dem Wiki hochgeladen werden.

Um die Erstellung der Visualisierungen reproduzierbar zu machen (z.B. wenn in bb Fehler behoben werden) und die Visualisierungen damit von jeglicher inhärenter Schöpfungshöhe zu befreien (folglich Public Domain), enthalten die Beschreibungsseiten der Kapitelvisualisierungen genaue Anleitungen, wie sie erstellt wurden. Diese Anleitung ist zweiteilig und besteht zum einen aus den Kapiteldaten, zum anderen aus den Formatierungsdaten, die dem Programm direkt übergeben werden.

Benutzen von book-barify (allgemein)

Herunterladen und Installation

Kurzhinweis: Wenn du bereits Python hast und mit Git vertraut bist, reicht es, das Repo zu klonen.

bb ist ein Python-Skript. Wenn du an der Weiterentwicklung von bb interessiert bist, solltest du mit dieser Programmiersprache vertraut sein. Auch wenn nicht, musst du einen Python-Interpreter installieren, um bb auszuführen. Dafür benutzt du am besten den Standard-Interpreter (CPython) in einer der neuesten Versionen (3.8 oder später), den man für alle Betriebssysteme direkt über die verlinkte Website erhalten kann. Im Folgenden wird angenommen, dass du eine Befehlszeile benutzen kannst, um Befehlszeilenprogramme auszuführen. Glücklicherweise gibt es in diesem Anwendungsfall keine Unterschiede zwischen den Betriebssystemen.

Prüfe vor den nächsten Schritten, dass du Python ausführen kannst. Der Befehl python -h sollte eine Hilfeliste ausgeben und keinen Fehler anzeigen. Auf manchen Systemen ist der Befehl hingegen python3; sollte das bei dir der Fall sein, musst du im weiteren Verlauf eben immer python3 statt python verwenden. Um bb zu benutzen, brauchst du für Python noch BeautifulSoup4 und einen XML-Parser wie lxml. Diese können über pip installiert werden (braucht evtl. Administratorrechte): python -m pip install bs4 lxml

Um bb herunterzuladen, gibt es zwei Möglichkeiten. Die für Anfänger einfachste besteht im direkten Herunterladen des Repo-Zips, dafür auf der Seite von bb auf Code, dann auf Download ZIP klicken. Die heruntergeladene Datei entpacken und im Ordner book-barify eine Befehlszeile öffnen. Alternativ kann das Repository auch per Git geklont werden; dieser Prozess ist für Fortgeschrittene schneller, soll aber hier nicht erklärt werden.

Funktionsweise

Im Wurzelordner von bb befindet sich eine Python-Datei namens book-barify.py. Diese Datei muss mit Python ausgeführt werden: Befehl python book-barify.py. Es sollte eine Kurzhilfe erscheinen, die mit „usage“ beginnt. Eine Langhilfe erhält man mit der -h-Flagge: python book-barify.py -h. Die weiteren Argumente, die dem Skript übergeben werden müssen, sind in der Langhilfe ausführlich erklärt. Weitere Erklärungen finden sich in der Datei README.md (auch auf GitHub selbst direkt zu lesen).

bb arbeitet mithilfe von zwei Konfigurationen. Zum einen werden für die Visualisierungen Kapiteldaten herangezogen, die sich in einer CSV-Datei befinden. Das genaue Format ist im README erklärt und es gibt eine Beispieldatei. Die Kapiteldaten können durch Farbdaten und Textannotationen ergänzt werden, während die Kapitelnamen zwar vorhanden sein müssen, aber nicht in die Visualisierung mit aufgenommen werden. Weitere Formatierungsoptionen, die die gesamte Ausgabe betreffen, werden auf der Befehlszeile durch eine Vielzahl an Argumenten festgelegt. Dazu gehören der Balkenalgorithmus, das Ausgabeformat, Größe der Kapitelbalken, statische Farben, Vorhandensein der Textspalte und Textoptionen etc.

Mit den Hauptoptionen -i und -o werden die Eingabe- und Ausgabedatei festgelegt, wobei die Ausgabedatei natürlich nicht vorhanden sein darf bzw. bedingungslos überschrieben wird. Als Ausgabe erzeugt bb eine SVG-Datei, die jeder moderne Browser lesen kann. Auch viele andere Programme (z.B. Inkscape) arbeiten mit SVG-Dateien. Die Besonderheit dieser Dateien ist, dass es sich um Vektorgrafiken handelt, die – vereinfacht gesagt – unendliche Auflösung besitzen. Daher kann die Datei, falls sie in ein klassisches Bildformat verwandelt werden muss, in einer beliebig hohen Auflösung übertragen werden. Das Wiki selbst erzeugt Vorschaubilder bis ca. 3000 Pixel Seitenlänge.

Benutzen von book-barify, um eine alte Visualisierung zu wiederholen

Es wird für diesen Abschnitt vorausgesetzt, dass du die allgemeine Bedienung von bb beherrschst.

Alle Kapitelvisualisierungen auf dem Wiki enthalten in ihrer Beschreibung sowohl die Befehlszeilenargumente als auch die CSV-Datei. Zunächst muss eine CSV-Datei angelegt werden, die den gegebenen Inhalt hat. Dann kann bb mit dieser Datei als Eingabe aufgerufen werden. Beachte, dass die Beschreibung der Visualisierung nur die Formatierungsargumente (wie -m, -f, -b) enthält. Du musst immer noch Python mit dem bb-Skript aufrufen und außerdem die -i und -o-Optionen benutzen, um die Eingabe-CSV-Datei und den Ausgabedateinamen anzugeben.

Die Ausgabedatei sollte (zumindest vom Aussehen her) zur Wiki-Datei identisch sein. Ist das nicht der Fall, kontaktiere den/die Hochlader*in der Wiki-Datei (bzw. der letzten Version der Datei).

Erstellen einer neuen Kapitelvisualisierung

Es wird für diesen Abschnitt vorausgesetzt, dass du die Bedienung von bb im Kontext des Wikis beherrschst und bestehende Visualisierungen reproduzieren kannst.

  1. Erstelle die Kapitelinfo-CSV für das Buch. Dafür ist es nützlich, wenn die Wiki-Seite des Buchs bereits Kapitelzahlen, Kapitelnamen und Seitenzahlen beinhaltet. Beachte natürlich, dass es am Ende ein Pseudo-Kapitel ohne Namen geben muss, welches die Seitenzahl der letzten Textseite des Buchs hat. Dies ist nötigt, damit auch das letzte Kapitel eine richtige Seitenzahl hat.
  2. Ergänze die Kapitelinfos um Textannotationen, die wichtige Abschnitte beschriften. Es sollten nicht mehr als etwa eine Anmerkung pro 50 Seiten vorhanden sein. Die einzelnen Anmerkungen sollten nur aus wenigen Wörtern bestehen und dürfen gerne die Ereignisse vereinfachend oder verkürzend darstellen.
  3. Ergänze die Kapitelinfos um Farben, die Akte oder andere Infos markieren. Orientiere dich dabei an den Visualisierungen der Bücher derselben Reihe. Benutze immer dieselben Farben wie die Bücher derselben Reihe, andernfalls sind entweder Wiki-Farben oder Farben einer dunklen blau-grünen Palette erwünscht.
  4. Finde eine schöne Kombination an Formatierungsargumenten. Für Bücher, die zu einer Reihe gehören, sollten immer die Argumente der restlichen Reihe genutzt werden, damit alle Visualisierungen einheitlich aussehen. Eventuell musst du die Argumente der gesamten Reihe anpassen, wenn z.B. Text zu lang ist.
  5. Lade die Visualisierung unter einem sinnvollen Namen hoch. Der Name sollte auch in das Schema der Visualisierungen von anderen Büchern der Reihe passen.
  6. Nutze die Vorlage:Kapitelvisualisierung, um die Beschreibung der Visualisierung auszufüllen. Lies die Seite der Vorlage, um zu erfahren, wie du dort die CSV-Datei und die Formatierungsargumente für bb einfügst.
Advertisement