caption

Ein Plugin zum besseren Setzen von Abbildungen und Tabellen, insbesondere der entsprechenden Abbildungsunter- und Tabellenüberschriften.

Gerade aus einer LaTeX-Perspektive geschaut ist die bisherige Handhabung von Abbildungen und Bildunterschriften im DokuWiki nicht wirklich brauchbar (bzw. nicht gelöst). Der direkt mit dem Bild angebbare Alternativtext ist zwar aus HTML-Sicht gut und notwendig, aber als Abbildungsunterschrift unbrauchbar.

NEU: Ab sofort auch auf GitHub verfügbar: https://github.com/tillbiskup/dokuwiki-caption

Syntax

Das Plugin stellt grundsätzlich zwei verschiedene Syntax-Elemente bereit, vergleichbar dem blockquote-Plugin:

  • <figure>…</figure>, <table>…</table>
  • <caption>…</caption>

Dabei sollte <caption>…</caption> immer nur innerhalb einer der beiden anderen Umgebungen verwendet werden.

Anmerkung: Abbildungen haben immer Unterschriften, Tabellen immer Überschriften. Entsprechend muß man dann die caption-Umgebung positionieren.

Innerhalb der Syntaxelemente ist fast jedes weitere DokuWiki-Markup erlaubt.

Die caption-Umgebung sorgt für eine automatische Nummerierung und die Ausgabe des Strings „Abb.“ bzw. „Abbildung“ (und entsprechend für die Tabellen).

Ob die abgekürzte oder ausgeschriebene Schreibweise verwendet werden soll, kann über die Konfigurationsoberfläche des Plugins eingestellt werden. Die jeweiligen Strings sind lokalisiert, Lokalisierungen für Deutsch und Englisch sind momentan vorhanden, weitere lassen sich bei Bedarf sehr einfach nachinstallieren1).

Hinweis: Im DokuWiki ist innerhalb einer <caption> fast alles erlaubt, allerdings sollte man sich dessen bewußt sein, daß z.B. Fußnoten innerhalb einer Gleitumgebung in LaTeX nicht erlaubt sind.2)

Labels und Referenzen

Da die Abbildungen und Tabellen durch das Plugin automatisch durchnummeriert werden, gibt es den Bedarf, genauso automatisch im Text auf diese Abbildungen/Tabellen verweisen zu können, ohne jedesmal beim Umgruppieren der Abbildungen/Tabellen alle Referenzen von Hand abändern zu müssen.

Die ursprüngliche Einschränkung durch den Parser, daß nur Referenzen auf bereits definierte Abbildungen/Tabellen aufgelöst wurden, wurde mittlerweile behoben3).

Die Syntax sieht wie folgt aus:

<figure label>
...
</figure>

...

{{ref>label}}

Analog gilt das für die Tabellen. D.h. das (optionale) Label wird im öffnenden Tag einer Abbildung/Tabelle definiert4) und über die Struktur

{{ref>label}}

darauf verwiesen. Dabei wird bei der Referenz nicht zwischen Abbildungen und Tabellen unterschieden, sie gibt ausnahmslos (wie der entsprechende LaTeX-Befehl \ref{}) die zugehörige Zahl aus. Diese Zahl ist gleichzeitig ein Link auf die entsprechende Abbildung/Tabelle.

Hinweis: Ist für eine Abbildung/Tabelle ein Label definiert, wird das als „hover“-Text („Tooltip“) angezeigt, wenn man sich mit der Maus über den entsprechenden Beginn der jeweiligen Beschriftung („Abb[ildung] n“/„Tab[belle] m“) bewegt.

Beispiel

Und so könnte das DokuWiki-Markup dann aussehen:

<figure>
{{:stuff:kuschelpanzer.jpg|Kuschelpanzer}}
<caption>**Der ultimative rosa Kuschelpanzer.** Jetzt muß ich doch endlich mal eine
Abbildungsunterschrift kreieren, in der auch ein paar //Formatierungen// vorkommen.
Grundsätzlich ist ja alles erlaubt((Fußnoten eigentlich auch?))</caption>
</figure>

Und das Ergebnis:

Beispiel für ein Bild mit Bildunterschrift

bzw. analog für eine Tabelle:

<table>
<caption>Und eine Tabellenüberschrift mit etwas **fettem Text**.</caption>
 
^ Heading 1 ^ Heading 2 ^ Heading 3 ^
| Some text | some more text | some less text |
| no idea what to write in here |||
| | But still some idea for here ||
 
</table>

Und das Ergebnis:

Beispiel für eine Tabelle mit Tabellenüberschrift

Styles

Die einzelnen Elemente sind weitestgehend separat ansprechbar und über Änderungen der CSS-Datei des Plugins anpaßbar.

Nachfolgend ist ein Beispiel für den vom Plugin erzeugten XHTML-Code mit der Angabe der entsprechenden Klassen.

<div class="figure">
  <div class="caption">
    <span class="captionno">Abbildung 2:</span> 
    <span class="captiontext">...</span>
  </div>
</div>

Grundsätzlich ist es wichtig, die Abbildungsunter- und Tabellenüberschriften so zu formatieren, daß sie sich möglichst klar vom umliegenden Fließtext unterscheiden lassen (insbesondere, wenn sie mehrere Absätze umfassen, was vielleicht seltener der Fall ist, aber durchaus vorkommen kann).

Konfiguration

Über die DokuWiki-Konfigurationsoberfläche kann eingestellt werden, ob die Über-/Unterschriften mit abgekürzten oder ausgeschriebenen „Labels“ beginnen („Abbildung“ vs. „Abb.“/„Tabelle“ vs. „Tab.“).

Die „Labels“ sind über die Standardlokalisierung der Plugins vorerst in Deutsch und Englisch vorhanden, können aber bei Bedarf auch für andere Sprachen ergänzt werden.

Code

Die jeweils neueste Version zum Herunterladen:

Bitte beachten: Nutzung auf eigene Verantwortung. Fehler und Sicherheitslücken sind nicht ausgeschlossen. Jeder, der Fehler entdeckt, wird herzlich gebeten, sie entsprechend via BugZilla (s.u.) zu berichten.

Bugs

Für Bug Reports gibt es mittlerweile BugZilla. Bitte Bugs dort eintragen (zum Bugs eintragen ist einmalig eine Registrierung mit einer gültigen Emailadresse notwendig).
1)
entsprechend den Richtlinien und Strukturen von DokuWiki für die Mehrsprachigkeit.
2)
Eine entsprechende automatische Handhabung von Fußnoten im Rahmen des dokulatex-Plugins innerhalb von Gleitumgebungen geht (zumindest im Moment) über die Möglichkeiten und das sinnvolle Maß an Programmieraufwand hinaus.
3)
Der „Trick“ ist etwas grob, da es sich um ein Suchen&Ersetzen im bereits geparsten Teil der aktuellen Seite handelt.
4)
Man achte auf möglichst kurze, prägnante, aber aussagekräftige Labels. Da dieselben Labels auch im Falle eines LaTeX-Exports in LaTeX verwendet werden, gelten alle Einschränkungen der LaTeX-Labels: keine Sonderzeichen wie Umlaute, keine Leerzeichen
de/software/dokuwiki/caption.txt · Zuletzt geändert: 2017/12/09 20:09 (Externe Bearbeitung)