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 stu pider 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 Doku-Wiki-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 Doku-Wiki 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⁹⁾ ebenfalls ausgeschlossen. Diese Möglichkeit soll verhindern, dass Seiten zu indizieren, 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 Doku-Wiki-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 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 (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_im­por­tant_points und Sie befinden sich im Bereich des zweiten Kapitels let's sup­pose you're in the name­space of the second chapter (i.e. in 03_se­cond_chapter). Now you'd like to pro­vide links to the men­ti­oned pages for your rea­ders. You could do this by either use an abso­lute path like 03_important_points_2 or use a rela­tive path like 03_important_points_2 With this example it's only a difference of 3 charac­ters. But the dee­per your na­me­spaces are nested the more you save ty­ping. And – as an addi­tio­nal bene­fit – using rela­tive paths lea­ves those links intact if you move the whole book to an­other place: If – for instance – you de­cide to move/re­name the whole book name­space into a new my_books name­space un­der the new name big_bang (or what­ever) the abso­lute path above would no lon­ger show any links while the rela­tive one will still work as ex­pected¹⁰⁾. Besides DokuWiki's : (colon) path sepa­rator this plugin allows the stan­dard UNIX / (slash) as well. Hence the se­cond exam­ple above could be writ­ten nstoc_.._02_first_chapter_03_important_points_2 as well. The respec­tive cur­rent name­space can be addres­sed as ./, the pa­rent name­space as ../ and the root name­space as /. This seems to be more intui­tive at least for those who are fami­liar with a shell com­mand­line. === Caching === At least as long as the name­space/page struc­ture you're in­dexing by this plugin is like­ly to change you should place the ”~~NOCACHE~~“ direc­tive in those fi­les (pa­ges) which con­tain the ”nstoc“ markup. That should make sure that the users al­ways get an actual/cur­rent TOC. ===== Installation ===== It's quite easy to integrate this plugin with your DokuWiki: - Download the source archive (~9KB) and un­pack it in your Doku­Wiki plug­in di­rec­tory {dokuwiki}/lib/plugins (make sure, in­clu­ded sub­di­rec­to­ries are un­packed cor­rect­ly); this will create the directory {dokuwiki}/lib/plugins/nstoc. - Make sure both the new direc­tory and the files therein are read­able by the web-server e.g.<code> chown apache:apache dokuwiki/lib/plugins/* -Rc </code> You might as well use the plugin manager for installing or updating this plugin. ===== Plugin Source ===== Quellcode ==== Presentation ==== The accompanying CSS presentation rules: <code css> div.level1 ul.nstoc,div.level2 ul.nstoc,div.level3 ul.nstoc,div.level4 ul.nstoc,div.level5 ul.nstoc,div.level6 ul.nstoc{margin:0;padding:0;} ul.nstoc{list-style-position:inside;list-style-type:none;font-size:100%;margin:0;padding:0;text-align:left;line-height:1.4;} ul.nstoc li{margin:0;padding:0 0 0 0.5ex;list-style-type:none;} ul.nstoc li.level1{margin-top:0.3ex;padding:0;font-size:111.1%;font-weight:500;font-variant:small-caps;letter-spacing:1pt;background:inherit;color:#000;} ul.nstoc li.level2{font-variant:normal;} ul.nstoc li.level3{letter-spacing:normal;} ul.nstoc li.level2,ul.nstoc li.level3,ul.nstoc li.level4,ul.nstoc li.level5,ul.nstoc li.level6,ul.nstoc li.level7,ul.nstoc li.level8{font-size:96.6%;padding-left:1.3ex;} ul.nstoc li a,ul.nstoc li a.wikilink1{background:inherit;color:#003;border:none;font-size:inherit;font-variant:inherit;line-height:inherit;text-decoration:none;} ul.nstoc li a.wikilink1:before,ul.nstoc li a.wikilink1:after{display:none;} ul.nstoc li a:hover,ul.nstoc li a.wikilink1:hover{text-decoration:underline;} </code> Of course, you're free to modify this styles¹¹⁾ to suit your personal needs or aesthe­tics¹²⁾. ==== Changes ==== 2010-02-18:
* minor change in 'handle()' to avoid type conversion; 2008-03-30:
* modified private '_doMarkup()' method to use the current renderer instance directly;
- removed obsoleted property '_sepChar' and private '_makeID()' method and updated 'render()' accordingly; 2008-03-28:
* modified CSS to explicitly overwrite some broken default settings; 2007-08-29:
* little doc corrections; 2007-08-26:
* modified 'handle()' and 'render()' to ignore nested index pages; 2007-08-15:
+ implemented use of global '$conf[“hidepages”]' setting;
* added GPL link and fixed some doc problems; 2007-08-12:
+ implemented new private '_path()' method and rewrote public 'handle()' to use it (thus allowing better relative navigation);
* various internal optimizations in several places; + added 'aDecLevel' argument in '_getHeadings()' interface to allow for handling namespaces, sub-pages and root pages differently;
* modified 'render()' to handle different page/list types; 2007-08-09:
+ added private members '_Chars' and '_Ents' and modified '_doMarkup()' to use them (so the lists are created only once when the object is instantiated instead of with each method call); 2007-08-08:
* modified 'handle()' to explicitly check for index pages;
* changed internal handling of directories vs. pages;
* slightly decreased font-size of 'level3'/'level4' LIs;
* modified anchor selector to inherit bg-colour; 2007-08-06:
+ added ':before/:after' selectors for links in case the default setting (by the main template) specifies something else; 2007-06-12:
# modified 'handle()' to fix handling of omitted namespace names;
* changed/corrected some doc comments; 2007-02-23:
* removed function test in '_fixJS()' (the PHP file might not be loaded); 2007-02-20:
+ implemented support for older DokuWikis; 2007-01-31:
* minor change in 'render()' setting up private '_sepChar' member; 2007-01-28:
* modified 'handle()' to slightly improve handling of sub-namespaces; 2007-01-14:
* modified RegEx in '_getHeadings()' to ignore empty headline markup and skip consecutive '=' characters used in patch files;
+ implemented private member '_callback' for use in 'render()' instead of a global callback for the global 'search()' function; 2007-01-08:
+ implemented utilization of access rights in 'render()'; 2006-12-31:
+ initial release; Matthias Watermann 2007-08-26 ===== See also ===== Consult DokuWiki's access control docs. ==== Plugins by the same author ==== * BOMfix Plugin – ignore Byte-Order-Mark characters in your pages * Code Syntax Plugin – use syntax highlighting of code fragments in your pages * Definition List Syntax Plugin – use the only complete definition lists in your pages * Diff Syntax Plugin – use highlighting of diff files (aka “patches”) in your pages¹³⁾ * HR Syntax Plugin – use horizontal rules in nested block elements of your pages * LANGuage Syntax Plugin – markup different languages in your pages * Lists Syntax Plugin – use the only complete un-/ordered lists in your pages * NBSP Syntax Plugin – use Non-Breakable-Spaces in your pages * NsToC Syntax Plugin – use automatically generated namespace indices * Shy Syntax Plugin – use soft hyphens in your pages * Tip Syntax Plugin – add hint areas to your pages ===== Discussion ===== Hints, comments, suggestions … (Please add new suggestions at the end to maintain some sort of chronological order.) > The idea of this plugin is interesting. It could be very useful, but it doesn't work in my DokuWiki installation… Do I have to change something before using it?? » Could you provide some more information? What did you try, what did you expect and what happened actually?
— Matthias Watermann 2007-01-30 12:57 I'm pretty happy with this plugin, but I will need to modify it some for my purposes. I have a news blurb site which is still very new. (I set up an example of what the home page will look like using this plug in in the sandbox. Currently, I am adding blurbs to the home page, then moving them to various categories when they get old. I would like to modify this plug in so that it only shows the first 5 second-level headings from each page. That way, I can just add the blurb to a specific category and it will automatically show up on the home page. I can strip out the top-level headings with the CSS, but will need to modify the plug-in itself to stop after 5 subheadings. I may also want to include the entire section for the top two of each page, but I need to play around with it more to see how it will work. Thanks for your good work on this one, I was going to start making one that does this sort of thing from scratch (and I have never programmed in PHP before, so it would be a real learning experience!) :p –Len 2007-01-30 12:30 p.m. -8:00. > Thanks for your input! I've had a look at your site to get the idea. (BTW: Your CSS isn't yet valid; both Firefox and Opera show a lot of warnings. Try http://jigsaw.w3.org/css-validator/ to help you get it fixed.) And I'd recommend to either add a left margin/padding to the ”ul.nstoc“ CSS selector or use the ”list-style-type: none“ setting as shown in the CSS above. The 'hopping' LI markers don't look that good to me.
About your intended changes: I fail to see the reason to skip the first-level headings (apart from the fact that in some pages the first heading is a H2 instead of H1) – but that's not my concern. What really worries me is the markup the user has to type in. There are already four variants: (1) neither namespace nor max-depth, (2) only namespace, (3) only max-depth, (4) both namespace and max-depth. Now, we'd need to express additionally to (a) skip the H1, (b) use only up to ”x“ H2s while (c) skipping all H3/H4/H5 lines.
The last point (c) seems to be the easiest one because the max-depth argument implicitly takes care of this: {{nstoc :legal 2}} would make sure that only H1 and H2 in the legal namespace will get used. However, once there will be sub-namespaces (like :legal:whatever) only the H1s of the pages therein will show up. So obviously this approach wouldn't work for you in the long term if used this way.
Point (b) (delimiting the H2s to use) kind of breaks the plugin's intended purpose insofar as the resulting list would no longer represent a complete TOC. On the other side I wonder whether a single page with several H2s shouldn't get split up into several pages of their own (probably in their own “sub-chapter” namespace).
That leaves (a) i.e. skipping H1. This as well doesn't fit with the plugin's purpose, I fear. And assuming that H1 should provide fairly relevant information I must admit that I fail to see the point in omitting it.
Well, although this reasoning doesn't seem to be very encouraging I think you could get what you want by slightly adjusting your point of view upon your wiki. Try to think of it as a big book like a reference of a programming language or such alike. You have the main topics to be covered which are the book's chapters (and wiki 1st level namespaces). So your 1st level index/start page could be nothing more than: ”{{nstoc :book}}“ This would produce an outline of all topics covered but no real content/information yet. As appropriate for each of the chapters, there would be either a page (providing content/information actually or just {{nstoc :book:chapter1}}) or sub-chapters (i.e. wiki 2nd level namespaces). And so on…
I'm aware that wiki users don't tend to think in terms like “document” or “structure” and alike but more in the lines of contents (leaving anything else to the “magic under the hood” i.e. the respective wiki software). But as a maintainer of a DokuWiki installation you've got the power to enforce some – say – “politics” about how to structure your web-presentation. And judging from your start page and your words above you've already given some thought to this matter. Hence I think you'll only need some “fine tuning” in your namespace usage and the distribution of contents between files (pages) therein. — Thinking such an approach to its end could mean that DokuWiki's built-in “index” (your http://www.patentblurb.com/doku.php?idx=wiki URL) could provide all navigational aid required to use your site.
Having said that please feel free to followup as I very well may have missed your point.
— Matthias Watermann 2007-01-31 12:29 »Thanks, I know the site has only been up for a week or so, and it still needs tweaking. Before discovering DokuWiki, I have been running WikiServer internally on my company's intranet, so I just copied the content and reformatted it with DokuWiki's syntax. I agree about the hopping LI markers :o thanks for the hint. Also I agree that skipping H1 is not necessary, as I think I can make what I want work with CSS changes. Part of the problem is that some of the name spaces have pages that I don't want included in the TOC, but I guess that is easy to fix by moving them to a different namespace… so that's ok, really, come to think of it. » » The one concern I have is that as these categories fill up with blurbs, the TOC will grow huge, which is why I wanted to limit to X number of headings (not X depth). So that, lets say the H1 and only the first 5 H2s under each H1 would be listed, with maybe a ”…more“ underneath which would point to the H1 location. –Len (2007-01-31 3:57 -8:00) »> About name­spaces to not include: If it's not only a matter of quan­ti­ty pos­sib­ly DokuWiki's access control can help?
The other point is one (huge lists) I stumbled over myself recently. While it would not be too difficult to implement another number option as such the question is: What would it be supposed to mean? (a) The overall max. number of list entries, (b) the max. number of entries per namespace (in­clu­ding (b.a) all sub-namespaces or (b.b) just the respective current one), (c) the max. num­ber of en­tries per page, or (d) … — What­ever we'd decide the resulting list would match our intentions only with certain com­bi­na­tions of name­spa­ces, sub-name­spa­ces, pages and head­lines therein while with other combina­tions the list would get either too short or still too large.
Above I mentioned the book analogy several times already. In its shortest form ”{{nstoc :book}}“ would produce a complete TOC of the whole thing. But that doesn't mean that you must use the plugin that way and only that way. It's just one way intended to save you some typing. Let me introduce another analogy: a tree. The wiki's namespaces are the branches and the pages the leafs. Additionally we say that neither the tree trunk nor in­ter­me­dia­te bran­ches may have leafs (i.e. real con­tent pages). All namespaces (trunk and bran­ches) except the outermost ones contain just one index page like<code> ====== Name of this branch ====== nstoc_sub-ns-one_1 nstoc_sub-ns-two_1 nstoc_sub-ns-three_1 </code> Since there's only one headline in such an index page it doesn't contribute too much to the overall list (the one that starts at the very top). But if the list is still too long, you could just hide all intermediate branches by using a top index like <code> ====== My presentation ====== outermost_2 outermost_2 outermost_2 </code> By explicitly naming the namespaces to use combined with the depth option you'd make sure that only the H1 and H2 headings of the pages in the re­spec­ti­ve outer­most name­space (branch, sub-chapter) show up in the final list. In case even that would give too huge a list you could name the pages explicitly (omit­ting those you do not want to show up in the list) e.g. <code> ====== My presentation ====== page1_1 page4_3 outermost_4 page77_2 </code> Well, that might not look too good at first glance, but I hope you'll get the idea. — Ad­mit­ted­ly this is a little more typing initially than just ”{{nstoc }}“. But, after all, you've to do that only once when your tree has grown its in­ten­ded struc­ture. — Like every gardener, however, be careful with your plants ;-)
— Matthias Watermann 2007-02-01 13:42 >Hi, this plugin is exactly what I need and I am able to create the TOC of nested namespaces if I explicitly list them but the simple syntax {{nstoc }} simply doesn't work on my DokuWiki. Note: I'm not in the root namespace so it's not the special case mentioned in the article. If I include {{nstoc }} on page namespace:some_page, it ignores the other pages in namespace and includes only heading from some_page. And I certainly have enough permissions to view all pages as I'm in an admin group. » Well, it took some time to track that down. But (hopefully) it's fixed by now. Let me know if there are still problems.
— Matthias Watermann 2007-06-12 13:26 »> It still doesn't work on my DokuWiki (version 2007-06-26). I was able to simulate the desired result with {{nstoc * 4 }}
Borek 2007-07-16 14:29 »» Thanks for your note. Please check again with the plugin's latest release. I've run several tests but was unable to reproduce what you're describing.
— Matthias Watermann 2007-08-26 22:19
>It would be nice if the plug in can search for specific tokens in the page, so I can create a resume page of interesting points.
Rodrigo Montes 2007-05-11 16:11 » Hmmm, I can't see how that could be implemented conveniently. After all, how would you define “specific tokens” in a way that fits all DokuWiki installations? Most probably you'd end up with a (theoretically endless) list of tokens which has to be parsed & processed with each “candidate” (i.e. file) resulting in a lot of runtime overhead.
If, however, you have root access to your *NIX/Linux based web server you could get what you want by creating “pseudo namespaces” (in need for a better term) which solely consist (as far as the filesystem is concerned) of sym-links organized & named in a way that fits your needs.
While I haven't tested this idea in real life I imagine you could generate your “page of interesting points” that way. Just remember that all DokuWiki (and this plugin) “knows” is the name of your namespaces and pages. So, for example, if one of your “specific tokens” would be tennis you'd just create a namespace (i.e. directory) called “tennis” and sym-link all your tennis related pages (i.e. files, wherever they may reside originally in your namespace hierarchy) into that directory (possibly using other names for the sym-links as the original files if that helps to “tokenize” them). Of course, you have to review any relative hyperlinks in such a page but that's something you must do anyway whenever setting up and/or modifying a namespace.
— Matthias Watermann 2007-06-12 13:32 > I added a couple of lines at the start of function handle:
<code php> function handle($aMatch, $aState, $aPos, &$aHandler) { $aMatch = str_replace('@YEAR@',date('Y'),$aMatch); $aMatch = str_replace('@MONTH@',date('n'),$aMatch); … } </code>
This allows me to use @YEAR@ and @MONTH@ to insert the current year and month.
Erik Itland » While I can see your point I really don't think that something like that is in the “domain of responsibility” of this plugin. See my comments above.
— Matthias Watermann 2007-06-12 13:49
Several quirks when I try to use this: * specifying namespaces only works if I use the full namespace path, starting with root * the TOC outputted shows from H1 down, without the page title; how do I make the page title appear? > Hi anonymous! If you want a list starting relative to the current namespace just specify it e.g.: {{nstoc .:sub_namespace}} or {{nstoc .:sub_namespace:pagename}}. – About “page title”: I'm not sure what you mean by that term. The filename? The namespace name? Anyway, the TOC gets generated based on the headings (and a page's title is usually the H1 heading).
— Matthias Watermann 2007-07-26 12:05 »I meant filename - is there anyway to get nstoc to list pages by the name of the page instead of the first H1 in the page? The reason is that many of the pages I am trying to get in the TOC have headings that are different from the page name. —Thanks »> Sorry, no. I consider the filename just a technical item with no relevance to the user/reader. This plugin is supposed to generate a Table of Contents not a directory listing. Apart from that: The filename is subject to various modifications (e.g. lowercasing, replacement of certain characters etc.) so it would be quite hard to produce a readable string (at least if one's using not only plain ASCII characters). – BTW: Do you know about the ”$conf['useheading']“ setting? – Isn't it, well, confusing if in the URL shows up a filename of “tea” while the page's headline says “coffee”? – Anyway, there's always DokuWiki's ”?do=index“ CGI argument you could use to get a filename based overview.
— Matthias Watermann 2007-08-12 15:26
> I wish I could use only the first H1 in a document I am using your excellent plugin here - http://dokuwiki.healthwealthandmusic.co.uk/. I think the pages look better if I use an HTML H1 as the page title with nice size and colour and then DokuWiki H1s as sections like this - http://dokuwiki.healthwealthandmusic.co.uk/doku.php/computer:dokuwiki. But because the plugin reads H1 as if it were a new document it will list all the H1s in a single document when all I really want is the first H1. If you click on Sitemap you will see what I mean. (I'll leave it for a day or two - from 19 Oct). I can understand I might have to revert back to the standard way but it would be nice if the algorithm allowed me to specify only the first H1 and NOT the rest? > Well, unless you're willing to properly structure your documents there isn't an easy solution, I'm afraid. Each single document can only have one main headline (H1). If there are more this indicates that (a) either the document should be split into two (or more) documents each of which having its own distinguished headline or (b) the document's markup doesn't represent its structure properly.
Another possible reason might be that your page authors are abusing the Hx for design instead of structure. If that's the case you should tell them the difference between a bold typeface and a document headline.
So whatever the reason might have been in the first place, as long as your document's markup reflects its structure you should be fine.
— Matthias Watermann 2008/03/28 10:26 I like this plugin very much as it saves me a lot of redundant work, but I have a small issue with how the TOC is displayed. I get a new line after every bullet button, so the actual text is in a separate new line, which doesn't give me a particular nice layout.
This seems to be problem in Firefox (2) only. It doesn't appear in IE7 or IE6. Is this something which Firefox does wrong?
I haven't modified any CSS (Should I be copying the style.css somewhere?). Is there an easy way to resolve this and to remove the new line without changing the actual code of the plugin?
— Max 2008-03-17 > I've been a bit confused at first, since list bullets shouldn't show up at all in a nstoc list and I haven't been able to reproduce the problem (BTW: bullets, colours, indentations etc. all are a matter of CSS, meaning it's up to the browser how to handle them). However, after a while I realized that there might be conflicting CSS rules with DokuWiki's default styles¹⁴⁾. To make a long story short: I've added some rules to the plugin's CSS file to enforce the nstoc layout even when used with DokuWiki's default CSS/template. I've verified it with both Opera and Firefox¹⁵⁾ and it works fine.
So please try to re-install the plugin and see whether it works out for you.
— Matthias Watermann 2008/03/28 10:14 > I have exactly the opposite wish as one colleague above: I'd like the plugin to be able to skip the H1 header. I'm using the plugin in two ways: > a) to replace the standard DokuWiki TOC. In this case it doesn't really make sense to have the H1 heading in the TOC, just beneath the H1 heading > b) to refer to a page from an other (“FAQ mode”). In this case I structure the main FAQ page myself and would like to list all headings but H1 > An ideal solution could be to have some kind of '-/+' syntax: -1 skips H1, -2 skips H2 etc. So that nstoc_-1_2_3 > would show H3 but not H1 and not H2..? > Just a proposition > — Frank, 2008/12/04 16:21 Make link hack
This hack fixing such errors as: * Incorrect romanization links handling * Makes inc number to duplicated headings To do it you gotta replace this function on /nstoc/syntax.php <code php> function _makeID(&$aID) { $title = str_replace(':',,cleanID($aID)); $title = ltrim($title,'0123456789._-'); if(empty($title)) $title='section'; make sure tiles are unique $num = ; while(in_array($title.$num,$this→headers)){ ($num) ? $num++ : $num = 1; } $title = $title.$num; $this→headers[] = $title; return $title; } _makeID() </code> — Kirill Bezrukov 2008/03/23 11:49 > Hmmm, I'm not sure what you're trying to accomplish here. The headlines of a page/document must be unique in the first place (otherwise you'd not only confuse the readers but also break DokuWiki's automatic link generation). So if your pages have duplicated headlines you should correct those pages instead of a plugin which simply uses those pages.
Adding a number (or anything else) to a hypertext link fragment identifier will break that link. Please be aware that the private method you're “fixing” must return a value exactly as DokuWiki's internal link generation, which it does not in your variant. Apart from that: There's no object property named headers, so at least the code snippet above is incomplete.
As for “incorrect romanization” I really don't know what you're talking about. As the comments in the (original) source code state there are not only the official W3C rules to take into account when creating anchor names but an additional constraint imposed by DokuWiki to use only lowercase letters. Your “fix” fails on both.
I'd strongly discourage everybody from using the “fix” above: It will break your DokuWiki and possibly invalidate the page.
— Matthias Watermann 2008/03/28 11:09 » I got this code from \parser\xhtml.php line 997 function _headerToLink. May be the best way just use this function from DokuWiki core, but I don't know how.
About Romanization: if your wiki not in English, for example in Russian as I have, and you use $conf['deaccent'] = '2'; option (when Russian names are converted in translation (English letters) the headers in generated TOC have empty links (just #). And after I made this, it became fine.
And I just forgot about $headers array, it must be defined as plugin class global var and clearing before link generation — Kirill Bezrukov 2008/03/29 22:04 »> Following your suggestion I've modified the plugin to use the method you mentioned. As already discussed by private email this does not guard against poorly structured documents. I hope it helps, anyway.
— Matthias Watermann 2008/03/30 20:09
Hi Matthias, Did you consider using metadata rather than searching the wiki text in your _getHeadings() method? The TOC (admittedly a restricted set of headings) is available in array form through p_get_metadata($id,'description tableofcontents');. If the TOC is acceptable, it maybe a faster method for accessing the raw heading information. — Christopher Smith 2008/12/04 14:33 Great plugin! did a bit of a hack to allow me to exclude pages from getting indexed site-wide. I did this because I'm building a nav menu where each namespace has a file named sidebar and a file named nav, and I didn't want those to show up in the nstoc listing. In syntax.php, line 693: <code php> $this→_callback = create_function( '&$aData, $aBase, $aFile, $aType, $aLvl, $opts', 'if 16)' . '&& (! is_dir($aBase . ”/“ . substr($aFile, 0, -4)))' . '&& ($aFile = pathID($aFile)) && ($aFile != ”' . $idx . '“)' . '&& (substr($aFile, -3) != “nav”)' Added by DREW to exclude pages named “nav” . '&& (substr($aFile, ' . $iLen . ') != ”:' . $idx . '“)) {' . '$aData[] = $aFile;' . '}' . 'return TRUE;'); </code> You can continue to copy and paste to add any other exclusions you'd like. Also, remember to change the number on the substr to be the number of letters in the filename you're trying to exclude (nav has 3 letters, so -3; sidebar has 7 letters, so -7). While I'm sure this isn't the best way to do it, it works for me. I could see this as being useful to be able to define per instance of nstoc, though, so perhaps a suggestion to the plugin is to add that? (ie: {{nstoc :namespace 1 excludeMe1 excludeMe2 …) Thanks for the great plugin! Andrew Petersen 2009/03/01 00:03
Thanks for this plugin. It looks like exactly what I was looking for. The only thing I would like to have would be to replace the contents of the built-in Table of Contents by the HTML output of this table. How could be this done? — Josef Meile 2009/04/21 20:00 > Hmm, as far as I can see that's not easily possible. And I fail to see the benefit: While a page's TOC is meant to provide overview of the current page (i.e. the one actually displayed by the browser) the nstoc output gives the page titles of one or more name­spaces (possibly but not necessarily including the current page). In other words: Both lists serve a completely different purpose.
— Matthias Watermann 2009/08/07 11:05
This plugin is great, but the 'title' attribute of the links is different to the title attribute created by DokuWiki for an internal link. E.g.: nstoc creates: <a class="wikilink1" title="Architectural Overview" href="/wiki/doku.php/work:intro­duction#architectural_overview">Architectural Overview</a> vs. DokuWiki: <a class="wikilink1" title="work:introduction" href="/wiki/doku.php/work:intro­duction#architectural_overview">architectural overview</a>. This means that offline processors can't use the title attribute for determining which page it points to e.g. offline plugin. Any chance you can say how to quickly change that? > I'm not sure about your point. The “title” attribute offers “advisory information about the element for which it is set” (see e.g. W3C), it is not intended for “determining which page it points to”. Usually it's displayed as a so-called “tooltip” window by visual brow­sers. The “href” attribute, however, “specifies the location of a Web resource” (see e.g. W3C) thus providing exactly the information you're obviously looking for.
— Matthias Watermann 2009/08/07 10:57 » Thanks for your reply. When using the offline plugin, the links created by nstoc are not converted correctly to local URLs. I assumed that the offline plugin was reading the HTML output of rendering a page and the only different between links that were converted correctly (manual links) and those that were not (nstoc) was the title attribute. I should probably hit up the offline plugin guys for the cause of this, they may be incorrectly assuming that the title attribute can help them find the referred page rather than parsing the href. If there is no convention for using the title attribute for this then its their problem I guess. - Lindsay Smith 09-08-2009
Nice plugin but it seems to me that there is a small bug if a page has same name than a namespace. In such a case, the page is ignored. For instance, if you have a namespace /organization and a page /organisation.txt the plugin will display /organisation/district_A.txt and /organisation/district_B.txt but not /organisation.txt which may introduce the other pages.
> Maybe a patch should suppress ligne 643 in syntax.php <code php> . '&& (! is_dir($aBase . ”/“ . substr($aFile, 0, -4)))' </code> — Florent Chabaud 2009/12/23 20:51 > What you're describing, Florent, is indeed an intended feature and documented above. I'd recommend to rename the pages you do not want to be skipped to something like oldname_overview.
— Matthias Watermann 2010/02/18 11:17 » @Florent: Thanks. This little “hack” solved exactly this problem I had » @Matthias: I understand the motivation of the current implementation, but e.g. in our environment, we completely got rid of the start pages and use pages with the same name as the namespaces as overview or index pages (usually using the nstoc plugin) (motivation: clean URLs). Renaming them is not an option because it would be against the intended results. Maybe this could become a configurable option for the plugin: To respect those “index” pages or not?
— Frank Thommen 2010/05/27 » @Florent: Cheers for the patch, works a treat. @Frank: +1. The current behavior may be intentional, but it “feels” broken when a significant number of your namespace headings disappear from the TOC, so their pages appear as children of the previous namespace.
— Steve, 2010/05/29
I use your plugin to have a table of content at the beginning of a page.
The headings are automatically numbered by the numberedheadings plugin. Unfortunately nstoc does not display the numbers of the heading.
” - heading“ is shown instead of “1 heading”.
(the syntax of numberedheadings plugin is to add a '-' between the '=' and the headingtext e.g. ===== - heading ====='')
Does anybody has an idea how to fix this? joachim 2010-02-08 > This plugin reads the headings as they're stored in the filesystem. So, if there's a hyphen in the heading a hyphen is shown. You might want to have a look at another approach for numbered headings.
— Matthias Watermann 2010/02/18 11:28
>Don't work when ns name is not in English? I tried to set $conf['deaccent']=2, but still no result.