Bessere Dokumentation als beameruserguide?

Über die beamer Anleitung

The BEAMER class, User guide ist die offizielle Anleitung zu beamer. Dieser ist auch klar strukturiert:

• 1 Introduction — Ein kurzer Überblick, was beamer ist, wie es entstanden ist, ein paar persönliche Hinweise der Autoren, wie die Anleitung zu lesen und zu verstehen ist und wie oder wo man ggf. Hilfe bekommt. Insbesondere für Menschen, die im Lesen von LaTeX-Anleitungen noch ungeübt sind, ist dabei Abschnitt 1.4 besonders wichtig. Darin wird beispielsweise erklärt wie die Syntax-Darstellungen zu verstehen sind, also beispielsweise dass bei

  \begin{somebeamerenvironment}[⟨optional arguments⟩]{⟨first argument⟩} ⟨environment contents⟩ \end{somebeamerenvironment}

  somebeamerenvironment eine beamer-Umgebung darstellt; [(optional argument)] ein optionales Argument ist; {(first argument)} ein normales Argument ist. Auch, wer bereits eine ausführliche Anleitung gelesen hat, sollte wissen, dass man optionale Argumente samt der eckigen Klammern weglassen darf, wenn man darüber nichts anzugeben hat. Ebenso sollte derjenige wissen, dass Argumente in geschweiften Klammern nicht optional sind, sondern zwingend, man diese also keinesfalls einfach weglassen darf.

• I Getting Startet — ein Teil, der eine Art Kurzeinführung darstellt.
  Zunächst wird die Installation beschrieben. Ursprünglich waren solche Infos für jeden Anwender wichtig. Heutzutage installiert man besser über den Paketmanager der TeX-Distribution (oder ggf. über den Paketmanager der Linux-Distribution, falls man die TeX-Live-Pakete der TeX-Distribution verwendet). Daher ist dieser Abschnitt heutzutage eher unwichtig.

  Es folgt ein kurzes Tutorium, in dem wesentliche Elemente von beamer an einem Beispiel gezeigt werden. Daran schließt sich eine kurze, zweiteilige Erklärung zum empfohlenen Vorgehen bei der Erstellung einer Präsentation an. Der erste Abschnitt befasst sich dabei mit dem technischen Vorgehen, der zweite mit stilistischen und inhaltlichen Fragen. Es sei mir die Bemerkung erlaubt, dass diese Zusammenfassung mit entsprechenden Anpassungen durchaus auch auf andere Dokumentarten anwendbar ist.

  Es folgt eine kurze Auflistung von Beispiel-Templates. Dabei wird auch erklärt, dass diese als Teil des Dokumentverzeichnisses von beamer jeweils in drei Sprachen vorhanden sind. Anfängern sei dringend empfohlen, diese Beispieldateien näher zu betrachten. Sie geben einen kurzen Einblick in verschiedene Anwendungsszenarien.

  Die abschließenden Lizenzbedingungen sind für den normalen Anwender dagegen vermutlich eher von geringem Interesse.

• II Building a Presentation — der Teil, in dem die Anwenderschnittstelle von beamer komplett erklärt wird. Hier wird also die Verwendung der Elemente von beamer erklärt. Dabei ist der Teil selbst ebenfalls stringent gegliedert. Zunächst befasst sich ein Abschnitt mit frames. Im nachfolgenden Abschnitt geht es dann darum, wie man frames mit Hilfe von overlays nicht als statische fertige Seiten darstellt, sondern schrittweise aufbaut und verändert. Danach geht es um globale Strukturen wie Titel, Abschnitte etc. sowie um ein paar beamer-Spezialitäten wie Lektionen. Daran schließt sich an wie diese globalen Strukturen interaktiv über Links miteinander verknüpft sind bzw. verknüpft werden können und wie man dabei ein paar beamer-Spezialitäten wie wiederholte frames oder Lupenfunktionen nutzen kann. Darauf folgenden dann sogenannte lokale Strukturen, also Strukturen innerhalb von frames und overlays, beispielsweise Listen, Hervorhebungen, Blöcke mit eigener Überschrift, theoremartige Strukturen, Kästen, Abbildungen und Tabellen, Unterteilung in Spalten, die Besonderheiten von verbatim-Ausgaben, Zitatumegebungen, Fußnoten, externe Bilder (nicht zu verwechseln mit Abbildungen!). Ein eigener Abschnitt beschäftigt sich mit Animationen. Hier sei mir die Bemerkung erlaubt, dass ich das noch nie verwendet habe, weil ich Animationen hauptsächlich als Ablenkung vom eigentlichen Inhalt betrachte. Nett als kurze Auflockerung aber nervig, wenn sie ständig irgendwo auf einer Seite herumflickern. Sound habe ich dagegen vor Jahren einmal verwendet, als es darum ging, einen Originalton im Original einzuspielen. Würde ich heute aber eher mit einem externen Link machen, damit ich unabhängig vom PDF-Viewer bin. Auch Übergänge zwischen einzelnen Seiten brauche ich eher nicht.

• III Changing the Way Things Look – der Teil, der die Programmiererseite von beamer behandelt. Hier geht es weniger darum, wie man Inhalte strukturiert, als darum, wie man die Form der Darstellung verändert. Hier werden die unterschiedlichen Abstraktionsstufen wie Themes, innere Themes, äußere Themes, Templates, Farbtemplates, Transparenz, Fonts und deren Zusammenhang oder Zusammenspiel behandelt.

• IV Supporting Material – ist der Teil, in dem es sehr wesentlich um das geht, was über die reine Präsentation hinaus geht. Das wären beispielsweise ein Handout, Notizen für den Vortragenden und sogar die Erstellung von klassischen Folien im Gegensatz an Stelle von oder zusätzlich zu einer heute üblichen Präsentation.

• V Howtos – ist eine thematisch in zwei Abschnitte unterteilte Auflistung von kurzen Hinweisen, wie man konkrete Anforderungen löst. Dieser Teil ist noch am ehesten in gewisser Hinsicht als unklar zu bezeichnen. Unklar ist dabei vor allem die Motivation des Autors und warum er bestimmte Dinge noch einmal explizit erwähnt andere aber nicht. Ich kann nur vermuten, dass vor allem der erste Abschnitt eine Art FAQ darstellt, entweder als Gedächtnisstütze für den Autor selbst oder weil es eben Punkte sind, die als Frage häufig an ihn herangetragen werden.

Wie man sieht, hat die Anleitung insgesamt eine durchdachte Struktur, die nach meinem Eindruck auch konsequent durchgehalten wird. Für Infos über das Herangehen an eine Präsentation schaut man in Teil I. Für die Erfassung der Inhalte schaut man in Teil II. Will man die Darstellung ändern, schaut man in Teil III. Für das ganze Beiwerk schaut man in Teil IV. Das ist üblicherweise auch die empfehlenswerte Reihenfolge bei der Erstellung einer Präsentation. Lediglich die Auswahl des Themes kann vor der Erfassung der Inhalte durchaus sinnvoll sein, weil unterschiedliche Themes unterschiedlich viel horizontalen und vertikalen Platz bieten. Änderungen an einem ausgewählte Theme nimmt man aber normalerweise erst vor, wenn man den Inhalt erfasst und noch Zeit übrig hat. Davon unabhängig kann irgendwann die Entwicklung eines eigenen Themes erfolgen – meist auf Basis dessen, was man bereits früher in einzelnen Präsentationen an Änderungen vorgenommen hat.

Von einem Durcheinander kann also objektiv nicht die Rede sein. Natürlich sind wir alle Individuen mit unterschiedlichen Voraussetzungen und Herangehensweisen. Daher kann subjektiv der eine Leser eine Anleitung als Katastrophe empfinden, die für andere perfekt geeignet ist. Gerade deshalb ist aber auch eine allgemeine Frage nach einer besseren Anleitung eben nicht allgemeingültig beantwortbar. Der Fragesteller muss schon konkrete Punkte bezüglich seiner Probleme und Anforderungen benennen, um überhaupt eine Chance zu haben, seine Auffassung von besser nachvollziehen und somit seinem Wunsch nachkommen zu können.

Nach meiner Erfahrung hat der subjektive Eindruck dabei aber auch sehr viel damit zu tun, ob ein Leser die Anleitung bestimmungsgemäß einsetzt und sich quasi vorab mit der Struktur der Anleitung befasst hat. Viele Anleitungen zu LaTeX-Paketen liest man am besten einmal mehr oder weniger gründlich durch, so dass man eine Ahnung hat, was wo steht. Bei Bedarf vertieft man das dann. Bei der beamer-Anleitung habe ich beispielsweise Teil II irgendwann weitgehend gelesen, Teil III dagegen nur überflogen und bei Bedarf dann konkrete Einzelfragen durch gezieltes und gründliches Nachlesen gelöst.

Das in der Frage dargestellte Problem

Bei dem in der Frage gezeigten Code:

\setbeamercolor{frametitle}{fg=white, bg=blue}
  \setbeamertemplate{frametitle}
  {
      \begin{beamercolorbox}[ht=30px, wd=\paperwidth,\insertframetitle
      \end{beamercolorbox}
  }

handelt es sich nach meinem Dafürhalten nicht um eine Problem aufgrund einer schlechten Struktur oder Erklärung oder gar fehlerhaften Beispielen in der beamer-Anleitung. Vielmehr sind hier mehrere schon fast typische Anfängerfehler versammelt:

• Das optionale Argument der Umgebung beamercolorbox wurde nicht korrekt mit ] beendet. Stattdessen befindet sich an der entsprechenden Stelle zwischen wd=\paperwidth und \inserframetitle fälschlich ein Komma.
• Das zwingende Argument beamer color von beamercolorbox, das in der Anleitung eindeutig angegeben und erklärt ist, fehlt. Dadurch wird auch beim Beheben des Klammerfehlers das erste Token aus der Expansion von \insertframetitle als beamer color interpretiert. Da die entsprechende Farbe in der Regel nicht existiert, geht die Ausgabe in die Hose.

Diese beiden Fehler lassen auf ein mangelndes Grundverständnis von LaTeX und TeX schließen. Obwohl die beamer-Anleitung eine Menge grundlegender Dinge erklärt, ist sie aber keine Einführung in LaTeX und soll dies auch eindeutig nicht sein. Es wird daher empfohlen, zunächst eine ausführliche LaTeX-Einführung zu studieren.

Eine Minimalkorrektur der Fehler (aber noch keineswegs eine ideale Darstellung) hat übrigens @saputello in einem Kommentar gezeigt:

* !TeX NONE
\setbeamertemplate{frametitle}
{
  \begin{beamercolorbox}[ht=30px, wd=\paperwidth]{frametitle}
  \insertframetitle
  \end{beamercolorbox}
}

Eine bessere Darstellung erhält man jedoch, wenn man die Template-Definition weglässt und nur die Farben einstellt:

\documentclass[12pt]{beamer}

\usepackage[ngerman]{babel}
\usepackage[T1]{fontenc}

\setbeamercolor{frametitle}{fg=white, bg=blue}
\begin{document}
\begin{frame}{Test}
Inhalt
\end{frame}
\end{document}

Bei dieser Gelegenheit seit auch erwähnt, dass man sich seit LaTeX 2018/04/01 die Angabe \usepackage[utf8]{inputenc} sparen kann.

Weitere Analysen und Hinweise

Darüber hinaus lassen Kommentare ein grundsätzliches Problem mit der englischen Sprache vermuten. Grundsätzlich ist Englisch die bevorzugte Sprache für primäre Anleitungen international eingesetzter OpenSource-Software. Es ist natürlich immer schön, wenn es auch Übersetzungen gibt. Man kann aber nicht von einzelnen ehrenamtlichen OpenSource-Entwicklern erwarten, dass sie neben der teils sehr komplexen Software auch noch Anleitungen in diversen Sprachen selbst erstellen, verwalten und aktuell halten. Der Aufwand ist kaum zu leisten. Irgend eine Sprache wird immer fehlen. Das Problem ist also nicht beamer bzw. dessen Anleitung oder Autor anzulasten, sondern allenfalls der Gemeinschaft aller Anwender (also auch mir und dir).

Abseits der beamer-Anleitung gibt es jedoch zusätzliche Literatur in unterschiedlichen Sprachen. Diese sind teilweise auf CTAN im Bereich Präsentation aufgeführt. Abseits davon gibt es diverse LaTeX-Bücher in deutscher Sprache. Allein in der Edition Dante sind inzwischen mehr als ein Dutzend Titel erschienen, die sich Teils allgemein mit LaTeX, Teils aber auch sehr speziell mit einzelnen Aspekten davon befassen. Darunter ist auch der Titel Präsentationen mit LaTeX gleich in Deutsch und Englisch zu finden.

Darüber hinaus bewährt es sich gerade für Anfänger in der Materie bei Problemen, bei denen sie alleine nicht weiter kommen, diese ganz konkret und strukturiert beispielsweise hier auf TeXwelt zu schildern. Dabei darf ein vollständiges Minimalbeispiel natürlich nicht fehlen. Oftmals hilft so eine strukturierte Schilderung auch dabei, die eigenen Gedanken zu ordnen. Mir selbst ist bei dem Versuch, ein Problem allgemeinverständlich zu machen, oftmals mein Brett vor dem Kopf heruntergefallen, so dass sich die Frage letztlich erübrigt hat. Auch konkrete Zitate aus einer Anleitung mit Schilderung, wie man das verstanden oder wo man dabei Verständnisprobleme hat, können sinnvoll sein. Auch das illustriert man am besten an einem konkreten Minimalbeispiel. Nicht selten ist ein kleines Missverständnis Auslöser für ein scheinbar riesiges Problem. Jedenfalls sind solche konkreten Problemschilderungen weit zielführender als irgendwelches Anleitungs-Bashing.