Differences

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

--- plugin:nstoc [2022-07-06 16:19] – fwfewfe 2001:16a2:c584:1e00:947f:cc7c:ca78:8ef
+++ plugin:nstoc [2023-10-30 22:52] (current) – Klap-in
@@ Line 1: / Line 1: @@
-fewfewfewfweewfew
+[[de:plugin:nstoc|deutsch]]
+====== NsToC Syntax Plugin ======
+---- plugin ----
+description: Namespace Table-of-Content
+author     : Matthias Watermann
+email      : support@mwat.de
+type       : syntax
+lastupdate : 2010-02-18
+compatible : Frusterick Manners, !Hogfather
+depends    :
+conflicts  :
+similar    : tocselect
+tags       : navigation, menu, listing, namespace, !broken
+downloadurl: http://dev.mwat.de/dw/syntax_plugin_nstoc.zip
+----
+A while ago I started a project involving lots of hierarchically ordered pages -- just like a book with chapters, sub-chapters and paragraphs.
+To add (and update whenever a page was added/removed/merged) the TOC references was a necessary but quite stupid job((In other words: just what computers were made for.)).
+After doing this pesky task for quite a few times I decided to automate it. ---
+Enter "''nstoc''".
+This plugin offers you the ability to generate a //Table Of Contents// for a namespace with an optional depth.
+It generates a (possibly nested) list of headlines used in all matched pages.
+One could say this plugin sees your whole Wiki as one huge document structured by chapters (Wiki namespaces), sub-chapters (the single pages within a namespace) and appropriate headlines (H1...H5).
+===== Usage =====
+The basic markup is just:
+		{{nstoc }}
+This will create a nested list of all pages((actually, the //headlines// in/of the pages are shown)) in the current namespace and all sub-namespaces.
+Please note the space((''space'', ASCII char #32; not to be confused with a ''blank'', ASCII char #255)) behind the "''nstoc''" keyword:
+Forgetting it will trigger DokuWiki's built-in ''media'' renderer which you most probably do //not// want here.
+To limit the output to -- say -- two levels use
+		{{nstoc 2}}
+The result will be a list with all H1 and H2 headlines in the current namespace's pages and all H1 headlines in the pages of all sub-namespaces of the current one while
+		{{nstoc 3}}
+will produce a list with all H1/H2/H3 headlines in the current namespace's pages, all H1/H2 headlines in the pages of all sub-namespaces of the current one and all H1 headlines in the pages of all sub-sub-namespaces.
+Another way to limit the output is to explicitly name the namespace:
+		{{nstoc chapter2}}
+This will show the headlines (with unlimited depth) in the "''chapter2''" namespace.
+You may, of course, combine the optional //namespace// and //depth// arguments:
+		{{nstoc chapter3 1}}
+Here only the H1 headlines of the pages in "''chapter3''" will be shown.
+==== Compatibility ====
+This plugin is also compatible with 2005-07-13 and was made for that version. It's compatible with 2017 Frusterick Manners but not Hogfather.
+==== Hints ====
+Here are some tips which might be helpful for you when working with this plugin.
+=== Order ===
+The generated output -- or, to be more precise: the //order// of the generated list -- might not always be what you'd expect.
+The reason for this: You, as a human being((I hope ...)), have a notion of //meaning// while the computer just knows about //data//.
+To illustrate this let's assume you're writing a book.
+Right now you've finished (or at least created) this pages:
+	- Preface
+	- Introduction
+	- First Chapter
+	- Second Chapter
+	- Appendix
+When using "''nstoc''" you'll most probably expect a list like the one above.
+But, alas, the real result would look like
+	* Appendix
+	* First Chapter
+	* Introduction
+	* Preface
+	* Second Chapter
+Not very helpful, is it? --- The reason is simple:
+The only thing DokuWiki and this plugin has to deal with are (file and namespace) //names//.
+But, as it turns out, it's quite easy for you to take this fact to your advantage by choosing the right page names.
+For example, name the pages((i.e. the files but //not// the H1 headline)) like this:
+	* 00_preface
+	* 01_introduction
+	* 02_first_chapter
+	* 03_second_chapter
+	* 99_appendix
+Theoretically you could even omit all the alphas and just leave the digits.
+But I guess, that would take the computerizing of your work a bit too far.
+Anyway, as long as the page and namespace //names// sort in the intended order, "''nstoc''" will produce useful output.
 BTW: This discussion applies to namespace names as well.