Differences

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

--- plugin:nstoc:deutsch [2015-11-30 13:21] – [Quellcode] 149.148.252.245
+++ plugin:nstoc:deutsch [2022-01-29 20:54] (current) – Moved to de:plugin:nstoc Klap-in
@@ Line 1: / Line 1: @@
-===== 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 ((aktuell werden die //Überschriften// in/von der Seite angezeigt.)) im aktuellen Bereich und allen nachgeordneten Bereichen (//alphabetisch geordnet!//)\\ 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- & 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 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ö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 ((d.h. die Dateien, aber //nicht// die H1-Überschrift-Zeilen)) 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 Position((oder Bedeutung)) 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 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 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>[[plugin_syntax#Reiehnfolge|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 [[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 Ü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 finden((Ausprobieren von [[http://www.dokuwiki.org/plugin:acl|ACL Plugin]].)). 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 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 Unterbereich. 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 gleichem Namen wie ein Unterverzeichnis)) 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 ([[#Benutzung|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?
-== 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 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 //relativen//((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.)).\\
-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 "''~~NOCACHE~~''" 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:
-  - Das [[http://dev.mwat.de/dw/syntax_plugin_nstoc.zip|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.
-  - Sicherstellen, dass das neue Verzeichnis und die darin enthaltenen Dateien vom Web-Server gelesen werden können mit 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]]
-==== Test UE4 ====
-==== 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]]