Der Ausdruck namespace wird im Folgenden mit Bereich übersetzt.

Vor einiger Zeit startete ich ein Projekt, das eine Menge hierarchisch geordneter Seiten enthielt – wie ein Buch mit Kapiteln, Unterkapiteln und Paragraphen. Das Einfügen (und Aktualisieren jedes Mal, nach Seiten hinzufügen/entfernen/zusammenführen) der TOC-Referenzen war ein nötiger aber ziemlich stupider Job (also genau das, wozu Computer erfunden wurden). Nach mehrmaligem Ausführen dieser nervtötenden Aufgabe entschied ich mich dafür, dies zu automatisieren. — Enter “nstoc”.

Dieses PlugIn eröffnet die Möglichkeit, eine Table Of Contents (Inhaltsangabe) für einen Bereich mit wählbarer Verschachtelungstiefe zu erstellen. Es erzeugt eine (ggfs. verschachtelte) Liste aller Überschriftzeilen in allen passenden Seiten.

Man kann sagen, dieses PlugIn sieht ihr ganzes Wiki als ein großes Dokument, strukturiert durch Kapitel (Wiki Namensbereiche), Unterkapiteln (die einzelnen Seiten innerhalb eines Bereichs) und den zugehörigen Überschriften (H1…H5).

Der grundlegende Befehl ist:

	{{nstoc }}

Dieser Befehl erzeugt eine verschachtelte Liste aller Seiten ¹⁾ im aktuellen Bereich und allen nach geordneten Bereichen. Bitte das Leerzeichen ²⁾ hinter dem Schlüsselwort “nstoc” beachten: Fehlt es, greift die interne DokuWiki-Prozedur media ren­de­rer, welche hier meistens nicht erwünscht ist.

Um die Ausgabe auf – z.B.– 2 Ebenen zu beschränken, verwende

	{{nstoc 2}}

Das Ergebnis ist eine Liste mit allen H1 und H2 Überschriften in den Seiten aller Unterbereich des aktuellen Bereiches. Hingegeben ergibt

	{{nstoc 3}}

eine Liste mit allen H1/H2/H3 Überschriften in den Seiten des aktuellen Bereichs, alle H1/H2 Überschriften in den Seiten aller Unterbereiche des aktuellen Bereichs und alle H1 Überschriften in den Seiten aller Unter-Unter-Bereiche.

Durch die explizite Nennung des Bereichs kann die Ausgabe ebenfalls begrenzt werden:

	{{nstoc chapter2}}

Dies zeigt die Überschriften (ohne Begrenzung der Verschachtelungstiefe) im Bereich “chapter2”.

Man kann selbstverständlich die optionalen Argumente Bereich und Verschachtelungstiefe kombinieren:

	{{nstoc chapter3 1}}

Hier werden nur die H1 Überschriften der Seiten im “chapter3” Bereich angezeigt.

Hier folgen einige Tipps, die für die Arbeit mit diesem PlugIn hilfreich sein können.

Die erzeugte Ausgabe – oder, exakter: die Reihenfolge der erzeugten Liste – muss nicht immer so sein wie gewünscht. Der Grund dafür ist folgender: Wir als menschliche Wesen ³⁾, haben eine Vorstellung vom Sinn, während der Computer nur Daten kennt. Zur Verdeutlichung nehmen wir an, sie schreiben ein Buch. Zum jetzigen Zeitpunkt haben Sie folgende Seiten fertig (oder zumindest angelegt):

1. Preface
2. Introduction
3. First Chapter
4. Second Chapter
5. Appendix

Beim Einsatz von “nstoc” erwarten Sie höchst wahrscheinlich eine Liste in der gleichen Reihenfolge wie oben. Doch leider, das Ergebnis sieht wie folgt aus:

• Appendix
• First Chapter
• Introduction
• Preface
• Second Chapter

Nicht sehr sinnvoll, nicht wahr? — Die Ursache ist einfach: Das Einzige was DokuWiki und sein PlugIn kennen und sortieren, sind (Datei- und Bereichs-)Namen. Aber daraus folgt auch, diese Tatsache kann ganz einfach zum Vorteil ausgenutzt werden, indem die richtigen Seitennamen gewählt werden. Z. B. benennen Sie die Seiten ⁴⁾ wie folgt:

• 00_preface
• 01_introduction
• 02_first_chapter
• 03_second_chapter
• 99_appendix

Theoretisch kann man alle Buchstaben weglassen und nur die Zahlen nutzen. Aber ich denke, das treibt die Computerisierung Ihrer Arbeit ein bisschen zu weit. Jedenfalls, solange Seiten– und Bereichs-namen in der gewünschten Reihenfolge sortiert sind, ergibt “nstoc” die richtige, nützliche Ausgabe.

Nebenbei bemerkt: Dieses gilt ebenso für Bereichsnamen. Dies heißt, Sie sollten die Namen für Ihre Bereiche entsprechend der gewünschten Reihenfolge (d.h. entsprechend ihrer jeweiligen Position ⁵⁾ innerhalb Ihrer Gesamtpräsentation) wählen. Wenn z. B. das erste Kapitel Ihres Buches mehrere Unterkapitel enthält, sollte der Bereich “02_first_chapter”⁶⁾ heißen und die enthaltenen Seiten dann z.B. 01_first_subject“, ”02_second_subject“ usw. Natürlich sollte die Überschriften für die Leser etwas aussagekräftiger sein.

Ab dem Release 2007-01-08 dieses PlugIn’s werden alle, für den jeweiligen Benutzer/Leser nicht zugänglichen Seiten von der erzeugten Liste ausgeschlossen. Mit anderen Worten: Jeder Nutzer sieht eine TOC nur mit den für ihn aktuell verfügbaren Seiten. Dadurch kann es nicht dazu kommen, das beim Versuch eine – für den Nutzer gesperrte – Seite aufzurufen nur die “Zugriff verweigert”-Meldung erscheint.

Vorausgesetzt, Sie haben Ihre Zugriffskontrolle korrekt⁷⁾. Die Übersichtsseite des Buches muss nicht mehr angepasst werden – zumindest nicht der ”nstoc“-Befehl. Alles wird durch dieses PlugIn und die Zugriffskontrolle von DokuWiki kontrolliert.

Ab Version 2007-08-15 dieses PlugIn’s werden Seiten von der erzeugten Liste ausgeschlossen, die der globalen 'hidepages'-Einstellung (d.h. ein regulärer Ausdruck⁸⁾) entsprechen⁹⁾.

Wenn der Name nach dem ”nstoc“ Schlüsselwort auf einen vorgegebenen Seitennamen (d.h. ”start“ in einer unveränderten Doku­Wiki Installation) verweist, wird der jeweilige Bereich benutzt, um die TOC zu erzeugen, aber nicht die Seite. Das Gleiche geschieht, wenn Sie auf eine Seite zeigen mit gleichem Namen wie ein Sub-Bereich. Im Falle der Erzeugung einer TOC für einen Bereich mit weiteren Unterbereichen werden alle Seiten mit Stichwortverzeichnissen¹⁰⁾ ebenfalls ausgeschlossen. Diese Möglichkeit soll verhindern, dass Seiten zu indizieren, die bereits Teil von Übersichten sind.

In früheren Versionen musste der Wurzel-Bereich gesondert behandelt werden. Ab der PlugIn-Version 2007-08-12 wird der Wurzel-Bereich fast immer wie jeder andere Bereich behandelt. Mit dem Grund-Befehl

	{{nstoc }}

wird eine TOC erzeugt mit allen zugänglichen Seiten der DokuWiki-Installation.

Eine sauber strukturierte Installation vorausgesetzt, sind Seiten im Wurzel-Bereich höchst wahrscheinlich Ausgangspunkt für weitere Unterbereiche. Deshalb ist es vernünftig, ”nstoc“ im Wurzel-Bereich in einer erweiterten Form zu verwenden, wie

	{{nstoc intro_page}}
	{{nstoc ns1 2}}
	{{nstoc ns2 1}}
	{{nstoc ns3:ns3a}}

Diese Eingaben schließen Seiten im Wurzel-Bereich aus und zeigen nur die Überschriften in den angegebenen Unterbereichen.

Wie mir bekannt ist, benutzen einige Leute lieber numerische Namen für die Bereiche, wie ”1“, ”23“ or ”456“. Dies ist kein Problem für das PlugIn, allerdings muss der nstoc-Befehl sorgfältig gebildet werden. Ich hatte erwähnt (s.o.), dass die Angabe des Bereichs-Namens ausreicht, um alle Überschriften des Bereichs (einschl. der Unterbereiche) auszugeben ohne Begrenzung der Verschachtelungstiefe. Also:

	{{nstoc 23}}

sollte alle Überschriften anzeigen des Bereichs ”23“, oder? – Falsch: Das PlugIn interpretiert diese Angabe als die max. Verschachtelungstiefe des aktuellen Namenbereichs.

Um sicher zu stellen, dass das Argument ”23“ als Bereichsname erkannt wird, muss die Befehlsvariante mit zwei Argumenten benutzt werden, d.h.: die Verschachtelungstiefe muss mit angegeben werden:

	{{nstoc 23 4}}

Hier wird der Bereich ”23“ indiziert bis zu einer Tiefe von 4 Ebenen. – Einfach, oder?

Dieses PlugIn erlaubt auch die relative Addressierung der gewünschten Bereiche. Angenommen, in dem Buch-Beispiel gibt es einen Unterbereich im ersten Kapitel mit Namen 03_im­por­tant_points und Sie befinden sich im Bereich des zweiten Kapitels (d.h. in 03_se­cond_chapter). Nun möchten Sie Links für Ihre Leser bereit stellen zu den erwähnten Seiten. Sie können das tun mit einem absoluten Pfad wie

	{{nstoc :book:02_first_chapter:03_important_points 2}}

oder mit einer rela­tiven Pfadangabe wie

	{{nstoc ..:02_first_chapter:03_important_points 2}}

In diesem Beispiel macht das nur einen Unterschied von 3 Zeichen in der Befehlslänge aus. Allerdings, je tiefer die Bereiche verschachtelt sind, desto mehr Tipparbeit sparen Sie ein. Und – als zusätzlicher Bonus – der Einsatz von relativen Pfadangaben lässt solche Links intakt, wenn das ganze Buch an einen anderen Platz in DokuWiki verschoben wird: Wenn –z.B. – Sie entscheiden, den ganzen ‚“Buch“-Bereich zu verschieben/umzubenennenin den neuen my_books-Bereich mit dem neuen Namen big_bang (oder was auch immer), funktionieren die absoluten Pfadangaben nicht mehr, wohl aber die relativen¹¹⁾.

Neben DokuWiki's : (Doppelpunkt) Pfad-Trennzeichen erkennt dieses PlugIn auch das Standard UNIX / (Schrägstrich) Zeichen. Deshalb kann der zweite Befehl auch so geschrieben werden

	{{nstoc ../02_first_chapter/03_important_points 2}}

. Der aktuelle Bereich kann mit ./ addressiert werden, der Eltern-Bereich als ../ und der Wurzelbereich als /. Dies ist intuitiver, zumindest für solche, die an die Shell-Kommandozeile gewöhnt sind.

Zumindest solange, wie die zu indizierende Bereichs-/Seitenstruktur noch geändert werden kann, sollte die Anweisung ”~~NOCACHE~~“ in die Dateien (Seiten) aufgenommen werden, die den ”nstoc“-Befehl enthalten. Dies stellt sicher, dass die Nutzer immer eine aktuelle TOC-Version angezeigt bekommen.

Es ist ganz einfach, dieses PlugIn in das DokuWiki zu integrieren:

1. Das Quell-Archiv (~9KB) herunterladen und in das DokuWiki PlugIn Verzeichnis {dokuwiki}/lib/plugins entpacken.
   (Sicherstellen, dass enthaltene Unterverzeichnisse ebenfalls korrekt entpackt werden).
   Das Verzeichnis {dokuwiki}/lib/plugins/nstoc wird erstellt.
2. Sicherstellen, dass das neue Verzeichnis und die enthaltenen Dateien vom Web-Server gelesen werden können, z.B.

   	chown apache:apache dokuwiki/lib/plugins/* -Rc

Der PlugIn Manager kann genauso gut zur Installation oder zum Aktualisieren des PlugIn’s benutzt werden.