Erstellen einer offiziellen Dokumentation für die APF-Projekt-Webseite

1. Einleitung

Dieses Tutorial soll erklären, wie eine offizielle Dokumentations-Seite für die Projekt-Webseite adventure-php-framework.org erstellt werden kann. Es wird ausserdem aufgeschlüsselt, welche Seiten für eine fehlerfreie Darstellung notwendig sind.

2. Aufbau

2.1. Allgemeiner Aufbau

Eine Dokumentationsseite besteht immer aus zwei Dateien: Dokumentation mit dem eigentlichen Inhalt und der Navigation. Sämtliche Navigationsdateien werden im sepearaten Ordner "quicknavi" verwaltet.

2.2. Dateiname

Der Dateiname besteht aus einem Schema, womit unter anderem auch zwischen den APF-Versionen unterschieden werden kann. Nachfolgend ein Beispiel:

Code
c_de_151_1.X_filesystem.html

Welchen Nutzen nun die einzelnen Sektion, getrennt durch ein "_" (Unterschrich), haben, wird nochfolgend geschildert:

  • c: Typinformation: Inhalt oder Navigation (c - Inhalt, n - Navigation)
  • de: Sprachinformation (Deutsch)
  • 151: eindeutige ID der Dokumentationsseite)
  • 1.X: Versionsnummer, für die die Dokumentation verfasst wurde
  • X_filesystem: beliebiger Dateiname
Die Dateinamen für Dokumentation und Navigation müssen identisch sein. Es wird lediglich bei der Typenangabe ganz zu Beginn des Dateinamens zwischen Inhalt oder Navigation unterschieden!

2.3. Der Inhalt der Dokumentation

Für META-Angaben sowie die interne Suchfunktion wird der Kopf der Dokumantationsseite verwendet. Dafür steht das <doku:title />-Tag zur Verfügung. Ein Beispiel:

APF-Template
<doku:title parent="071" tags="docu,howto,documentation,create,dokumentation,erstellen" title="Erstellen einer offiziellen Dokumentation für die APF-Projekt-Webseite" urlname="Erstellen-einer-offiziellen-Dokumentation-fuer-die-Projekt-Webseite"> Dieses Tutorial soll erklären, wie eine offizielle Dokumentations-Seite für die Projekt-Webseite adventure-php-framework.org erstellt werden kann. </doku:title>
  • parent: übergeordnete Seiten ID (071)
  • tags: diverse Tags, welche u. a. als Meta-Keywords dienen
  • title: dient dem Title-Tag

Der Inhalt der Dokumentation kann beliebig ausgearbeitet werden. Dafür stehen alle HTML-Angaben zur Verfügung. Ausserdem gibt es einige Formatierungsmöglichkeiten, welche speziell für Hinweise oder Warnungen dienen sowie PHP-Code oder Konfigurationen lesbarer machen. Einige Beispiele:

Ich bin ein Hinweis. Für mich wird die CSS-Klasse "hint" benutzt.
Ich bin eine Warnung. Für mich wird die CSS-Klasse "warn" benutzt.
Code
"Ein einfacher String 123" Ich bin einfacher Code. Möchte man beispielsweise Strings ausgeben, eigne ich mich ideal dafür. Mich erzeugt man über den <gen:highlight />-Tag und dem Typ "code".
APF-Template
<html:placeholder name="xyz" /> Ich bin HTML-Code oder APF-XML-Code und eigne mich hervorragend für APF-Tags oder HTML. Mich erzeugt man über den <gen:highlight />-Tag und dem Typ "apf-xml".
PHP-Code
<?php echo 'Hallo!'; ?> Ich bin PHP-Code. Mich erzeugt man über den gen : highlight-Tag und dem Typ "php".
APF-Konfiguration
[de] foo = "bar" Ich bin eine Konfiguration und eigne mich bestens für alle INI-Dateien. Daher werde ich auch durch den <gen:highlight />-Tag mit dem Typ "ini" erzeugt.

Um der Dokumentation etwas Struktur zu verschaffen gibt es die unterschiedlichen Unterschrifts-Typen h3-h6. Diese müssen dann ebenso in der Navigation verlinkt werden.

Code

1. Kapitel 1

1.1. Kapitel 1.1

1.1.1. Kapitel 1.1.1
1.1.1.1. Kapitel 1.1.1.1

Es stehen ausserdem CSS-Klassen für Verlinkungen zur Verfügung. Dies wären:

APF-Template
class="external" - Externe Links class="forum" - Link ins Forum class="wiki" - Link zum WIKI

Interne Links, um beispielsweise auf andere Dokumentationen zu verweisen, lassen sich über einen speziellen Tag realisieren. Es ist dazu nur die Angabe der Seiten-ID erforderlich, umschlossen vom int:link-Tag:

APF-Template
<int:link pageid="154" />

2.4. Die Quicknavigation

Die Navigation ist nur eine Sammlung der einzelnen Kapitel der Dokumentation und verlinkt jeweils auf sie.

Es muss für jede Dokumentationsseite eine eigene Navigationsseite angelegt werden. Diese trägt den selben Dateinamen wie die Dokumenatation, abgesehen vom Anfang ("c" oder "n").