Hinweise für Entwickler

Copyright

Copyright (C) 2012-2013  Stephan Kreutzer

This file is part of Freie Bibel.

Freie Bibel is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 or any later version,
as published by the Free Software Foundation.

Freie Bibel is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License 3 for more details.

You should have received a copy of the GNU General Public License
along with Freie Bibel. If not, see <http://www.gnu.org/licenses/>.

The complete source code of this file is available at <http://www.freie-bibel.de>.
          

Bibeldigitalisierung

Die Bibeldigitalisierung an sich wird bisher durch Abfotografieren und nachträgliche Bildbearbeitung realisiert. Eine Bibel-Seite wird zunächst in Graustufen umgewandelt und dann mit möglichst hohem Kontrast-Ausgleich versehen, wobei die einzelnen Buchstaben an den Rändern von der Helligkeit nicht übertönt werden sollen und gleichzeitig die dunkelste Stelle noch lesbar bleiben muss. Mit intelligenter Skalierung (nicht gerastert, d.h. mit Antialiasing) wird die Bildbreite auf ca. 1000 Pixel gebracht1, im Zweifel sollte die Breite lieber etwas darüber liegen als darunter. Nach der Bearbeitung werden die Bilder als *.png für verlustlose Kompression mit 256 Farben gespeichert.

Die Übertragung in eine Haggai-XML-Bibel-Datei geschieht bisweilen durch buchstabenäquivalentes Abtippen. Haggai-XML als Format-Basis für die Erfassung von Bibeltexten wird deshalb bevorzugt, weil der Schwerpunkt nicht auf einer Auszeichnung von Satzstrukturen oder einer originalgetreuen Wiedergabe des zugrundeliegenden Exemplars beruht, sondern den reinen Übersetzungstext ohne Ausgabe-spezifischen Eigenheiten (Beigaben etc.) aufzunehmen vermag, was besonders für die spätere Print-Verarbeitung von Bedeutung ist. Ferner existieren eine Reihe von weiteren Regeln, die zwecks exakter Wiedergabe der Textfassung berücksichtigt werden müssen – hier einige davon:

Tools

Im Verzeichnis $/tools/ befinden sich die Quelldateien verschiedener Werkzeuge, die entweder lediglich angewendet, eventuell angepasst oder schließlich sogar gemäß eigener Anforderungen erweitert werden können:

textvergleicher

Damit der textvergleicher ausgeführt werden kann, müssen die *.java-Dateien in Java-Bytecode für eine Java-VM überführt werden. Evtl. ist hierfür zunächst das Java SDK (siehe freie Implementierung OpenJDK) zu installieren. Wenn mangels einer typischen Build-Umgebung der Aufruf des makefiles im textvergleicher-Verzeichnis nicht möglich ist, können die *.java-Dateien alternativ manuell einzeln kompiliert werden:

              javac ConfigProcessor.java
              javac BibleProcessor.java
              javac HtmlProcessor.java
              javac textvergleicher.java
            

Sollte auf einem Zielsystem das installierte Java SDK (zu prüfen mittels javac -version) von der Java-VM abweichen (zu prüfen mittels java -version) und ferner keine Möglichkeit bestehen, auf die Installation Einfluss zu nehmen, kann mit

              javac -source 1.6 -target 1.6 ConfigProcessor.java
            

die einzelne Quelldatei ConfigProcessor.java für Java 1.6 kompiliert werden. Wenn dann pro *.java-Datei eine entsprechende *.class-Bytecode-Datei erzeugt wurde, kann textvergleicher mit

              java textvergleicher config.xml
            

aufgerufen werden. Allerdings sollte vorher die config.xml-Datei angepasst worden sein, dort sind nämlich die Quell-Haggai-XML-Dateien (<inFile>), das Quell-Verzeichnis für Annotationen (<annotationDirectory>) als auch das Ausgabe-Verzeichnis (<outDirectory>) plus die gewünschten Bibelbuch-Namen (<bookmappings>) zu hinterlegen. Im Annotations-Verzeichnis müssen die Annotationen als einzelne Dateien mit folgender Benennung

              <buchnummer>_<kapitelnummer>_<versnummer>.html
            

(Nummern ohne führende Nullen) abgelegt sein. Der dort enthaltene HTML-Text wird vom textvergleicher unmittelbar in die Ausgabe übernommen. Da die Ausgabe-Dateien auf eine nicht automatisch generierte index.html-Datei verweisen, sollte diese manuell angelegt werden.

hag2latex7

hag2latex7 verhält sich ziemlich ähnlich wie der textvergleicher, nur dass in Ermangelung von make weniger Dateien einzeln kompiliert werden müssen:

              javac ParallelProcessor.java
              javac hag2latex7.java
            

Der Aufruf erfolgt anschließend mit

              java hag2latex7 haggai_links.xml haggai_rechts.xml out.tex
            

Daraufhin muss die Ausgabe nur noch wie sonst bei der Gruppe der hag2latex-Tools auch mit

              pdflatex out.tex
              pdflatex out.tex
              pdflatex out.tex
              pdflatex out.tex
            

von LaTeX zum PDF verarbeitet werden.

hag2html

Soll einmalig eine HTML-Ausgabe erzeugt werden, kann ein entsprechender XML-Transformator aufgerufen werden. Für XMLStarlet Toolkit genügt

              xmlstarlet transform hag2html.xsl input.xml > output.html
            

Für denselben Zweck kann aber auch der Apache FOP eingesetzt werden:

              fop -xml input.xml -xsl hag2html.xsl -foout output.html
            

Wenn diese Art der Verarbeitung nicht erwünscht ist, kann alternativ auf den expliziten Aufruf eines Prozessors ganz verzichtet und stattdessen in der hypothetischen input.xml direkt unter der XML-Processing-Instruction (<?xml ?>) ein anzuwendendes Stylesheet angegeben werden:


              <?xml version="1.0" encoding="UTF-8"?>
              <?xml-stylesheet type="text/xsl" href="hag2html.xsl"?>
              <XMLBIBLE ... >
                ...
              </XMLBIBLE>
            

Wird die input.xml nun im Browser geöffnet, erfolgt die Darstellung nun Stylesheet-kontrolliert. Um die Nutzung für Endanwender zu vereinfachen, empfiehlt es sich, eine index.html mit Weiterleitung anzulegen:


              <html>
                <head>
                  <meta http-equiv="refresh" content="0; URL=input.xml">
                </head>
                <body>
                  <p>
                    Falls die automatische Weiterleitung nicht funktioniert,
                    bitte einfach <a href="input.xml">hier</a> klicken.
                  </p>
                </body>
              </html>
            

hag2fo

Zur Erzeugung der PDF-Druckvorlage genügt der Aufruf des Apache FOP wie folgt:

              fop -c fop.xconf -xml input.xml -xsl hag2fo.xsl -pdf output.pdf
            

Die Datei fop.xconf wird zur Schriftarten-Konfiguration verwendet, wo standardmäßig in den installierten Schriftarten des Systems gesucht werden soll, alternativ aber auch absolute Pfade zu Schriftart-Dateien angegeben werden können.

hag2latex

Im ersten Schritt wird über das XMLStarlet Toolkit die LaTeX-Ausgabe erzeugt:

              xmlstarlet transform hag2latex1.xsl input.xml > output.tex
            

Sodann kann manuelle Mikro-Typografie an der output.tex vorgenommen werden. Da in der Ausgabe jeder Vers auf eine eigene Zeile gesetzt wird, können über die GNU Diffutils die eingepflegten Änderungen gesichert werden, um bei einem späteren erneuten Lauf diese wieder einzupatchen. Um zum Endergebnis zu gelangen, muss LaTeX das Dokument mehrmals verarbeiten, um etwa alle Fußnoten und Zusätze am Seitenrand an der richtigen Stelle platzieren zu können:

              pdflatex output.tex
              pdflatex output.tex
              pdflatex output.tex
              pdflatex output.tex
            

Je nach hag2latex-Version sind teils umfangreichere manuelle Anpassungen notwendig, um zur optimalen Print-Vorlage zu gelangen, was auf die jeweils eingesetzten LaTeX-Pakete und deren Fähigkeiten sowie evtl. entstehende Konflikte zurückzuführen ist. Da sich durch die Anpassungen der Fließtext sehr wahrscheinlich verschieben wird, empfiehlt es sich, vorn anzufangen und sich Seite für Seite vorzuarbeiten bei gleichzeitiger ständiger Kontrolle des Ergebnisses, denn eine übersehene Unschönheit könnte den Text und somit die Positionierung von Gestaltungselementen auf allen nachfolgenden Seiten verschieben. Darum sollte vom Vorgehen her der Text linear gelesen und je nach Auftreten einer potentiellen Anpassungsstelle modifiziert werden abhängig davon, welcher Anpassungsfall der Reihe nach auftritt. Zum Schluss können noch globale Modifikationen eingepflegt werden. Bei hag2latex4.xsl wäre beispielsweise im Johannes-Evangelium der Elberfelder 1885 NT (Stand der Haggai-XML-Datei 2012-10-26 oder später, sofern das Bibelbuch seither nicht verändert wurde) auf der ersten Seite ein solcher Anwendungsfall die Vereinheitlichung der Fußnoten. Das bigfoot-Paket hat keine Möglichkeit, textuell gleiche Fußnotentexte zu identifizieren, um dann pro Ergebnis-Seite doppelte Nennungen auszusortieren, wo infolge des Seitenumbruchs gleichlautende Fußnoten auf der nächsten Seite neu erwähnt werden müssten und auf der gegenwärtigen Seite entfallen würden.

Doppelte Fußnoten in der hag2latex4.xsl-Ausgabe

hag2latex4.xsl führt in der *.tex-Datei alle Fußnoten im vollen Textlaut an ihrer Position gemäß der Haggai-XML-Datei an, sodass die betroffene Zeile der *.tex-Datei leicht aufgefunden werden kann, zumal Verse immer mit einer neuen Zeile beginnen und der Befehl


              \putmarginpar{versepos:43:1:3}
            

nach versepos erst die Nummer des Bibelbuches, dann das Kapitel und zuletzt die Versnummer angibt, wodurch man nach dem betroffenen Vers suchen kann. In der Zeile ist dann auch schnell


              dasselbe,\footnote{O. ihn.} und ohne dasselbe\footnote{O. ihn.} ward
            

aufgefunden, die Ursache für die doppelte Fußnote. Die zweite Erwähnung wird dann einfach durch \footnotemark[2] ersetzt, wobei 2 die Fußnotennummer der ersten Erwähnung ist. Der Ausschnitt lautet dann


              dasselbe,\footnote{O. ihn.} und ohne dasselbe\footnotemark[2] ward
            

und hat

Korrigierte doppelte Fußnoten in der hag2latex4.xsl-Ausgabe

zur Folge. Dabei muss berücksichtigt werden, dass alle nachfolgenden Fußnotennummern durch die nun fehlende, ehemals doppelte Fußnote um 1 dekrementiert wurden, sodass etwa die frühere Fußnote 4 nun die Nummer 3 aufweist. Wenn also händisch doppelte Fußnoten durch \footnotemark ersetzt werden, hängt die als Argument übergebene Fußnotennummer unmittelbar von allen übrigen Fußnoten der Seite ab und eine Änderung an Reihenfolge oder Anzahl würde das Argument hinfällig machen – dies trifft übrigens auch zu, wenn infolge von Textänderungen die Fußnotenposition auf die nächste Seite wandert. Als weiterer Effekt kann durch die Eliminierung der doppelten Fußnoten der Fußnotenapparat Zeilen verlieren, sodass LaTeX für den Fließtext mehr Raum zur Verfügung hat, evtl. mehr Zeilen auf die Seite nimmt und somit den gesamten nachfolgenden Text um die Anzahl der zusätzlich untergebrachten Zeilen verschiebt.

Ein weiteres Problem betrifft den automatischen Spaltenausgleich, der teilweise schlichtweg unterbleibt. In manchen Fällen kann die Fußnotenpositionierung ursächlich sein – wenn sie es aber nicht ist, genügt eine einfache Unterstützung des Spaltenausgleichs durch manuelles Setzen des Seitenumbruchs. Ein Beispiel dafür ist beispielsweise die erste Seite des Philipperbriefs der Elberfelder 1907 (Stand der Haggai-XML-Datei 2012-11-19 oder später, sofern das Bibelbuch seither nicht verändert wurde):

Kein automatischer Spaltenausgleich in der hag2latex4.xsl-Ausgabe

Da offenbar die hier fehlende Zeile auf die nächste Seite verschoben wurde, kann dort die eigentlich erwünschte Seitenumbruch-Position im Text identifiziert werden:

Wünschenswerte Seitenumbruch-Position für den automatischen Spaltenausgleich der hag2latex4.xsl-Ausgabe

Um nun das Ergebnis entsprechend zu beeinflussen, muss nun direkt im Anschluss des letzten Wortes der Zeile ein \pagebreak{} hinzugefügt werden. Dabei ist unbedingt zu beachten, dass das dazwischenliegende Leerzeichen von LaTeX bereits als auf der nächsten Seite liegend angesehen wird, sodass


              auf daß euer \pagebreak{}Rühmen in Christo
            

den Umbruch nach der kompletten zweiten Zeile platzieren würde, da dieser ganz an deren Anfang festgelegt wurde. Stattdessen muss die Korrektur unter Beibehaltung des dazwischenliegenden Leerzeichens wie folgt lauten:


              auf daß euer\pagebreak{} Rühmen in Christo
            

womit das gewünschte Ergebnis

Spaltenausgleich durch manuellen Seitenumbruch in der hag2latex4.xsl-Ausgabe erzielt

erreicht ist.

hag2epub

Um eine EPUB-Datei vollautomatisch zu erstellen, genügt in dem Unterordner der jeweiligen hag2epub-Version folgender Aufruf, solange mindestens eine Shell, das XMLStarlet Toolkit und zip installiert sind:

              ./hag2epub.sh input.xml output
            

output ist dabei das Ausgabe-Verzeichnis, in welchem bei Erfolg die Datei out.epub abgestellt werden wird. Bei Bedarf können alle Aufrufe des Shell-Scripts auch separat und unter Ersetzung durch ein Programm-Äquivalent durchgeführt werden, wenn daraus ebenfalls eine gültige EPUB-Datei resultiert. Eine Validierung des Ergebnisses kann mit dem EPUB-Validator des IDPF vorgenommen werden.

Weiterverarbeitung

Die durch die oben beschriebenen Tools erzeugten Resultate stellen noch nicht das Ende des Verarbeitungsprozesses dar. Oft sind weitere Schritte nötig, um das gewünschte Ergebnis letztendlich zu erreichen, was aber nicht mehr in den Aufgabenbereich des Projekts „Freie Bibel“ fällt und darum hier nur grob angedeutet werden kann. Meistens handelt es sich dann auch um reine Nutzungsfragen, die durchaus individuell beantwortet werden können.

Ein häufiger Anwendungsfall betrifft die Ausgabe als PDF in DIN A4-Format, womit ein Druck als DIN A3-Heft mithilfe der psutils wie folgt realisiert werden kann:

            pdf2ps 1.pdf
            psbook 1.ps 2.ps
            psnup -Pa4 -l -pa3 -2 -s1 2.ps 3.ps
            ps2pdf -sPAPERSIZE=a3 3.ps
          

pdf2ps konvertiert das PDF erstmal nach 1.ps, um die PostScript-Manipulationen der psutils darauf anwenden zu können. Mit psbook werden die Seiten „ausgeschossen“, sodass die Seitenfolge mit der letzten Seite beginnt, dann folgt die erste, dann die zweite, dann die vorletzte, dann die vorvorletzte, dann die dritte, dann die vierte, dann die vorvorvorletzte, und in diesem 4er-Rhytmus so weiter, bis sich die Seiten in der Mitte treffen. Grund hierfür ist, dass die A3-Seitenbögen später in der Mitte gefaltet und gebunden werden, was von demselben Bogen die eine Ursprungsseite als links von der Mitte und die andere als rechts von der Mitte enden lässt. Von der Mitte des Hefts aus gesehen liegen sich die Folgeseiten direkt gegenüber auf demselben Blatt Papier, fallen aber links in der Seitenzahl ab und steigen rechts an, was bei separater Betrachtung der einzelnen Papierblätter zu der geschilderten Aufteilung führt. Insofern ist es ratsam, als Gesamtseitenzahl 4 oder ein vielfaches von 4 anzustreben, da eine A3-Papierseite 4 A4-Ursprungsseiten aufnehmen wird. psnup kümmert sich dann um die Anordnung auf dem A3-Blatt, indem -Pa4 das Eingangsformat A4 nennt, -l „landscape orientation“ (Querformat, d.h. Ursprungsseite um 90° im Gegenuhrzeigersinn drehen) definiert, -pa3 DIN A3 aus Ausgangsformat festlegt, -2 angibt, dass zwei Ursprungsseiten auf einer Ergebnisseite untergebracht werden sollen und -s1 die Skalierung um Faktor 1.0 (d.h. gleichbleibend – wenn die Option fehlt, wird automatisch berechnet, welche Skalierung notwendig ist, um die Ausgangsseiten auf dem Ziel unterzubringen) veranlasst. Bei Bedarf könnte auch noch die Option -d angegeben werden, was einen Rahmen zu Überprüfungszwecken zur Folge hat, um etwa die Anordnung der Ursprungsseiten optisch nachzuvollziehen. ps2pdf konvertiert die manipulierte PostScript-Datei 3.ps zurück nach 3.pdf, wo durch -sPAPERSIZE=a3 nochmal für PDF die Abmessungen angegeben werden müssen. Der DIN A3-Duplexdruck an der kurzen Seitenseite sollte dann zu den Heftseiten führen, die nur noch in der Mitte gefalzt und gebunden zu werden brauchen. Mit einem Langarmhefter (mind. DIN A3!) können solche Hefte auch getackert werden – dabei empfiehlt es sich, erst zu heften und danach zu falten.

Seit hag2latex8.xsl können aber ebenso auch kleinere Heftchen mit DIN A5-Seitenformat auf gewöhnliches DIN A4-Papier gedruckt werden, indem die Verarbeitung mithilfe der psutils wie folgt abgeändert wird:

            pdf2ps 1.pdf
            psbook 1.ps 2.ps
            psnup -Pa5 -l -pa4 -2 -s1 2.ps 3.ps
            ps2pdf 3.ps
          

hag2latex10.xsl für kleine DIN A6-Verteilheftchen (gedruckt auf DIN A4) hingegen bedarf etwas anderer Verarbeitungsaufrufe:

            pdf2ps 1.pdf
            psbook 1.ps 2.ps
            pstops '2:0+1(10.5cm,0)' 2.ps 3.ps
            pstops '4:0(0,14.8cm)+2,1(0,14.8cm)+3' 3.ps 4.ps
            ps2pdf 4.ps
          

Anschließend kann der Ausruck mit einer Hebel-Schneidemaschine oder einer Schere geschnitten werden. Von den beiden DIN A5-Stapeln, die sich daraus ergeben, können, mit Seite 1 beginnend, die Seiten beider Stapel jeweils im Wechsel zusammengelegt werden. Das Ergebnis kann daraufhin wie sonst auch mit einem Langarmhefter getackert und zu DIN A6 gefaltet werden.

Nach deutschem Recht ist der Herausgeber einer Publikation verpflichtet, sog. „Pflichtexemplare“ mindestens an die Deutsche Nationalbibliothek und ggf. auch an die zuständige(n) Landesbibliothek(en) abzuliefern. Die Bestimmungen dazu gehen auf die „Verordnung über die Pflichtablieferung von Medienwerken an die Deutsche Nationalbibliothek“ zurück, wo insbesondere unter „§ 4 Einschränkung der Ablieferungspflicht für bestimmte Gattungen von körperlichen Medienwerken“ spezifiziert ist, welche Veröffentlichungen im Print-Bereich betroffen sind. Die Deutsche Nationalbibliothek stellt ein PDF-Heft der aktuellsten Kalenderwoche in den Reihen A und B ab (A für verlegerische Veröffentlichungen, B ohne Verlagsbeteiligung), wo die in den Bestand aufgenommenen Ersterscheinungen verzeichnet sind. Ferner besteht die Möglichkeit, den Online-Katalog nach Bibelbuch-Autor, Thema (Bibel) oder Herausgeber (Eintrag „Verleger/Firma, Ort“) zu durchsuchen – wobei die Suchbegriffe oft eigenen Notationsschemata folgen.

Abschließende Bemerkung

Diese Hinweise für Entwickler sind nicht letztgültig, sondern als gängige Praxis und bewährte Konzepte zu verstehen. Obwohl es freilich jedermann offen steht, aufgrund der freien Lizenz-Politik seine eigene Umsetzung und Implementierung zu starten, sollen doch innerhalb des offiziellen Software-Pakets diese Empfehlungen berücksichtigt werden, um Inkompatibilität zu vermeiden. In jedem Fall ist eine offene Diskussion über mögliche Lösungen und Verfahrensweisen erwünscht, um mit der Zeit die Schwächen der hier vorgestellten Methoden zu beseitigen.

Fußnoten

  1. Natürlich sollte hierfür das Bild 1000 Pixel überschreiten, anderenfalls ist keine Skalierung notwendig (dann sollte das Bild aber auch nicht zu klein sein). 1.

Weiterführende Links