Feedback on ExplicitNumberingPlugin

Suggestions

Discussion

-- MartinVlach - 30 Jul 2003

Martin, did you look at TocPlugin (TocPluginDev)? That also numbers sections.

-- CrawfordCurrie - 30 Jul 2003

Yes, I did look at TocPlugin. I will add a reference to it in the "See Also" section of the ExplicitNumberingPlugin.

I developed this plugin as an "excercise to the reader" to learn plugins and perl programming. I posted it as a thank you to the TWiki community for developing a great system.

-- MartinVlach - 01 Aug 2003

I had a problem in connection with ModPerl: Because the module is reused for each page rendering, the first-level numbers were increased on each page view (e.g. 1.1 -> 2.1 -> 3.1 ...) That bug is easy to fix by reinitializing %Sequences on the startRenderingHandler event.

Here's my configuration:

Operating system: Unix (hpux) 
Perl version: 5.6.1 
mod_perl: Used for this script (mod_perl loaded) 
ExplicitNumberingPlugin version: 29 Jul 2003 (V1.010)

https://twiki.org/p/pub/Plugins/ExplicitNumberingPluginDev/ModPerlBugfix.diff is the diff containing my patch to ExplicitNumberingPlugin.pm.

-- IngoKarkat - 07 Aug 2003

Thank you, Ingo. I fixed the distribution.

-- MartinVlach - 12 Aug 2003

Martin, I downloaded the new version of the plugin and your comments state that this is version 1.002 but the internals state that this is still version 1.010. Just making sure I have the version numbering right - was the intent to make this version 1.020? thanks!

-- SteveRJones - 19 Nov 2003

I posted this to the support web, and was asked to repost it here :

I'm unable to get the ExplicitNumberingPlugin working correctly with the TOC variable. I've read the syntax rules for this, but I don't get the correct anchors being rendered in the TOC, for example, if my source code looks like this :

%TOC%

---+ Chapter ##0. Introduction
---+ Chapter ##. Part One
---+ Chapter ##. Part Two
---+ Chapter ##. Part Three

The page appears to render OK, but the anchors generated in the TOC don't correspond to the anchors generated for the headings. This means you can no longer navigate the page via the TOC. The heading anchors look correct, but the TOC anchors look wrong (to me). If I view the page source, the anchors look like this (topic name is Test) :

I got this reply from the support web :

I've tried this myself and it definitely does not work. One thing the docs indicate is that you need to make sure you label the numbering group with a name - yet the example does not show this. Your example above should read as follows:

%TOC%

---+ Chapter ##a#0. Introduction
---+ Chapter ##a#. Part One
---+ Chapter ##a#. Part Two
---+ Chapter ##a#. Part Three

Adding the named region adds a name to the internal reference tag and it does. What is missing is the generated numeration in the generated anchor.

I would go ahead and re-post this to the ExplicitNumberingPluginDev as a bug and see if it cannot be chased down.

-- SteveJonesST - 26 Jan 2004

We've been using this heavily in our design docs and its been driving everyone nuts that the links in the TOC don't work. I looked into this a bit and found it is because TOC scans the page w/o calling any plugins (so the anchor names end up w/o numbers and the actual headers in the text end up with numbers).

A workaround is in TWiki.pm to change makeAnchorName() to always strip off the numbering. This way for the TOC it will (as it does now) strip off the ##. text and for the body it will strip off the plugin rendered numbers. I didn't figure out how to make this work with named sequences, we only use numbers. The change is in TWiki.pm around line 2336:

    $anchorName =~ s/__+/_/g;               # remove excessive '_'
+   $anchorName =~ s/^[\d_]+//g;            # remove auto numbering
    $anchorName =~ s/^(.{32})(.*)$/$1/;     # limit to 32 chars

I'm not suggesting this as a general fix, but someone may find this workaround useful.

-- EricVarsanyi - 04 Aug 2004

.zip checked into CVSplugins:ExplicitNumberingPlugin

-- WillNorris - 23 Nov 2004

I was able to finally make the plugin work using the following syntax:

---+ FAQ##0.: 
---+ FAQ##.:
---+ FAQ##.:
---+ FAQ##.:
---+ FAQ##.:
---+ FAQ##.:

This was used for building simply FAQ templates.

-- SteveRJones - 23 Nov 2004

I was able to get the anchors to work by modifying TWiki::handleToc (in TWiki.pm)

I added:

&TWiki::Plugins::outsidePREHandler( $line ); 

$anchor = TWiki::Render::makeAnchorName( $line ); 

-- AnthonyEWong - 01 Feb 2005

Anthony, do you want to update the package for us?

-- AntonAylward - 02 Feb 2005

Unfortunately, I made a change to TWiki.pm, so this is not a change to the plugin, but a change to a core module (I think). I'm not really a perl guy. This change that I proposed is really more of a kludge fix, since the problem lies in the handleToc module (see EricVarsanyi's comments above).

-- AnthonyEWong - 02 Feb 2005

Has anyone looked at extending the plugin to support sequence reinitializing to a non-0 value. E.g. ##a#1. to force the first sequence value to 2. instead of 1.? Some of the topics we have start getting longish and then split into subtopics. It would be nice to continue the numbering scheme down into the subtopics.

-- SteveWampler - 28 Feb 2005

I've gone ahead and added the ability to force a level value to a specific integer (1-99999). For example:

---++ ##4. Infrastructure

   ##.. blah
   ##.. more blah
   ##6.. still more blah
   ##.. less blah

renders as (something like):

4 Infrastructure

4.1 blah
4.2 more blah
4.6 still more blah
4.7 less blah

It's a simple fix - a slight change to a regular expression and 4 extra lines added to the perl script. I'll provide details if anyone is interested.

-- SteveWampler - 09 Mar 2005

Steve, please attach a patch of your enhancement...

Ok, it's attached below as ForceLevel.patch.

-- SteveWampler - 09 Mar 2005

Sigh. I uploaded a patch against an earlier attempt. ForceLevel.patch has been updated to the correct version. Sorry!

-- SteveWampler - 09 Mar 2005

I tried to put this plugin into production and had to remove it because of the TOC issue posted above.

Before I do the suggested fix by AnthonyEWong (01 Feb 2005) to the TWiki code on a production server I need to make sure that the developers of the Dakar release includes this - or a compatible fix - on the release. I would not be in a situation where I upgrade and then all our ISO9000 pages are with non working numbering and/or TOC.

I have tested Anthony's fix and it works fine.

The auto numbering of sections is a feature my users keep on asking for so I would love to see this plugin or similar feature among the standard functions in TWiki.

-- KennethLavrsen - 15 Mar 2005

Hmmm, is it true that this plugin only applies to section headers? It works fine for me in lines such as:

---+++++ ##header#.

but not if I try to build a numbered list as:

   ##item#.
   ##item#.

It looks like it works, but if I insert some non-item text (such as this) and try to resume with:

   ##item#.

I get the renumbering starting also.

Is that just me?

-- SteveWampler - 18 Apr 2005

No, this should work -- we use this plugin fairly extensively. Keep in mind that the text where you have "item" is really the text that defines the sequence that shares the common numbering. To use this you would do something like:

Item ##a#0. %BR% <---- the zero does a restart

blah

Item ##a#. %BR%

blahblah

Item ##a#. %BR%

blahblahblah

This plugin also requires that you end the tag with a <break> -- I think this needs fixing.

-- SteveRJones - 19 Apr 2005

Yes, that works, but if you change it to:

 Item ##a#0. %BR% <---- the zero does a restart

blah

   ##a#. %BR%

blahblah

   ##a#. %BR%

blahblahblah

Then it doesn't work. (That is, indent the text three spaces and try to use this plugin to number the indented paragraphs). (I was using 'item' as the sequence name - I'm not partial to single character mnemonics - hence the confusion...)

Would you explain that last sentence ("end the tag with a") - I'm confused. Thanks!

-- SteveWampler - 19 Apr 2005

Ah, I now know why you cannot use this plugin to override the default list numbering. The plugin works correctly and renumbers the list elements, but Render.pm then spots the 'numbered' list lines and does its own renumbering.

I can't think of a fix.

-- SteveWampler - 25 Apr 2005

Is it possible to extent the forced renumbering to support forcing to an arbitrary numbering level? E.g. allow numbering to go from 2.3 to 4.1.5 by writing ##4.1.5. (or whatever)? I'm trying to write editorial notes on sections of a paper. Most of the time the number is contiguous, but I occasionally need to jump to arbitrary sections.

-- MichaelOkincha - 28 Apr 2005

It's certainly possible, but someone who's more facile with perl should probably modify ForceLevel.patch to do so. I'm barely literate in perl. In the meantime, you can use ForceLevel.patch and the following kluge technique:

   <!-- ##4. ##1.. --> ##5...

-- SteveWampler - 29 Apr 2005

See also NumberedHeadings and NumberedHeadingsWithNesting for a "poor man's" way to create nested numbered headings.

-- PeterThoeny - 30 Apr 2005

Oops, I keep forgetting that the < > gets sucked up as an html tag. SteveWampler, I fixed my comments -- it is that a <break> needs to be added.

And yes, you are correct that the plugin does not work if you pre-pend the pound signs with spaces.

-- SteveRJones - 01 May 2005

This plugin works fine with Dakar and %TOC% if you change the sub outsidePREHandler to sub commonTagsHandler and sub startRenderingHandler to sub beforeCommonTagsHandler.

-- DanielRohde - 07 Feb 2006

Daniel, do you have check-in rights? Can you make your changes to the twiki-plugins area and republish your modifications to the plugin?

-- MartinCleaver - 07 Feb 2006

Please make an effort to keep the Plugin compatible with Cairo and Dakar codebase. See HandlingCairoDakarPluginDifferences

-- PeterThoeny - 08 Feb 2006

Peter, I think the biggest issue with this plugin is that it is not really owned by anyone as there really hasn't been anything from Martin since 2003. There are several Plugins that are like this - and if I could ever understand how regex's work I could probably help out with some.

So right now, we have a number of orphaned plugins that need a daddy (or mommy!)

-- SteveRJones - 08 Feb 2006

I couldn't pick up from the thread, does this plugin work with TWiki 4.0.3?

-- EricHanson - 28 Jun 2006

Judging by the comments of DanielRohde and PeterThoeny it needs some minor modifications to run in TWiki 4.x (Dakar).

-- JasonHill - 29 Jun 2006

Here is how I use this plugin to number lists: I use RenderListPlugin, where I define a new rendering theme as follows:

      * #Set EMPTY_THEME = icon, 0, 16, 16, %ATTACHURL%/empty.gif, %ATTACHURL%/empty.gif, %ATTACHURL%/empty.gif, %ATTACHURL%/empty.gif, %ATTACHURL%/empty.gif

Then

%RENDERLIST{"empty"}%
   * ##.
      * ##..

-- ShaughanLavine - 04 Aug 2006

As this plugin seemed orphaned and I needed support for numbered headings, I updated this plugin by

• adding reset to specific number based on suggestion by SteveWampler,
• adding support of numbered headers,
• proper handling in table of content.

-- ThomasWeigert - 22 Nov 2006

Thanks Thomas for resurrecting this plugin!

-- PeterThoeny - 22 Nov 2006

Below is a comparison to the features supported in TocPlugin. Basically, the difference is syntax and that TocPlugin supports cross references.

-- ThomasWeigert - 22 Nov 2006

I made a minor improvement in the use of sequences using letters to allow upper-case letters (useful for numbering things like Appendices)

Index: ExplicitNumberingPlugin.pm
===================================================================
--- ExplicitNumberingPlugin.pm   (revision 310)
+++ ExplicitNumberingPlugin.pm   (revision 311)
@@ -80,7 +80,7 @@
     %Sequences = ();
 
     $_[0] =~ s/\-\-\-(\#\#*) /&makeHeading(length($1))/geo;
-    $_[0] =~ s/\#\#(\w+\#)?([0-9]+)?\.(\.*)([a-z]?)/&makeExplicitNumber($1,$2,length($3),$4)/geo;
+    $_[0] =~ s/\#\#(\w+\#)?([0-9]+)?\.(\.*)([a-zA-Z]?)/&makeExplicitNumber($1,$2,length($3),$4)/geo;
 }
 
 # =========================
@@ -153,8 +153,12 @@
         $text .= '.' if ( $i < $level );
     }
     } else {
-    #...Level is 1-origin, indexing is 0-origin
-    $text .= $alphabet[$Numbering[$level]-1]
+        #...Level is 1-origin, indexing is 0-origin
+        if ($alist =~ m/[A-Z]/){
+            $text .= uc $alphabet[$Numbering[$level]-1];
+        } else {
+            $text .= $alphabet[$Numbering[$level]-1];
+       }
     }
 
     return $text;

-- DarrenElkerton - 09 Mar 2007

---#, ---##, ... syntax is killed by the TML --> HTML --> TML roundtrip of the WYSIWYG editor in 4.2. Use the ##., ##.., ... syntax instead!

Basic question: how can plugin developers ensure that their syntax enhancements don't get eaten up by WYSIWYG?

-- FranzJosefGigler - 02 Oct 2007

To the plugin maintainer: Someone updated an Interwiki link on the plugin topic. Make sure to take this into the next release.

-- PeterThoeny - 04 Jan 2008

I am having problems installing this plugin in TWiki 4.2, here the message I have got when I execute "perl ExplicitNumberingPlugin _installer.pl":

Can't locate object method "findUser" via package "TWiki::Users" at ExplicitNumberingPlugin_installer.pl line 559, <STDIN> line 1.

Does someone have an idea how to solve it?

-- MarceloAInuzuka - 14 Apr 2008

Got a very similar message while installing the latest TreePlugin. Isn't this just a warning message. The plugin does work, doesn't it?

-- FranzJosefGigler - 14 Apr 2008

I have installed on 4.2 and as posted above have found that the WYSIWYG editor replaces ---# with ---+. Does anyone know if it is possible to get the WYSIWYG editor to use ---# when applying heading styles or alternatively to get the editor to insert ##. text as part of the heading style? I expect that most of my users will be using the WYSIWYG editor and I would like to have numbered headings performed automatically.

-- ChrisPurves - 27 Jun 2008

Feedback: Incorrect interwiki link, TWiki:Plugin.TocPlugin should read TWiki:Plugins.TocPlugin

-- PeterThoeny - 16 Jul 2008

Here's a patch to fix parsing of enumeration in headings ( ---#) so that it now works together with EditChapterPlugin. This patch also includes DarrenElkerton 's patch for upper-case alphabetic enumerations. This plugin is marked as ContactAuthorFirst before applying the patch in svn and creating a new release. To the plugin's author: please have a look at the patch? I am going to check it in to SVN and create a new release if there's no reply from the author within - let's say - a week.

-- MichaelDaum - 25 Aug 2008

I am trying to use the plugin. Unfortunately the rendering is not entirely correct. The first number gets separated from the following ones by a space:

1. 1.1

1. 2.1

etc.

Is there a chance to fix that (maybe it's related to running TWiki 4.1 here)?

-- DetlefMarxsen - 2010-02-09