Die BibTeX-Bibliographie als zentrale Datenquelle

Idealerweise wären alle internen Dokumente in der eAkte enthalten und mit einem Aktenzeichen versehen. Da dies nicht der Fall ist, pflegen wir eine eigene Bibliogrpahie. Dies führt unter anderem dazu, dass wir mit dem Bibkey einen eigenen Primärschlüssel für jedes Werk bekommen, eine Aufgabe die eigentlich das Aktenzeichen erfüllen würde. Wenn jedes Dokument ordnungsgemäß in der eAkte samt Aktenzeichen hinterlegt wäre.

Darüber hinaus nutzen wir die Bibliographie gleich noch zum Literaturmanagement. Durch die Verschlagwortung aller erfassten Werke sind wir in der Lage sehr schnell relevante Literatur zu finden. Doch dazu mehr im Workflow.

Die Bibliographie erfüllt also zuerst die Funktion eines Bibliothek-Kataloges. Wie im klassischen Zettelkasten auch, werden alle Werke systematisch erfasst und katalogisiert. Dazu nutzen wir die BibTeX-Grammatik, die seit Jahrzehnten erprobt und weit verbreitet ist. Dabei handelt es sich um ein einfaches Textformat in dem Variablen die passenden Werte zugewiesen werden. Zahlreiche Programme unterstützen dieses Format, außerdem ist es sehr leicht menschenlesbar.

Die Bibliographie dient hier also zuallererst als ein Katalog, in dem alle relevanten Werke zentral erfasst werden.

Der technische Ablauf der Nutzung einer Bibliographie zur Erstellung einer PDF-Version ist wie folgt:

  1. Der Autor schreibt eine AsciiDoc-Datei, in der die Bibliogrpahie konfiguriert wird. Im Fließtext werden Verweise auf die zu zitierenden Werke mittels Zitationsbefehl (citenp::[Anw-TLS]) geschrieben.

  2. asciidoctor-pdf wird aufgerufen, um die AsciiDoc-Datei in eine PDF zu kompilieren

  3. asciidoctor-pdf trifft auf den Zitationsbefehl im Satz ( » …​ TLS-Algorithmen gemäß citenp::[Anw-TLS] konfigurieren …​ «)

  4. asciidoctor-pdf ruft asciidoctor-bibtex auf um die Bibliographie zu verarbeiten

  5. asciidoctor-bibtex sucht in der Bibliographie nach dem Eintrag mit dem Schlüssel Anw-TLS

  6. asciidoctor-bibtex liefert den Titel und das Jahr des Eintrags zurück

  7. asciidoctor-pdf prüft welcher Zitierstil aktiviert ist und formatiert Titel und Jahr entsprechend als »…​ TLS-Algorithmen gemäß Anweisung Transportverschlüsselung (2024) konfigurieren …​« an der Stelle des citenp-Befehls

  8. asciidoctor-pdf setzt den restlichen Text bis es auf den Bibliographie-Befehl bibliography::[] trifft

  9. asciidoctor-pdf ruft asciidoctor-bibtex auf um die Bibliographie zu verarbeiten

  10. asciidoctor-bibtex zieht alle relevanten Felder zu allen zitierten Einträgen aus der Bibliographie

  11. asciidoctor-pdf bereitet die Felder und Einträge gemäß Zitierstil auf und sortiert die Liste entsprechend. Bei APA alphabetisch nach Autor bzw. Titel und Jahr.

  12. asciidoctor-pdf gibt die Gesamt-Bibliographie im Text entstprechend formatiert aus, siehe z.B. Abb. Das Ergebnis des LaTeX-Codes, kompiliert als PDF.

Die BibTeX-Grammatik

Die Grammatik der eigentlichen Bibliographie-Datei ist recht simpel. Es gibt verschiedene wohldefinierte sprechende Feldnamen, die mit den entsprechenden Daten befüllt werden können. Lediglich beim Autoren-Feld kann es etwas komplexer werden, da BibLaTeX versucht diese Namen entsprechend zu formatieren und es mit mehrteiligen Namen unter Umständen etwas problematisch werden kann. Ansonsten sind die Felder mit einer Zeichenkette idR frei zu befüllen, Ausnahmen gibt es nur beim ISBN-/ISSN und Datums-Feld, hier sollten gültige ISBN/ISSNs verwendet werden und das Datum idealerweise im Format JJJJ-MM-TT befüllt werden, da BibLaTeX dann automatisch auf die einzelnen Bestandteile wie das Jahr zugreifen kann.

Jeder Bibliographie-Eintrag beginnt grundsätzlich mit einem @ gefolgt vom Typ des Werkes, also article, book, inbook, proceedings, techreport, manual usw. eingeleitet. Danach folgt der (fast) frei wählbare Zitationschlüssel. Aus historischen Gründen sollte im Schlüssel auf Umlaute und andere Nicht-Latin1-Zeichen verzichtet werden. Danach erwartet BibTeX bestimmte Felder, die vom Werk-Typen abhängen. So ist das Feld journaltitle nur für Artikel verfügbar, nicht aber für Bücher, da Bücher nun mal nicht in einem Journal erscheinen. Dafür haben Bücher das ISBN-Feld. Die Felder author, editor, usw. sind in der Regel selbsterklärend. Bei mehreren Autoren und/oder Herausgebern werden diese mit einem and als Stichwort verbunden. Komplexere Namen können mit geschweiften Klammern versehen werden, um den zu zitierenden Namensbestandteil festzulegen: Miranda Veracruz {de la Jolla} Cardinal erscheint in der PDF dann als de la Jolla anstatt als Cardinal. Unter keywords kann man beliebige Stichwörter komma-separiert erfassen. Welche Felder zwingend erforderlich sind und welche optional ergänzt werden können, ist in der BibLaTeX-Doku hinreichend beschrieben.

AsciiDoctor nutzt den Zitationsstil nicht nur um das Layout der Zitationen und der Bibliographie zu setzen, sondern auch um festzulegen, welche BibTeX-Felder überhaupt ausgewertet werden. Nicht-benötigte Felder und deren Werte werden ignoriert. Dies nutzen wir, um zusätzliche Felder zu erfassen, die dann außerhalb der AsciiDoc-Toolchain mit selbstgeschriebenen Perl-Skripten aufbereitet werden.

Der Zitationsstil wird im AsciiDoc-Dokument festgelegt und beeinflußt u.a. die Zitationen im Text. Im APA-Stil werden Werke mittels Autor und Jahr (Schumacher (2003)) zitiert, im IEEE-Stil hingegen über Nummern in eckigen Klammern [1]. Wir nutzen den APA-Stil, da er bei fehlenden Autoren den Titel des Dokumentes und das Jahr anzeigt. was die allgemeine Lesbarkeit der PDF erhöht, da man nicht erst am Ende des Dokumentes nachschlagen muss was sich hinter »[1]« verbirgt.

@article{Schumacher:DS:SocEng,
	IDS="datenschleuder2010",
    author = {Stefan Schumacher},
    title = {Psychologische Grundlagen des Social-Engineering},
    year = {2010},
    volume="\#94",
    journaltitle="Die Datenschleuder",
    journalsubtitle="Das wissenschaftliche Fachblatt für den Datenreisenden",
	gender="sm",
	editor="{Chaos Computer Club}",
    address="Hamburg",
    pages="52-59",
    issn="0930-1054",
	abstract="Social-Engineering ist eine Angriffsstrategie, die nicht die Technik als Opfer auserkorenhat. Stattdessen wird hier viel lieber – und vor allem effizienter – der Mensch, bzw.sein Verhalten angegriffen. Dieser Artikel zeigt, wie Social-Engineering funktioniert underklärt die zugrundeliegenden Tricks anhand sozialpsychologischer Studien und Experimente.Außerdem werden Beispiele, Warnsignale und Gegenmaßnahmen vorgestellt.Er richtet sich an Sicherheitsverantwortliche und Systemadministratoren, die verstehenwollen, wie Social-Engineering funktioniert und dieses Wissen in ihre Sicherheitsmaßnahmenintegrieren wollen.",
	keywords="steschum,social engineering,psychologie,sozialpsychologie,sicherheit,human factors",
	url="http://ds.ccc.de/pdfs/ds094.pdf",
    urldate="2010-10-10",
}

@inbook{Schumacher:Cyberterrorismus,
	 author="Stefan Schumacher",
	 title="Cyber-Terrorismus",
	 subtitle="Reale Bedrohung oder Mythos?",
	 year="2014",
	 pages="159-177",
	 editor="Stefan Hansen and Joachim Krause",
	 booktitle="Jahrbuch Terrorismus 2013/2014",
	 publisher="Verlag Barbara Budrich",
	 address="Opladen",
	keywords="steschum,terrorismus,sammelband,politikwissenschaft,cyber",
}

@inbook{Feyrer:OSJB:NetBSD,
	IDS="osjb07",
    author = "Hubert Feyrer and Stefan Schumacher and Mark Weinem",
    title = "NetBSD -- Das portabelste Betriebssystem der Welt",
    pages = "315-326",
    booktitle = "Open Source Jahrbuch 2007",
    editor="Bernd Lutterbeck and Matthias Bärwolff and Robert A. Gehring",
    isbn="978-3-86541-191-4",
    address="Berlin",
    publisher="Lehmanns Media",
    year="2007",
	keywords="steschum",
    url="http://www.opensourcejahrbuch.de/download/jb2007/OpenSourceJahrbuch2007_online.pdf",
	abstract="NetBSD ist ein modernes, vollständig freies Betriebssystem, das kontinuierlich weiterentwickelt wird. Es wird wie viele interessante Open-Source-Projekte leider wenig beachtet. Dabei eignet sich das NetBSD-Betriebssystem für jeden Anwendungszweck und es gibt kaum einen Computer, auf dem es nicht genutzt werden kann. Wegen seiner Qualität und liberalen Lizenz wird es ebenso gerne in der Lehre wie bei der Entwicklung neuer kommerzieller Produkte eingesetzt. Dieser Artikel beschreibt die wichtigsten Merkmale von NetBSD sowie dessen Einsatzmöglichkeiten im privaten und im kommerziellen Umfeld. Eine Betrachtung des pkgsrc-Paketsystems, das auch unabhängig von NetBSD eingesetzt werden kann, schließt den Artikel ab.",
    urldate="2007-03-17"
}

@inproceedings{Schumacher:ThueWa17,
    author = "Stefan Schumacher",
    title = {Informationssicherheit in Versorgungsunternehmen umsetzen},
    year = {2017},
    publisher = {Fachhochschule Erfurt},
	booktitle="22. Thüringer Wasserkolloquium",
    address="Erfurt",
    pages="33-44",
	abstract="Versorgungsunternehmen sind als Betreiber kritischer Infrastrukturen vielfältigen Angriffen aus dem Internet ausgesetzt. Sowohl einfache Bürorechner, Abrechnungssystem als auch Industriesteuerungsanlagen werden regelmäßig von verschiedenen Akteuren attackiert. Darunter fallen auch ungezielte automatisierte Massenangriffe.  Der Beitrag zeigt, wie Sie Ihre Infrastruktur vor Angriffen schützen können, wie Sie dazu strategisch vorgehen müssen und welche technisch-organisatorische Maßnahmen implementiert werden sollten.  Desweiteren werden in einem Überblick Standards bzw. Richtlinien wie ISO 27001 oder das BSI Grundschutzkonzept vorgestellt.  ",
	keywords="steschum, sicherheit, kritis, versorger, wasser",
}

@techreport{Schumacher-eurostud,
    author = {Stefan Schumacher},
    title = {Design und Implementierung der Webseite für den Studiengang »European Studies«},
    type={Handbuch},
    year = {2003},
    publisher="Otto-von-Guericke Universität Magdeburg: Institut für fremdsprachliche Philologien",
    address="Magdeburg",
    language = {german},
    keywords="howto,steschum",

Da unsere internen Dokumente in der Regel nicht als Autor-Jahr zitiert werden sollen bzw. wir eigentlich auch keine Autoren erfassen wollen, habe ich den report Typen genutzt um Richtlinien zu erfassen:

@report{anw-tls,(1)
    title="Transportverschlüsselung von Netzwerkverbindungen",(2)
    date="2024-12-24",(3)
    version="1.1.0",(4)
    addendum="Az: 08/15",(5)
    keywords="bsi,gsc,tls,ssl,ssh,transportverschlüsselung,netz",(6)
    file="Anweisung_Transportverschluesselung.pdf",(7)
    url="http://192.168.100.248:/Architektur/Anweisung_Transportverschluesselung.pdf",(8)
    abstract="Dieses Dokument regelt die Implementierung der Transportverschlüsselung im gesamten Projekt gemäß den Technischen Richtlinien des BSI.",(9)
}
1 Typ report und der Bibkey
2 Titel und ggf. Untertitel
3 Das Datum der Veröffentlichung bzw. Inkraftsetzung der Richtlinie
4 Die Version der Richtlinie
5 addendum ist ein beliebiger Anhang, wir nutzen es für das Aktenzeichen
6 die passenden Stichwörter, durch Kommata getrennt
7 der Dateiname im Projektverzeichnis
8 eine URL zum, Ablageort,
9 der Abstract, eine Kurzzusammenfassung des Inhaltes

Der Bibkey ist zwar relativ frei wählbar, wir haben aber trotzdem in der Architektur ein Schema eingeführt, so beginnen alle Dataport-eigenen Dokumente mit dp-, gefolgt von einem px-, wenn es Phoenix-eigene Dokumente sind. Danach folgt der Type wie rl- für Richtlinie. hb- für Handbuch oder anw- für Anweisung und schlussendlich der eigentliche Kurztitel. Somit kann man aus dem Bibkey halbwegs auf Herkunft (Regelungsebene), Typ und Inhalt schließen.

In Ein einfaches Beispiel für eine LaTeX-Datei, die eine Bibliographie zum zitieren nutzt. wird ein einfaches Minimalbeispiel für eine LaTeX-Datei gezeigt, die mittels BibLaTeX Werke zitiert und im Literaturverzeichnis ausgibt. Abb. Das Ergebnis des LaTeX-Codes, kompiliert als PDF. zeigt das kompilierte Minimalbeispiel als PDF.

Ein einfaches Beispiel für eine LaTeX-Datei, die eine Bibliographie zum zitieren nutzt.
\documentclass[10pt,makeidx,a4paper]{scrartcl}
\usepackage[pdftex,colorlinks=true,urlcolor=blue]{hyperref}
\usepackage[utf8]{inputenc}
\usepackage[russian,ngerman]{babel}
\newcommand\ru[1]{\foreignlanguage{russian}{#1}}
\usepackage{alltt,scrdate,textcomp,makeidx,eepic,palatino,datetime}

%%%%%%%%%%%%% Bibliographie
\usepackage[ngerman]{babel}
\usepackage[style=apa,doi=true,isbn=true,maxcitenames=3,sorting=ydnt]{biblatex}
\usepackage{csquotes}
\addbibresource{../Stefan-Schumacher-Bibliographie-utf.bib}

\begin{document}

In \LaTeX\ kann man die folgenden Dokumente mittels \texttt{textcite} direkt im Text
zitieren
\textcite{Schumacher:DS:SocEng,Schumacher:Cyberterrorismus,Feyrer:OSJB:NetBSD,Schumacher:ThueWa17,Schumacher-eurostud}
und dann in die Bibliographie verweisen lassen.

Häufig nutzt man auch \texttt{parencite}, um die Zitation in Klammern an das Ende des
Satzes zu hängen. Üblicherweise wenn man aus den Werken ohne Seiten-Angabe zitiert mit dem
Verweis vgl. für Vergleiche. Vergleiche hierzu auch \parencite{Schumacher:DS:SocEng,Schumacher:Cyberterrorismus,Feyrer:OSJB:NetBSD,Schumacher:ThueWa17,Schumacher-eurostud}

In die eckigen Klammern kann man bei jedem Zitiertstil optionale Argumente setzen, die vor
bzw. nach der Zitation gesetzt werden. In die zweiten Klammern kommen üblicherweise die
Seitenzahl oder ggf. das zitierte Kapitel \parencite[vgl.][S. 23ff]{Schumacher:DS:SocEng}.

\printbibliography
\end{document}
Bibliste Beispiel
Figure 1. Das Ergebnis des LaTeX-Codes, kompiliert als PDF.
Minimalbeispiels einer AsciiDoc-Datei mit Bibliographie
= Minimum Working Example
:bibtex-file: references.bib
:bibtex-order: alphabetical
:bibtex-style: apa

== Beispiel

TLS-Algorithmen gemäß citenp::[Anw-TLS] konfigurieren.
Weiterhin gelten die citenp::[bsi-tr-021021] und citenp::[bsi-tr-021022]

== Mitgeltende Richtlinien

bibliography::references.bib[apa]

Der Workflow mit der Bibliographie

Für Autoren von Richtlinien etc.

Schreibt ein Autor ein Dokument in AsciiDoc, kann er über die Bibliographie sehr einfach die dort enthaltenen Werke zitieren. Über den AsciiDoc-Befehl citenp:[BibKey] werden die Daten aus der Bib eingelesen und je nach Zitationsstil entsprechend im Text angezeigt. Bei einem numerischen Stil bspw. als [42], bei einem Autor-Jahr-Stil wie APA in der Art Adams (1979). Abschließend wird im Dokument das Literaturverzeichnis mittels bibliography::references.bib[ieee] ausgegeben. Hier werden dann im numerischen IEEE alle zitierten Dokumente samt Autor, Jahr, Titel und ggf. Versionssnummer und URL und Zugriffsdatum ausgegeben.

Die Bibliographie kann von allen Autoren genutzt werden, damit wird die doppelte Arbeit der Datenerfassung vermieden. Alle notwendigen Quellen werden an einer Stelle zentral erfasst und stehen für alle Autoren mit Zugriff auf die Bib-Datei zur Verfügung. Ein Autor erfasst ein mal ein Dokument in der Bibliographie, danach kann es x-mal zitiert werden.

Aktualisierungen sind zentral möglich. Ändert sich bspw. der Pfad oder die URL zu einem Dokument, muss dieses nur zentral ein mal in der Bibliographie aktualisiert werden. Danach kompiliert man ggf. die PDF-Dateien neu und alle Verweise werden automagisch aktualisiert, da die Daten bei jedem Compilerlauf aus der zentralen Bib eingelesen werden. Ähnlich einem Header, der in C per include-Anweisung importiert wird.

Für die Zitationsstile gibt es Tausende verschiedene Standards und Implementierungen, Bekanntere wie z.B. APA, ACM oder IEEE oder Speziellere, wie sie z.B. in Archiven oder Bibliotheken verwendet werden. Für unsere Richtlinien gibt es in der Regel immer eine Kapitel mit mitgeltenden Dokumenten, in denen die übergeordneten internen Regelungen aufgeführt werden. Dies lässt sich in der Praxis recht einfach als Liste mit einer Voll-Zitation erreichen. Dazu wird mit dem Befehl bibitem:[regelung-kryptographie] das entsprechende Werk komplett zitiert. Also nicht nur eine Nummer oder Autor/Jahr, sondern Titel, Untertitel, Jahr etc. pp. Da wir in den Richtlinien in der Regel keine Autoren erfassen bzw. nicht mit den Autorennamen arbeiten wollen, habe ich den Zitationsstil etwas angepasst. Nun werden die Regelungen mit Titel, Untertitel, Versionssnummer, Datum, Aktenzeichen und BibKey ausgegeben. Über das Aktenzeichen sind sie in der eAkte einfach zu finden, der Bibkey erleichtert uns die interne Arbeit und es müssen bei Reviews der Richtlinie keine Pfade geprüft werden, da hier schlichtweg keine Laufwerke, Intranet-Seiten oder Sharepoint-URLs zitiert werden. Dies erleichtert die Arbeit und macht die eigenen Dokumente wesentlich stabiler und langlebiger.

Zum Literaturmanagement

Auch zum finden und sortieren der (eigenen) gesammelten Werke ist die Bibliographie nützlich. Schließlich nützt die vollste Bibliothek ohne Zettelkasten bzw. Index nichts. Bisher wurden die eigenen Werke in einer irgendwie gewachsenen Verzeichnisstruktur abgelegt. Was verschiedene Probleme mit sich bringt, man muss Dokumente anhand des Dateinamens erkennen können und nicht alle Dokumente lassen sich in diese Verzeichnisstruktur problemlos einsortieren.

Hier ist eine einfache Webseite hilfreich, die verschiedene Sichten auf die Werke darstellen kann. Man kann problemlos die bestehende Verzeichnisstruktur übernehmen und abbilden. Zusätzlich kann man aber auch z.B. nur das Aktenzeichen als Ordnungskriterium nutzen, in dem man eine Seite erzeugt, in der die Dokumente nach Aktenzeichen sortiert dargestellt werden. Oder man erzeugt Übersichten für unterschiedliche Dokumententypen (Richtlinien, Konzepte, ADRs), Themen (Containerisierung, Verschlüsselung, BSI) oder Universen (z.B. Phoenix-TZ68, Phoenix-LD6, BSI, Dataport).

All diese Sichten bzw. Webseiten lassen sich aus der Bibliographie als Single Source of Data automatisiert erstellen. Man muss sie nur darin erfassen.

BibLaTeX bzw. biber kann nach bestimmten Kriterien filtern und bringt einige interessante Zitierstile frei Haus mit, bspw. reading, welcher speziell für Kataloge erstellt wurde. BibLaTeX kann nach Werk-Typen (book, article, proceedings) und/oder Stichwörtern filtern. So kann man bequem eine Literaturübersicht alle Bücher erstellen, die sich mit TOGAF befassen. BibLaTeX kann darüber hinaus um beliebige Felder erweitert werden, z.B. ein eigenes Feld für das Aktenzeichen. Dazu muss man dann aber auch die Style-Files für Biblatex entsprechend erweitern, was etwas mühselig werden kann.

Flexibler und mächtiger ist hier der Einsatz von Perl mit dem Modul Text:BibTeX. Diese liest eine Bibliographie ein und kann dann auf jedes einzelne Feld — auch selbst definierte — zugreifen und die Daten ausgeben.

Ich nutze dieses Modul selbst schon seit über 20 Jahren in verschiedenen Projekten. Da BibTeX und BibLaTeX inzwischen gut abgehangen sind, ist das recht hohe Alter des Perl-Moduls kein Problem. Meistens habe ich es genutzt, um eine Bibliographie einzulesen, aufzubereiten und in eine PostgreSQL-Datenbank eines Redaktionssystems einzuspeisen.

Für unsere Anwendungsfälle ist die Datenbank aber etwas überdimensioniert. Ich nutze es hier in verschiedenen Ausprägungen, um die Bibliographie für die oben bereits erwähnte Webseite aufzubereiten. Dazu wird die Bibliographie eingeselesen, alle Felder des jeweiligen Bibliographie-Eintrages in Variablen gepackt und diese entsprechend verarbeitet und formatiert wieder ausgegeben. Dabei kann ich mit beliebigen Regulären Ausdrücken suchen oder filtern und beispielsweise eine Liste aller eigenen Werke sortiert nach Aktenzeichen erstellen. Wenn noch kein Aktenzeichen erfasst ist, wird eine entsprechende Warnung oder Formatierung ausgegeben. Man kann damit auch bequem nach Stichwörtern filtern und so z.B. eine Übersicht der Werke nach Stichwort erstellen, also alle Dokumente in einer Liste die das Thema Container und/oder Grundschutz haben.

Diese Listen werden fast alle als AsciiDoc erstellt und dann mittels AsciiDoctor nach HTML, PDF und auch XML/ODT/PDF konvertiert. Die HTML-Dateien liegen dann auf einem internen Webserver.

Die notwendigen Perl-Skripte sind relativ simpel gehalten und können in einem Container mit Perl in der Gitlab CI/CD ausgeführt werden. Dazu ist ein selbsterstellter Container notwendig, da die Standard-Perl-Container leider nicht mit den notwendigen Modulen kommen. Aber auch dieses Problem lässt sich einfach lösen.

Die Vorteile der zentralen Bibliographie sind:

  • Single Source of Data

  • Daten müssen nur einmal erfasst werden

  • Daten müssen ggf. nur einmal aktualisiert werden

  • Signifikante Arbeitserleichterung für alle Autoren

  • Der Bibliographie-Schlüssel ist ein Primärschlüssel und kann als solcher z.B. für Verweise und Listen genutzt werden. Auch für Dokumente die nicht in der eAkte enthalten sind und kein Aktenzeichen haben

  • Die Bibliographie ist ein aktueller Katalog der erfassten Dokumente — damit wird das Wissensmanagement massiv vereinfacht

  • Thematische Leselisten können einfach erstellt werden

  • Die Bibliographie kann in 1..n Dateien liegen. Es ist problemlos möglich, beliebig viele Bib-Dateien einzubinden und zu pflegen. So kann man z.B. nach Abteilungen getrennte Bibliographien pflegen und in einem Dokument vereinigen, oder man unterteilt die Dateien nach thematischen Schwerpunkten. Oder lässt im Extremfall jeden Benutzer eine eigene Bib pflegen.

BibTeX ist ein wohl etabliertes Format für das Literaturmanagement und damit entsprechend gut abgehangen und weit verbreitet. Dennoch ist es praktischer, BibLaTeX einzusetzen. BibLaTeX ist flexibler als BibTeX, es unterstützt mehr Eintrags-Typen wie manual, es kann direkt beim Erstellen einer Bibliographie mit LaTeX nach Typen und Stichwörtern filtern, es kann kapitelweise Bibliographien verwalten und es ist sogar möglich mittels ids={key1,key2,key3} mehrere Zitationsschlüssel für einen einzelnen Eintrag zu verwalten. Das ist eigentlich nicht wünschenswert, da ein Primärschlüssel idealerweise nur genau ein mal existieren darf, hilft aber dabei schon existierende Bibliographien zu konsolidieren. So habe ich anfangs in meiner persönlichen Bibliographie keine Ordnung bei der Vergabe der Schlüssel eingehalten und diese ungeordneten Schlüssel natürlich auch zitiert. Nachdem ich eine Ordnung etabliert habe, konnte ich die alten Schlüssel in das ids-Feld überführen und so in den alten Dokumenten weiter mit BibLaTeX zitieren, ohne dort im Text die Schlüssel aktualisieren zu müssen.

Die Bibliographie mit Perl aufbereiten

Einer der vielen Vorteile der BibTeX-Bibliographie ist die weite Verbreitung ihrer Syntax. Hunderte Werkzeuge sind entstanden, um BibTeX-Dateien zu parsen und zu konvertieren. Neben direkten BibTeX-Editoren wie JabRef gibt es auch ein Modul für Perl, welches BibTeX verarbeiten kann.

Mit Text::BibTeX besteht dann die Möglichkeit, durch die gesamte Bibliographie zu iterieren und jedes Feld samt dazugehörigen Datum einzulesen und dann weiter zu verarbeiten. Damit kann man z.B. durch die Bibliographie parsen und alle Dokumente mit dem Keyword Container und dem zugehörigen Aktenzeichen ausgeben. Oder ich generiere damit eine Übersicht alles Stichwörter und der jeweils zugehörigen Dokumente.

GraphvizAdocBibBaum
Figure 2. Erstellung von Sichten auf die Bibliographie

Wie dies funktioniert, ist in [sourcepl1] beschrieben.

use utf8;                      # Source code is encoded using UTF-8.
use open ':encoding(UTF-8)';   # Set default encoding for file handles.
use Encode;
use HTML::Entities;

use Text::BibTeX;
use Data::Dumper qw(Dumper);

$datetime=localtime();

$wwwroot="/home/gitlab-runner/public_html/bib";
`mkdir -p $wwwroot`;

### Bibliographie oeffnen und durch alle Einträge traversieren
$bibfile = new Text::BibTeX::File "phoenixbibliographie.bib";
$bibfile->set_structure ('Bib', sortby => 'title');

###############################################################################
### Stichwoerter sammeln

### Hash, der je ein Stichwort mehreren Bibkeys zuordnet
my %sw_bibkey;

### Bibliographie traversieren
while ($entry = Text::BibTeX::Entry->new($bibfile))
{
next unless $entry->parse_ok;

## Schlüssel
$bibkey = $entry->key;   (1)

## Stichwörter aus der Bib holen
($kw,$titel) = $entry->get ('keywords','title');
## lowercase
my $tmp=$kw; $kw = lc $tmp;
## Ausrufezeichen entfernen
$kw =~ s/!/_/g;	$kw =~ s/ //g;

## Stichwoerter zerlegen
@mytags=split(/,/, $kw);
foreach $key (@mytags){(2)
    $key=~s/ //gi;
	push(@swout,"$key");
	$sw_bibkey{$key}{$bibkey} = $titel; #multidim-Hash für 1 Stichwort -> n Bibkeys
}

##Array in Hash werfen, führt zu uniq keys $hash enthält uniq(keywords) und deren Häufigkeit als string-länge der X im Wert
foreach(@swout){ (3)
     $hash{$_} .= "x"; #Für jedes Vorkommen ein X in den Wert anhängen
}#foreach(@swout){

### Hash-Schlüssel sortieren
@keyssortiert = sort { $hash{$a} cmp $hash{$b} } keys %hash;


}# Schleife durch Bibfile
###############################################################################

###
### Verzeichnisse anlegen. durch den Hash mit den Stichworten traversieren
###
`rm -rf $wwwroot/./swindex `;


foreach my $sw(@keyssortiert){(4)
	$sw =~ s/!/_/g;	$sw =~ s/ //g;
	`mkdir -p $wwwroot/swindex/$sw`;
    open(FH, '>> :encoding(UTF-8)', "$wwwroot/swindex/$sw/index.html") or die $!;
    print FH "<html><head><meta charset=\"utf-8\"></head><body><h1>$sw öäü</h1><h3>$datetime</hr><br/>\n\n\n";
    close(FH);
}

### Multi-Hash zerlegen (5)
### stichwort aus dem multi-hash holen
foreach my $swort(sort keys %sw_bibkey) {
    $swort =~ s/!/_/g;	$swort =~ s/ //g;
    # bibkey aus multihash holen
    foreach my $bkey(keys %{ $sw_bibkey{$swort} }) {
        $titel=$sw_bibkey{$swort}{$bkey};
        $titel=decode_entities(decode('utf-8', $titel));
    open(FH, '>> :encoding(UTF-8)', "$wwwroot/swindex/$swort/index.html") or die $!;
    print FH "<li> <a href=\"http://127.0.0.1/~gitlab-runner/adoc/000BibliographieKatalog.html#$bkey\">($bkey) $titel  </li>\n";
    close(FH);
    }
}
1 Die Stichwoerter und der Titel werden aus der Bibliographie geholt, der Bibkey wird in $bibkey geladen. Anschließend werden alle Stichwörter in Kleinbuchstaben umgewandelt, Ausrufezeichen und überflüssige Leerzeichen entfernt und die Zeichenkette der Stichwörter in ein Array zerlegt.
2 Diese Schleife legt ein zweidimensionalen Hash an aus jeweils einem Keyword und Bibkey des jeweiligen Dokuments. Damit entsteht ein Hash in der jedes Keyword nur genau ein mal einthalten ist und beliebig viele Bibkeys als Wert dem Bibkey zugeordnet sind.
3 Durch das Array mit allen Stichwörtern wird nun traversiert und ein Hash erzeugt, mit den Stichwörtern als Key. Als Wert wird der Einfachheit halber einfach ein X an die Zeichenkette angeängt. Damit könnte bei Bedarf die Häufigkeit des Stichworter über die Länge der Zeichenkette ausgelesen werden. Ergebnis ist ein Hash in dem jedes vorkommende Stichwort genau ein mal existiert. Anschließend werden die Hash-Keys alphabetisch sortiert.
4 Hier wird durch den Hash mit den Stichwörtern traversiert und im wwwroot ein passendes Unterverzeichnis samt index.html mit einem Header erzeugt
5 Zuerst wird durch den Hash für Stichworte traversiert und je ein Stichwort extrahiert und normalisiert. Anschließend werden der Bibkey und der jeweilige Titel des Werkes aus dem Hash geholt und als HTML-Link in die entsprechende index.html im Verzeichnis des Stichwortes abgelegt.

Mithilfe verschiedener Perl-Skripte kann so die BibTeX-Bibliographie geparsed und in verschiedenen Formaten formatiert werden. So wird automatisch eine Übersicht über unsere eigenen Dokumente sortiert nach Aktenzeichen erzeugt, ebenso können thematisch sortierte Seiten erzeugt werden oder wie im Skript oben gezeigt eine Webseite die alle Stichwörter als Einstieg in die Navigation nutzt.

Die Daten dazu werden entweder als simple TXT-Datei, direkt als einfaches HTML oder wieder in AsciiDoc exportiert und dann mittels AsciiDoctor in schick formatiertes HTML umgewandelt.

Ein zentrales Glossar samt Stichwortverzeichnis pflegen

Asciidoc kommt mit einer eingebauten Syntax für ein Glossar.

Lemma

Die Erklärung des Lemmas

Glossar

ein spezielles Wörterverzeichnis, in dem erläuterungsbedürftige Wörter bzw. Begriffe erklärt werden

Im Text interpretiert sieht dies so aus:

Glossar ein spezielles Wörterverzeichnis, in dem erläuterungsbedürftige Wörter bzw. Begriffe erklärt werden

Da wir in vielen Dokumenten ein Glossar einbinden, pflegen wir dieses ebenfalls zentral im Gitlab. Dies erfolgt in einem Unterverzeichnis unseres Vorlagen-Verzeichnisses. Dort wird für jeden Glossareintrag eine eigene Datei mit dem Lemma als Dateinamen angelegt. In dieser Datei wird das Lemma in AsciiDoc-Syntaxe erläutert und kann dann bei Bedarf über einen Include-Befehl eingebunden werden. Dies spart nicht nur Arbeit beim definieren bzw. erläutern der Einträge, sondern sorgt auch für eine zentralisierte Wissensdatenbank und damit für synchronisierte Begriffe.

Neben dem Glossar unterstützt AsciiDoc auch noch ein Stichwortverzeichnis bzw. Index. Dieses wird in der Regel ans Ende des Dokumentes gehängt und verweist auf die Seitenzahl(en), auf denen das Stichwort auftaucht und benutzt wird.

Ein Index ist in größeren Dokumenten nützlich, um schnell relevante Seiten zu finden.

Stichwörter können dabei sichtbar oder unsichtbar im Text markiert werden. Sichtbare Stichwörter werden in zwei runden <span class="indexterm" primary="Index-Klammern"></span>Index-Klammern geklammert. Das Wort erscheint dann so im Text und im Index.

Mittels dreifacher Klammerung können Stichwörter erfasst werden, die so nicht im Fließtext erscheinen. Dabei ist es möglich, bis zu 2 zusätztliche Gliederungsebenen zu erzeugen, um Kategorien zu bilden.

<span class="indexterm" primary="Datenbank" secondary="SQL" tertiary="PostgreSQL"></span> <span class="indexterm" primary="Datenbank" secondary="SQL" tertiary="MySQL"></span> <span class="indexterm" primary="Datenbank" secondary="KeyValue" tertiary="Redis"></span> <span class="indexterm" primary="Datenbank" secondary="KeyValue" tertiary="ValKey"></span>

Im Text "versteckt" stehen folgende Index-Einträge:

(((Datenbank,SQL,PostgreSQL)))
(((Datenbank,SQL,MySQL)))
(((Datenbank,KeyValue,Redis)))
(((Datenbank,KeyValue,ValKey)))

Im folgenden Unter-Kapitel wird zu Demonstrationszwecken das Stichwortverzeichnis ausgegeben.

Beide Möglichkeiten - Glossar und Index - lassen sich für das zentrale Architektur-Glossar nutzen.

(((Nutzer,angelegter)))
[[angelegterNutzer]]
Angelegter Nutzer::
Ein angelegter Nutzer ist ein Konto im System, das spezifische Zugriffsrechte und Rollen erhält, um auf bestimmte Ressourcen oder Dienste zuzugreifen. Der Prozess der Provisionierung beinhaltet die Zuweisung von Authentisierungsdetails und die Einrichtung notwendiger Dienste für den Nutzer. Die Provisionierung sichert die Einhaltung von Sicherheits- und Geschäftsanforderungen sowie die grundsätzliche Möglichkeit der Systemnutzung zu.
  1. <1> Der "versteckte" Index-Eintrag mit 2 Ebenen

  2. <2> Ein Verweisanker, damit kann im Text auf diese Zeile verwiesen werden

  3. <3> Die Glossar-Definition

Über einen normalen Include-Befehl ìnclude::../Glossar/Nutzerangelegter.adoc kann die Definition dann eingebunden werden. Bindet man im Dokument ein Glossar und/oder Index ein, erscheinen die Einträge dort.