Differences

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

--- plugin:nstoc [2010/02/10 01:55]
74.93.99.97
+++ plugin:nstoc [2010/09/05 17:29] (current)
andi old revision restored
@@ Line 6: / Line 6: @@
 email      : support@mwat.de
 type       : syntax
-lastupdate : 2008-03-30
+lastupdate : 2010-02-18
 compatible : 2005-07-13+
 depends    :
@@ Line 15: / Line 15: @@
 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''".
@@ Line 239: / Line 239: @@
  * <tt>{{nstoc [namespace [maxdepth]]}}</tt>
  * </p><pre>
- *  Copyright (C) 2006, 2008  M.Watermann, D-10247 Berlin, FRG
+ *  Copyright (C) 2006, 2010  M.Watermann, D-10247 Berlin, FRG
  *      All rights reserved
  *    EMail : &lt;support@mwat.de&gt;
@@ Line 254: / Line 254: @@
  * </div>
  * @author <a href="mailto:support@mwat.de">Matthias Watermann</a>
- * @version <tt>$Id: syntax_plugin_nstoc.php,v 1.15 2008/03/30 12:43:59 matthias Exp $</tt>
+ * @version <tt>$Id: syntax_plugin_nstoc.php,v 1.16 2010/02/18 10:30:46 matthias Exp $</tt>
  * @since created 23-Dec-2006
  */
@@ Line 536: / Line 536: @@
     } // if
     // Check for relative paths:
-    if ((1 < $len) && ('.' == $aPath{0})) {
+    if ((1 < $len)
+    && ('.' == $aPath{0})) {
       if (':' == $aPath{1}) {
         return syntax_plugin_nstoc::_path($aNamespace,
@@ Line 618: / Line 619: @@
       'author' =>  'Matthias Watermann',
       'email' =>  'support@mwat.de',
-      'date' =>  '2008-03-30',
+      'date' =>  '2010-02-18',
       'name'  =>  'NsToC Syntax Plugin',
       'desc' =>  'Add a namespace\'s table of contents {'
@@ Line 696: / Line 697: @@
     // Compute current page and namespace:
     $current = str_replace('/', ':', getID('id', FALSE));
-    $dir = substr($current, 0, strrchr($current, ':'));
+    $f = strrchr($current, ':');
+    $dir = (FALSE === $f)
+      ? ''
+      : substr($current, 0, $f);
     if (! $dir) {
       // For unknown reasons the "strrchr()" call above
@@ Line 878: / Line 882: @@
     // To avoid repeated boolean and regEx tests if unneeded
     // we unroll the loop saving lots of CPU cycles.
-    if (isset($conf['hidepages']) && strlen($conf['hidepages'])) {
+    if (isset($conf['hidepages'])
+    && strlen($conf['hidepages'])) {
       $re = '/' . $conf['hidepages'] . '/ui';
       while (list($i, $entry) = each($ids)) {
@@ Line 937: / Line 942: @@
 ==== Changes ====
+__2010-02-18__:\\
+* minor change in 'handle()' to avoid type conversion;
 __2008-03-30__:\\
@@ Line 1018: / Line 1026: @@
 	* [[shy|Shy Syntax Plugin]] -- use soft hyphens in your pages
 	* [[tip|Tip Syntax Plugin]] -- add hint areas to your pages
 ===== Discussion =====
 Hints, comments, suggestions ...
@@ Line 1032: / Line 1039: @@
 I'm pretty happy with this plugin, but I will need to modify it some for my purposes.  I have a [[http://www.patentblurb.com|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 [[http://www.patentblurb.com/doku.php/playground:playground| 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|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''" ''H2''s 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 ''H1''s 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 ''H2''s 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 ''H2''s 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'd 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.\\ --- //[[support@mwat.de|Matthias Watermann]] 2007-01-31 12:29//
+> 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|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''" ''H2''s 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 ''H1''s 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 ''H2''s 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 ''H2''s 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.\\ --- //[[support@mwat.de|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.
@@ Line 1085: / Line 1092: @@
 Several quirks when I try to use this:
-  * specifying namespaces only works if I use the full namespace path, starting with root
+* 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?
+* 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).\\  --- //[[support@mwat.de|Matthias Watermann]] 2007-07-26 12:05//
@@ Line 1111: / Line 1118: @@
 > 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}}
+{{nstoc -1,2+3}}
 > would show H3 but not H1 and not H2..?
 > Just a proposition
@@ Line 1118: / Line 1125: @@
 **Make link hack**\\
 This hack fixing such errors as:
-  * Incorrect romanization links handling
+* Incorrect romanization links handling
-  * Makes inc number to duplicated headings
+* Makes inc number to duplicated headings
 To do it you gotta replace this function on ''/nstoc/syntax.php''
@@ Line 1153: / Line 1160: @@
 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.
- --- //[[chris@jalakai.co.uk|Christopher Smith]] 2008/12/04 14:33//
+--- //[[chris@jalakai.co.uk|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:
@@ Line 1164: / Line 1171: @@
 . '&& (substr($aFile, -3) != "nav")' // Added by DREW to exclude pages named "nav"
 . '&& (substr($aFile, ' . $iLen . ') != ":' . $idx . '")) {'
-   . '$aData[] = $aFile;'
+. '$aData[] = $aFile;'
 . '}'
 . 'return TRUE;');
@@ Line 1175: / Line 1182: @@
 --- //[[jmeile@hotmail.com|Josef Meile]] 2009/04/21 20:00//
-> Hmmm, 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 namespaces (possibly but not necessarily including the current page). In other words: Both lists serve a completely different purpose.\\ --- //[[support@mwat.de|Matthias Watermann]] 2009/08/07 11:05//
+> 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 namespaces (possibly but not necessarily including the current page). In other words: Both lists serve a completely different purpose.\\ --- //[[support@mwat.de|Matthias Watermann]] 2009/08/07 11:05//
 \\
@@ Line 1183: / Line 1190: @@
 > I'm not sure about your point. The "title" attribute offers "advisory information about the element for which it is set" (see e.g. [[http://www.w3.org/TR/html401/struct/global.html#adef-title|W3C]]), it is //not// intended for "determining which page it points to". Usually it's displayed as a so-called "tooltip" window by visual browsers. The "href" attribute, however, "specifies the location of a Web resource" (see e.g. [[http://www.w3.org/TR/html401/struct/links.html#edef-A|W3C]]) thus providing exactly the information you're obviously looking for.\\ --- //[[support@mwat.de|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
@@ Line 1194: / Line 1201: @@
 --- //Florent Chabaud 2009/12/23 20:51//
-\\
+> What you're describing, Florent, is indeed an intended feature and documented [[#index_pages|above]]. I'd recommend to rename the pages you do //not// want to be skipped to something like ''oldname_overview''.\\ --- //[[support@mwat.de|Matthias Watermann]] 2010/02/18 11:17//
-I use your plugin to have a table of content at the beginning of a page.\\
+>> @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 [[http://www.dokuwiki.org/tips:numbered_headings|another approach]] for numbered headings. \\ --- //[[support@mwat.de|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.