AKFFAQ-FAQ

AKFFAQ ist eine einfache, XML-basierte Sprache, mit der man FAQs schreiben kann.

FAQ steht für „Frequently Asked Questions“ , zu deutsch etwa „Häufig gestellte Fragen“ . Ob diese Fragen wirklich häufig gestellt werden, ist ein ganz anderes Thema, Einige Leute, so wie ich, mögen einfach nur diesen Schreibstil.

AKFFAQ könnte für alles Mögliche verwendet werden, wo es Fragen gibt, oder Behauptungen, und Antworten darauf gegeben werden sollen. Zum Beispiel auch für Interviews oder um Fehleinschätzungen zu widerlegen.

Alpha — Das heißt, es befindet sich noch in der Entwicklung und verändert sich eventuell noch...

http://akfoerster.de/akffaq/

Nein. Nur diese FAQ. ☺

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE akffaq SYSTEM "akffaq.dtd">
<?xml-stylesheet type="text/xsl" href="akffaq.xsl"?>

<akffaq>

<section>
<question id="gruss">
Wollen Sie noch jemanden grüßen?
</question>

<answer>
Hallo Welt!
</answer>
</section>

</akffaq>

Die ersten drei Zeilen mögen am Anfang zwar etwas kompliziert wirken, aber keine Angst, für den Anfang kann man sie einfach so übernehmen, wie sie sind. Die Zeilen sind nicht immer notwendig, aber es ist besser sie drin zu haben, nur für den Fall.

Zu beachten ist, dass es mindestens einen Abschnitt ( „section“ ) geben muss. Wenn man mehre verwenden will, sollte man noch „id“ - und „title“ -Attribute mit angeben.

Diese Zeile stellt klar, dass es sich um eine XML-Datei handelt. Die Zeile ist nicht unbedingt nötig, aber wenn man sie weglässt, muss der Text in UTF-8 oder UTF-16 gespeichert sein.

Der Parameter „version“ zeigt die Version der XML-Spezifikation an. Es handelt sich nicht um die Versionsnummer der FAQ und es ist auch nicht die Version von AKFFAQ. Man sollte hier immer 1.0 verwenden und nichts anderes.

Der Parameter „encoding“ hingegen meint die Zeichensatz-Kodierung der vorliegenden XML-Datei. UTF-8 ist eine gute Wahl für so ziemlich jede Sprache. Falls der verwendete Text-Editor jedoch kein UTF-8 unterstützt, kann man hier den verwendeten Zeichensatz eintragen. Auf älteren Systemen wird zum Beispiel häufig „ISO-8859-1“ verwendet.

Wenn man die Datei aber als UTF-8 speichern kann, sollte man das auch tun.

Die „DOCTYPE“ -Zeile verweist auf die „Dokumenten-Typ-Definition“ (DTD). Die DTD-Datei „akffaq.dtd“ ist die maschinenlesbare Spezifikation des AKFFAQ-Formates. Diese Datei wird von einigen Programmen verwendet, um die Datei auf formale Fehler hin zu überprüfen. Man sollte jedoch beachten, dass viele Programme das nicht tun.

In der DTD-Datei können auch Definitionen für sogenannte „Entities“ sein. Zum Beispiel definiert die Datei „akffaq.dtd“ &smiley; für einen Smiley (☺). Leider lesen einige Programme die DTD-Datei überhaupt nicht, so dass das nicht immer funktioniert ☹ Aber es gibt da einen Hack, um das Problem zu umgehen...

Die verweist auf die Datei „akffaq.xsl“ . Und diese Datei ist es, wo die eigentliche Arbeit von AKFFAQ geleistet wird.

Tatsächlich bin ich der Meinung, dass „Stylesheet“ eine ziemlich falsche Bezeichnung ist. Es handelt sich vielmehr um ein Skript, dass die XML-Datei nach HTML umwandelt. Das ist nicht nur eine einfache Übersetzung, sondern es ist eine eigentlich richtige kleine Programmiersprache. Damit können auch viele Dinge automatisiert werden. Zum Beispiel wird bei AKFFAQ auch das Inhaltsverzeichnis automatisch erstellt.

Neuere Webbrowser können die XML-Datei mit diesem Skript auch direkt anzeigen. Man kann aber auch externe Programme verwenden, um es nach HTML umzuwandeln, so dass auch ältere Browser unterstützt werden.

Auf den meisten GNU/Linux Systemen ist bereits das Programm „xsltproc“ vorinstalliert. Man kann es folgendermaßen anwenden: xsltproc akffaq.xsl myfaq.xml > myfaq.html.

Für weitere Infomationen siehe http://xmlsoft.org/XSLT/xsltproc.html.

Die „id“ sollte ein nur einmal verwendetes Kennwort für die Frage oder der Abschnitt sein. Sie sollte kurz sein und keine Leerzeichen enthalten. Man kann aber Bindestriche oder das Unterstrich-Zeichen in dem Bezeichner verwenden.

Dieser Bezeichner wird für den automatischen Überblick in der HTML-Ausgabe verwendet. Man kann es auch verwenden, um von anderen Webseiten auf eine bestimmte Frage oder einen bestimmten Abschnitt zu verweisen.

Wenn man die „id“ weg lässt, wird falls nötig automatisch ein Bezeichner generiert. Das funktioniert für den automatisch erstellten Überblick. Aber das ist nicht so gut für Links von anderen Seiten, da der Bezeichner sich von mal zu mal verändern kann.

Wenn man einen automatisch erstellten Überblick in der HTML-Ausgabe haben möchte, kann man den Befehl <overview back="zurück"/> entweder vor den ersten Abschnitt, oder hinter dem letzten einfügen.

Zu beachten ist, dass da ein Schrägstrich vor der schließenden spitzen Klammer eingefügt werden muss.

Mit dem Attribut „back“ kann man den Namen für die Links zurück festlegen. Man kann auch back="zurück zum Überblick", oder sowas schreiben.

Man kann eine Überschrift zum Beispiel so hinzufügen: <heading>Über dieses und jenes</heading>. Diese Zeile solle man direkt hinter das öffnende <akffaq> einfügen.

Indem man jeden Absatz in <p>...</p> einbettet.

Im Gegensatz zu HTML muss dieses grundsätzlich immer paarweise verwendet werden. Man kann nicht einfach das schließende „</p>“ auslassen. Wenn man es verwendet, dann sollte man es auch konsequent verwenden.

Achtung: Fragen können nicht in Absätze unterteilt werden.

Es gibt da zwei Möglichkeiten.

Zum Einen kann man Links zum Beispiel so angeben: <link>http://akfoerster.de</link>. Dabei ist das Ziel das Links auch gleichzeitig der angezeigte Text.

Wenn man einen Text verlinken will, kann man das aber auch ähnlich wie in HTML machen:

<a href="http://akfoerster.de">Andreas K. Förster</a>.

Man kann Text hervorheben, indem man ihn mit <em>...</em> einschließt. Code-Teile können mit <code>...</code> markiert werden. Längere Code-Blöcke können mit <code-block>...</code-block> gekennzeichnet werden. Für Tastatur-Eingaben kann man <kbd>...</kbd> verwenden.

Nein. Ich habe viele Tags ähnlich zu HTML konzipiert um es für Benutzer, die bereits HTML kennen, einfacher zu machen und weil es einfacher ist das so nach HTML zu konvertieren. Aber man kann nur die Tags und Attribute verwenden, die speziell für AKFFAQ definiert wurden.