Aneamal-Version 2017-K08

Die Aneamal-Version 2017-K08 steht zum Herunterladen bereit. Selbst für mich als Entwickler ist das zum jetzigen Zeitpunkt überraschend, denn die vorhergehende Aktualisierung liegt nur etwas mehr als einen Monat zurück. Doch der Schritt wurde aufgrund eines Bruches bei MathJax, welches als einzige externe Komponente in Aneamal zum Anzeigen von Formeln vorkonfiguriert ist, nötig.

Davon abgesehen enthält diese Aneamal-Version aber eine ganze Reihe von Neuerungen, die das Potenzial der Auszeichnungssprache erweitern oder bei Umwandlung in eine Webseite für ausdrucksstärkeres, barrierefreieres HTML sorgen. Die Aktualisierung lohnt sich also auch für Nutzer, die gar nicht auf mathematische Formeln zurückgreifen.

Auf dieser Seite stelle ich ausgewählte Änderungen vor und beschreibe, welche Anpassungen bei Aktualisierung von der vorigen Aneamal-Version 2017-H02 empfehlenswert sind. Eine Liste aller Änderungen findet sich in der Versionsgeschichte.

Neu: Heredocs

„Heredocs“ sind so etwas wie Pseudodateien. Es sind Abschnitte in einem Aneamaldokument, die – bis auf technisch bedingte Details – so behandelt werden, als stünden sie in einer externen Datei. Hier ist ein Heredoc-Beispiel:

[h]
|<svg xmlns='http://www.w3.org/2000/svg' width='120' height='120'>
|<circle cx='60' cy='60' r='50' stroke='none' fill='blue' />
|</svg>

Das ist äquivalent zur HTML-Dateieinbindung:

[h]->kreis.svg

mit einer Datei kreis.svg, die folgenden Inhalt besitzt:

<svg xmlns='http://www.w3.org/2000/svg' width='120' height='120'>
<circle cx='60' cy='60' r='50' stroke='none' fill='blue' />
</svg>

Das Ergebnis wäre also:

Heredocs können für die Dateitypen [a], [b], [d], [h], [p], [q], [t] sowie für die Metaangabe @style, die neue Metaangabe @script und für Platzhalterdefinitionen verwendet werden. Hier ein Syntaxbeispiel für die Anwendung in Metaangaben:

@ style
@ |h1 {color: red}

Neu: Aneamalvorlagen

In Aneamalvorlagen kann man Metaangaben hinterlegen, die dann beim Einbinden einer anderen Aneamaldatei (oder eines Heredocs) übernommen werden. Das ist sinnvoll, wenn man oft die gleichen Stilangaben benötigt. Man braucht sie dann nicht jedes Mal neu angeben, sondern lässt sie aus einer Vorlage abrufen.

Vorlagen speichert man als /aneamal/a–vorlagenname.nml ab. So könnte die Vorlage namens warnung unter der Adresse /aneamal/a-warnung.nml zum Beispiel folgende Metadaten enthalten:

@ class: caution
@ style
@ |.caution p {
@ |    background: yellow;
@ |    border: 3px solid black;
@ |    padding: 1em;
@ |}

Im folgenden Beispiel wird ein Heredoc geladen und dabei die Vorlage warnung verwendet:

[a:warnung]
|Lassen Sie Ihren Hund niemals unbeaufsichtigt mit Kinderdönern spielen!

Das Ergebnis:

Lassen Sie Ihren Hund niemals unbeaufsichtigt mit Kinderdönern spielen!

Derzeit können Vorlagen nur Metadaten und Kommentare enthalten.

Miniseiten → Zitatblöcke

Wenn man > am Absatz- und jedem Zeilenanfang schrieb, erzeugte das bislang eine Miniseite. Fügte man noch Zeilen ohne > am Zeilenanfang an, wurde daraus eine Beschriftung. Hier ein Beispiel:

> Der Hund braucht sein Hundeleben.
> Er will zwar keine Flöhe haben,
> aber die Möglichkeit, sie zu bekommen.
Robert Lembke

Nach HTML wurde dies bislang in etwa so übersetzt:

<div class='_minipage'>
Der Hund braucht sein Hundeleben.
Er will zwar keine Flöhe haben,
aber die Möglichkeit, sie zu bekommen.
</div>
<div class='_caption'>Robert Lembke</div>

Der Aneamaltext ist weiterhin gültig, wird nun aber als Zitatblock in etwa so nach HTML übersetzt:

<blockquote>
Der Hund braucht sein Hundeleben.
Er will zwar keine Flöhe haben,
aber die Möglichkeit, sie zu bekommen.
<footer>Robert Lembke</footer>
</blockquote>

Dabei handelt es sich um ausdrucksstarkes HTML, das den Text klar als Zitat kennzeichnet und mit der Beschriftung verknüpft. Gegebenenfalls musst Du infolge dieser Verbesserung deine CSS-Dateien so anpassen, dass die bisher für ._minipage hinterlegten Angaben nun für blockquote und die für ._caption hinterlegten Angaben für blockquote > footer gelten.

Falls Du die bisherigen Miniseiten für andere Dinge als Zitate nutztest, kannst Du stattdessen [a]-Heredocs einsetzen, vielleicht sogar mit einer Vorlage.

Quelltextblöcke

Ausdrucksstärker ist nun auch die Übersetzung von Quelltextblöcken mit | am Absatz- und jedem Zeilenanfang. Statt mit <pre>…</pre> werden sie in HTML mit <pre><code>…</code></pre> umgesetzt.

Mehrfachauswahl

Ebenfalls aussdrucksstärker und damit barrierefreier ist nun die Übersetzung von Auswahlboxen nach HTML. Nehmen wir das Beispiel:

Welchen Buchstaben möchtest Du?

{ } B
{ } Ä
{ } R

Dies wurde bislang in etwa so nach HTML übersetzt:

<p>Welchen Buchstaben möchtest Du?</p>
<p>
<input id="_1" value="" type="checkbox"> <label for="_1">B</label><br>
<input id="_2" value="" type="checkbox"> <label for="_2">Ä</label><br>
<input id="_3" value="" type="checkbox"> <label for="_3">R</label>
</p>

Statt mit <p>…</p> werden die Auswahloptionen nun mit <fieldset>…</fieldset> gruppiert, was sie als zusammengehörige Formularelemente kennzeichnet. Noch besser ist aber, wenn man die Leerzeile zwischen der Frage und den Optionen weglässt. Dann wird nämlich die Frage auch per HTML eindeutig mit den Antworten verknüpft, was es zum Beispiel Sehbehinderten einfacher macht, die Struktur der Seite zu verstehen:

Welchen Buchstaben möchtest Du?
{ } B
{ } Ä
{ } R

Dies wird nun in etwa so übersetzt:

<fieldset>
<legend>Welchen Buchstaben möchtest Du?</legend>
<input id="_1" value="" type="checkbox"> <label for="_1">B</label><br>
<input id="_2" value="" type="checkbox"> <label for="_2">Ä</label><br>
<input id="_3" value="" type="checkbox"> <label for="_3">R</label>
</fieldset>

Diese Verbesserung setzt eine Richtlinie für barrierefreie Netzinhalte um. Zu beachten ist dabei allerdings, dass Browser standardmäßig <fieldset> und <legend> in besonderer Weise darstellen. Eine unauffälligere Darstellung, die der bisherigen entspricht, erhältst Du, wenn Du Deinen Stilangaben so etwas beifügst:

fieldset {
    border: none;
    margin: 1em 0;
    padding: 0;
}
legend {
    padding: 0 0 1em;
}

MathJax

Der Aneamal-HTML-Konverter übersetzt mathematische Formeln nicht selbst in eine für Webseiten taugliche Darstellung, sondern überlässt das MathJax. Dafür ist aneamal-config.php seit Herbst 2015 vorkonfiguriert. Überraschend hat MathJax.org am 31. März 2017 angekündigt, ihr CDN nach Ablauf einer Monatsfrist abzuschalten. Das heißt, dass MathJax nicht mehr direkt aus Webseiten von den zu MathJax gehörenden Servern abgerufen werden kann.

MathJax empfiehlt einen alternativen CDN eines anderen Anbieters. Demnach muss in der Datei aneamal-config.php mindestens die Zeile

$source = 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML';

mit der folgenden ersetzt werden:

$source = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS_HTML';

In der Datei aneamal-config.php der neuen Version ist der Austausch des CDNs zusammen mit weiteren Änderungen an der MathJax-Konfiguration bereits erledigt. Wenn Du Deine alte aneamal-config.php behalten möchtest, müsstest Du Dich darum aber selbst kümmern.

Unter anderem da es keinerlei Garantie gibt, dass das neue CDN nicht ebenfalls plötzlich abgeschaltet wird, empfehle ich allerdings, MathJax neben Aneamal auf dem eigenen Server einzurichten. Abgesehen von Speicherplatz gibt es dafür keine Systemanforderungen. Wie man MathJax, das unter der freien Apache-2.0-Softwarelizenz steht, kostenlos beziehen kann, wird auf mathjax.org beschrieben.

Mittelfristig ist geplant, eine aufs Nötigste reduzierte MathJax-Installation für Aneamal hier schon bereitzustellen. Dies war leider zum jetzigen Zeitpunkt noch nicht möglich.