DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:nstoc:deutsch

NsToC PlugIn

(Inhaltsverzeichnis automatisch erstellen)

Dies ist eine auszugsweise Übersetzung der englischen Anleitung!

Syntax

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. → Just Enter “nstoc”.
Dieses PlugIn eröffnet die Möglichkeit, eine Table of Contents (Inhaltsverzeichnis) für einen Bereich mit wählbarer Verschachtelungstiefe zu erstellen und im Wiki-Dokument abzuspeichern. Es erzeugt eine (ggfs. verschachtelte) Liste aller Überschriftszeilen im gewählten Bereich.
Man kann sagen, dieses PlugIn sieht das ganze aktive Wiki als ein großes Dokument strukturiert durch Kapitel (Wiki Namensbereiche), Unterkapitel (die einzelnen Seiten innerhalb eines Bereichs) und den zugehörigen Überschriften (H1 … H5).

Benutzung

Der grundlegende Befehl ist:

  {{nstoc }}

Dieser Befehl erzeugt eine verschachtelte Liste aller Seiten 1) im aktuellen Bereich und allen nachgeordneten Bereichen (alphabetisch geordnet!)
Bitte das Leerzeichen2) hinter dem Schlüsselwort “nstoc” beachten: Fehlt es, greift die interne DokuWiki-Prozedur media renderer, 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- & H2-Überschriften in den Seiten aller Unterbereiche des aktuellen Bereichs.
Hingegen ergibt

  {{nstoc 3}}

eine Liste mit allen H1/H2/H3-Überschriften in den Seiten des aktuellen Bereichs, allen H1/H2-Überschriften in den Seiten aller Unterbereiche des aktiven Bereichs und allen H1-Überschriften in den Seiten aller Unter-Unterbereiche.
Durch die explizite Nennung des Bereichs kann die Ausgabe ebenfalls begrenzt werden:

  {{nstoc chapter 2}}

Dies zeigt die Überschriften (ohne Begrenzung der Verschachtelungstiefe) im Bereich “chapter 2”.
Man kann selbstverständlich die optionalen Argumente Bereich und Verschachtelungstiefe komibinieren:

  {{nstoc chapter3 1}}

Hinweise

Hier folgen einige hilfreiche Tipps für die Arbeit mit diesem PlugIn.

Behandlung von Leerzeichen in Überschriften

Leerzeichen in Überschriften müssen durch einen _ (Unterstrich) ersetzt werden, z.B.
in einem Link auf die Überschrift “Plugin Source” muss die Überschrift wie folgt angegeben werden: #Plugin_Source.

Reihenfolge

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 Wesen3), 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öchstwahrscheinlich 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- & Bereichs-)Namen.
Aber diese Tatsache lässt sich ganz einfach zum Vorteil ausnutzen, indem die richtigen Seitennamen gewählt werden. Z.B. benennen sie die Seiten 4) wie folgt:

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

Theoretisch kann man alle Buchstaben weglassen und nur die Zahlen benutzen. Aber ich denke, das treibt die Computerisierung ihrer Arbeit ein bisschen zu weit. Jedenfalls, solange Seiten- & Bereichs-namen in der gewünschten Reihenfolge sortiert sind, ergibt “nstoc” die richtige, nützliche Ausgabe.
Nebenbei bemerkt: Dieses gilt ebenso für Bereichsnamen. D.h. Sie sollten die Namen für Ihre Bereiche entsprechend der gewünschten Reihenfolge (d.h. entsprechend ihrer jeweiligen Position5) innerhalb Ihrer Gesamtpräsentation wählen. Wenn z.B. das erste Kapitel Ihres Buches mehrere Unterkapitel enthält, sollte der Bereich “01_first_chapter” heißen und die darin enthaltenen Seiten dann z.B. “01_first_object”, “02_second_object” usw. Natürlich sollten die Überschriften für Ihre Leser etwas aussagekräftiger sein.

Zugängliche Seiten

Ab der PlugIn-Version 2007-01-08 werden alle, für den jeweiligen Benutzer/Leser nicht zugänglichen Seiten von der erzeugten Liste ausgeschlossen. Mit anderen Worten: Jeder Nutzer sieht sein Inhaltsverzeichnis (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 korrekt6) konfiguriert, brauchen Sie sich keine Gedanken darüber zu machen, dass Ihren Nutzern - oder Einigen von ihnen - die Existenz von ihnen eigentlich unzugänglichen Seiten angezeigt wird.
Ein weiterer Vorteil liegt darin, dass Sie keine Seite modifizieren müssen, die den “nstoc”-Befehl enthalten, wann immer Sie einen Bereich oder eine Seite hinzufügen. Zur Erläutrung dient wieder das Beispiel mit dem weiter oben beschriebenen virtuellen Buchprojekt(<wrap box bggreen>s.o.</wrap>).
Angenommen, Sie haben das Vorwort und zwei weitere Kapitel fertig gestellt und arbeiten noch an den anderen Teilen. Jeder zufällige Leser soll nur die fertigen Seiten sehen können und nicht die unfertigen. Dann sollten Sie in der Übersichtseite Folgendes einfügen:

  {{nstoc 00_preface}}
  {{nstoc 02_second_chapter}}

Nach einigen Wochen ist dann das erste Kapitel für die Öffentlichkeit fertig. Um den Zugriff zu ermöglichen, ergänzen Sie den Eintrag in der Übersichtsseite wie folgt:
nstoc_00_preface

  {{nstoc 01_first_chapter}}
  {{nstoc 02_second_chapter}}

Um später z.B. Kapitel 7 frei zu schalten, genügt die Ergänzung:

  {{nstoc 00_preface}}
  {{nstoc 01_first_chapter}}
  {{nstoc 02_second_chapter}}
  {{nstoc 07_seventh_chapter}}

Und so weiter …
Mit access control können Sie die Bereiche Ihres Buches für jeden außer Ihnen selbst als gesperrt initialisieren. In der Übersichtsseite tragen Sie dazu ein:

  {{nstoc }}

Danach reicht es aus, bei Fertigstellung weiterer Seiten, die Zugriffskontrolle zu ergänzen mit einer Zeile wie:

  book:00_preface @ALL   1

oder was immer Sie angemessen finden7). Die Übersichstseite des Buches muss nicht mehr angepasst werden - zumindest nicht der “nstoc”-Befehl. Alles wird durch dieses PlugIn und die Zugriffskontrolle von DokuWiki kontrolliert.
Ab PlugIn-Version 2007-08-15 werden solche Seiten von der erzeugten Líste ausgeschlossen, die der globalen [http://www.dokuwiki.org/wiki:config#hidepages|'versteckte Seiten']]-Einstellung (d.h. ein regulärer Ausdruck8) entsprechen9).

Stichwortverzeichnis

Wenn der Name nach dem “nstoc”-Schlüsselwort auf einen vorgegebenen Seitennamen (d.h. “start” in einer unveränderten DokuWiki-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 Unterbereich. Im Falle der Erzeugung einer TOC für einen Bereich mit weiteren Unterbereichen werden alle Seiten mit Stichwortverzeichnissen10) ebenfalls ausgeschlossen. Dies soll verhindern, dass Seiten erneut indiziert werden, die bereits Teil von Übersichten (Inhaltsverzeichnissen) sind.

Wurzel(root)-Seite

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 voraus gesetzt, sind Seiten im Wurzel-Bereich höchst wahrscheinlich Ausgangspunkte 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 an.

Numerische Namen für Bereiche

Einige Nutzer setzen lieber numerische Namen für Bereiche ein, wie “1”, “23” oder “456”. Dies ist kein Problem für das PlugIn, allerdings muss der nstoc-Befehl sorgfältig gebildet werden. Wie bereits erwähnt (s.o.), reicht die Angabe des Bereichs-Namens aus, um alle Überschriften (einschl. der Unterbereiche) auszugeben ohne Begrenzung der Verschachtelungstiefe. Also:

  {{nstoc 23}}

sollte alle Überschriften des Bereich “23” anzeigen, oder? - Falsch: Das PlugIn interpretiert diese Angabe als die max. Verschachtelungstiefe des aktuellen Bereichs.
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 dem Namen 03_important_points und Sie befinden sich im Bereich des zweiten Kapitels (d.h. in 02_second_chapter). Nun möchten Sie Links für Ihre Leser bereitstellen zu den erwähnten Seiten. Sie können das tun mit einem absoluten Pfad wie:

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

oder mit einer relativen Pfadangabe wie:

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

In diesem Beispiel macht das in der Befehlslänge nur einen Unterschied von 3 Zeichen 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, auch wenn das ganze Buch an einen anderen Platz in DokuWiki verschoben wird: Wenn Sie z.B. entscheiden, den ganzen “Buch”-Bereich zu verschieben/umzubenennen in den neuen my_books-Bereich mit dem neuen Namen big_bang (oder was auch immer), funktionieren die absoluten Pfadangaben nicht mehr, wohl aber die relativen11).
Neben DokuWiki's Pfadtrennzeichen : (Doppelpunkt) erkennt dieses PlugIn auch das Standard-UNIX-Zeichen / (Schrägstrich). Deshalb kann der zweite Befehl auch so geschrieben werden:

  {{nstoc ../01_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.

Änderungen überwachen

Zumindest solange, wie die zu indizierenden Bereichs-/Seitenstrukturen noch Änderungen unterliegen können, sollte die Anweisung “” in die Dateien (Seiten) mit aufgenommen werden, die den “nstoc”-Befehl enthalten. Dies stellt sicher, dass die Nutzer immer eine aktuelle TOC-Version angezeigt bekommen.

Installation

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

  1. Das Quell-Archiv (~ 9 kB) 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 darin enthaltenen Dateien vom Web-Server gelesen werden können mit 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.

Quellcode

Präsentation

Änderungen

Siehe auch

weitere PlugIn's vom selben Autor

Diskussion

1)
aktuell werden die Überschriften in/von der Seite angezeigt.
2)
space, ASCII char #32; nicht zu verwechseln mit einem blank, ASCII char #255
3)
hoffe ich doch …
4)
d.h. die Dateien, aber nicht die H1-Überschrift-Zeilen
5)
oder Bedeutung
6)
was immer das für Ihre individuelle Installation heißt
7)
Ausprobieren von ACL Plugin.
8)
siehe “man 7 regex” für Einzelheiten'
9)
Beachte: dieses PlugIn zeigt nicht DokuWiki's Fehler in der Handhabung versteckter Seiten, wenn RegEx z.B. “0” ist, aber testet die $conf['hidepages']-Einstellung korrekt.
10)
d.h. Seiten mit dem Namen $conf['start'] und Seiten mit gleichem Namen wie ein Unterverzeichnis
11)
Bitte beachten, dass das pagemove-PlugIn Probleme hat, sowohl mit internen als auch relativen Links. Dies betrifft den nstoc-Befehl aber nicht, weil er von pagemove nicht erkannt wird.
plugin/nstoc/deutsch.txt · Last modified: 2015-11-30 13:21 by 149.148.252.245