Differences

This shows you the differences between two versions of the page.

--- plugin:nstoc:deutsch [2010-11-04 16:07] – 80.149.40.70
+++ plugin:nstoc:deutsch [2022-01-29 20:54] (current) – Moved to de:plugin:nstoc Klap-in
@@ Line 1: / Line 1: @@
-====== NsToC Syntax PlugIn ======
-**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).
-===== Benutzung =====
-Der grundlegende Befehl ist:
-		{{nstoc }}
-Dieser Befehl erzeugt eine verschachtelte Liste aller Seiten ((aktuell werden die //Überschriften// in/von der Seite angezeigt)) im aktuellen Bereich und allen nach geordneten Bereichen. Bitte das Leerzeichen ((''space'', ASCII char #32; nicht zu verwechseln mit einem ''blank'', ASCII char #255)) 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 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.
-==== Hinweise ====
-Hier folgen einige Tipps, die für die Arbeit mit diesem PlugIn hilfreich sein können.
-=== 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 Wesen ((hoffe ich doch …)), 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):
-	- Preface
-	- Introduction
-	- First Chapter
-	- Second Chapter
-	- 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 ((d.h. die Dateien, aber //nicht// die H1-Überschrift-Zeile)) 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 ((oder Bedeutung)) innerhalb Ihrer Gesamtpräsentation) wählen.
-Wenn z. B. das erste Kapitel Ihres Buches mehrere Unterkapitel enthält, sollte der Bereich "''02_first_chapter''"((Beachte, dass //kein// Konflikt mit dem //Seiten//namen ''02_first_chapter'' entsteht, da der letztere intern eine Dateinamen-Erweiterung benutzt.)) 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.
-=== Zugängliche Seiten ===
-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((was immer das für Ihre individuelle Installation heißt)) konfiguriert, brauchen Sie sich keine Gedanken darüber zu machen, dass Ihren Nutzern – oder Einigen von ihnen – die Existenz von ihnen unzugänglichen Seiten angezeigt wird.
-Ein weiterer Vorteil liegt darin, dass Sie keine Seiten modifizieren müssen, die den "''nstoc''"-Befehl enthalten, wann immer Sie einen Bereich oder eine Seite hinzufügen.
-Zur Erläuterung dient wieder das Beispiel mit dem weiter oben beschriebenen virtuellen Buchprojekt ([[#Reihenfolge|s.o.]]).
-Angenommen, Sie haben das Vorwort und das zweite 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 03_second_chapter}}
-Nach einigen Wochen ist dann das erste Kapitel für die Öffentlichkeit fertig.
-Um den Zugriff zu ermöglichen, ändern Sie den Eintrag in der Übersichtseite wie folgt:
-		{{nstoc 00_preface}}
-		{{nstoc 02_first_chapter}}
-		{{nstoc 03_second_chapter}}
-Um später Kapitel Sieben frei zu schalten muss der Eintrag ergänzt werden:
-		{{nstoc 00_preface}}
-		{{nstoc 02_first_chapter}}
-		{{nstoc 03_second_chapter}}
-		{{nstoc 08_seventh_chapter}}
-Und so weiter ...
-Mit [[http://www.dokuwiki.org/wiki:acl|access control]] können Sie die Bereiche Ihres Buches für jeden außer Ihnen selbst als gesperrt initialisieren.
-In der Übersichtseite tragen Sie 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 finden((Ausprobieren von [[http://www.dokuwiki.org/plugin:acl|ACL Plugin]] kann hilfreich sein.)).
-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 [[http://www.dokuwiki.org/wiki:config#hidepages|'hidepages']]-Einstellung (d.h. ein regulärer Ausdruck((siehe "''man 7 regex''" für Einzelheiten))) entsprechen((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.)).
-=== 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 Sub-Bereich.
-Im Falle der Erzeugung einer TOC für einen Bereich mit weiteren Unterbereichen werden alle Seiten mit Stichwortverzeichnissen((d.h. Seiten mit dem Namen ''%%$conf['start']%%'' und Seiten mit dem gleichen Namen wie ein Unterverzeichnis)) ebenfalls ausgeschlossen.
-Diese Möglichkeit soll verhindern, dass Seiten indiziert werden, die bereits Teil von Übersichten sind.
-=== Wurzel 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 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.
-=== Numerische Namen für Bereiche ===
-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 ([[#Benutzung|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?
-=== Navigation ===
-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_important_points'' und Sie befinden sich im Bereich des zweiten Kapitels (d.h. in ''03_second_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 //relativen// 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/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 //relativen//((Bitte beachten, dass das ''pagemove'' PlugIn Probleme hat sowohl mit internen als auch relativen Links. Dies berührt den ''nstoc''-Befehl aber nicht, weil er von ''pagemove'' nicht erkannt wird.)).
-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.
-=== Änderungen überwachen ===
-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.
-===== Installation =====
-Es ist ganz einfach, dieses PlugIn in das DokuWiki zu integrieren:
-	- Das [[http://dev.mwat.de/dw/syntax_plugin_nstoc.zip|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.
-	- Sicherstellen, dass das neue Verzeichnis und die enthaltenen Dateien vom Web-Server gelesen werden können, z.B. <code>
-	chown apache:apache dokuwiki/lib/plugins/* -Rc
-</code>
-Der [[http://www.dokuwiki.org/plugin:plugin|PlugIn Manager]] kann genauso gut zur Installation oder zum Aktualisieren des PlugIn’s benutzt werden.
-===== Quellcode =====
-[[plugin:nstoc:#Plugin Source|Quellcode]]
-==== Präsentation ====
-[[plugin:nstoc:#Presentation|Präsentation]]
-==== Änderungen ====
-[[plugin:nstoc:#Changes|Änderungen]]
-===== Siehe auch =====
-[[plugin:nstoc:#See also|Siehe auch]]
-==== weitere PlugIn's vom selben Autor ====
-[[plugin:nstoc:#Plugins by the same author|weitere PlugIn's vom selben Autor]]
-===== Diskussion =====
-[[plugin:nstoc:#Discussion|Diskussion]]