ExplicitNumberingPlugin Development

This is the topic to discuss development of download ExplicitNumberingPlugin

help If you need support, go to Support.ExplicitNumberingPlugin where you can ask questions and find answers to previously asked questions. warning If you want to report a bug, or a feature request, go to Tasks.ExplicitNumberingPlugin where you can see already submitted issues and where you can submit a new bug report or feature request.

Active Items

Id Summary Priority Current State Creation Date Last Edit
Item2262 Numeric Lists do not recognize ExplicitNumberingPlugin Normal Confirmed 15 Oct 2009 - 22:52 02 Jul 2010 - 02:14


This plugin is one I am often asked to install and I did install it once.

But my experience with it was negative. But there is hope.

The problem is that people very much want an auto numbering feature for section headers like they know from MS Word. Especially when they write longer topics or migrate topics from Word to Foswiki.

And the plugin works fine. BUT. People realize the problem the first time they are looking at a large topic and see a problem in section 14.3.5. Then they hit Edit and find that the whole document does not have visible section numbers in edit mode, only strange codes.

I have tried this myself. It is such a pain to find the place in the document you want to edit. If we had a sectional edit feature it would not have been so bad, but we don't. We end up in edit mode at the top of a 50 page topic and the only way to find the right place is to go back in view mode, copy some unique text, and edit again, use the find feature in the browser and find the place this way.

If this plugin was extended so it runs a handler when editing which also calculates section numbers and put these numbers in the edit text - it could work.

The issue here I suspect is what to do with includes. Where I was working, we made extensive use of the plugin, but topics were assembled from includes. Sometimes the includes were even conditional. If it works this way, then the numbers when viewing a topic would change from those generated when editing, because the includes are not expanded for edit, as well as when editing the include, the numbers would also be wrong. I do agree that this would make things much easier and much more wysiwyg, and would be very useful, but I suspect changing numbers in edit would be worse than not having them at all.

We would need to extend the syntax of the plugin so the result is shown either before or after the standard syntax. These numbers would be totally ignored when you save. They would only be there to aid the editing. They would not update if you insert a section. You would need to cycle through save and edit again.

I added the code in a recent update to skip the plugin for edit for exactly this issue. For some reason - (I suspect a trunk wysiwyg bug?) all of the ##a#.. "macros" in the plugin topic were quietly converted back into hard numbers in the saved topic. It made my testing of code changes shall I say "interesting", until I finally figured out that it was even "working" with syntax errors present.

I am not sure about the syntax. Maybe something like ---##... (1.2.3) or ---##... {1.2.3} or maybe ---###... <!-- 1.2.3 ->

The plugin syntax is a little geeky but since this is a plugin which is an additional feature, people will be more motivated to learn the geekiness.

Numbers inside text like footnotes etc are not so much a problem. It is mainly the section numbers because they help you scrolling directly down to the section you want to edit.

If you have ideas on dealing with the Includes issue, that would be greatly appreciated. Otherwise it would probably be better to make the feature "turn off" when includes are present.

-- GeorgeClark - 20 Jan 2010

-- KennethLavrsen - 20 Jan 2010

Regarding the WYSIWYG integration.

TinyMCE has many useful event handlers to hook into. It is feasible that a plugin using the standard TinyMCE API could parse out the standard ExplictNumberingPlugin syntax, expand them as their calculated section numbers classed in an appropriate <span> which would be converted back before save.

Obviously this means duplicating and verifying against the perl code substantially (maybe it's not a big deal). It also requires sharing alphabet/sequencing settings, unicode support issues etc. And this doesn't solve the problem of editing includes in a coherent manner.

Hopefully one day we can set up a way to teach special syntax to WysiwygPlugin such as this plugin, and code how it should be handled - with a little generic javascript framework that would allow the generic (browser-side) parts work for multiple editors (not just TinyMCE).

This doesn't mean I'm against doing a dedicated ExplicitNumberingPlugin for TinyMCE at this stage, in fact it might be a good adventure to help formulate the support I described above.

Kenneth's approach is certainly easier for now, with the added bonus that it would help with raw editing.

The other approach

I have been meaning to sit down and think about a double-click-to-edit feature which would scroll the editor and select the cursor exact where you were when viewing the document.

Such a feature would be a little more work but would reduce the need for what you're asking for here. These thoughts have prompted me to expand a little in WysiwygEditorAndMacros:

First step is wrapping various TML elements (output of macros, for instance) in specially classed DIVs, Eg, I want something like this done in TML2HTML and Render.pm:

<div class="foswikiMacro INCLUDE" (jqMeta about the parameters) id="foswikiPurpleNo1"> (... contents of Foo ...) </div>

And other elements too:
---++ Some Heading
<h6 class="foswikiTML" id="foswikiPurpleNo241">Some Heading</h6>


   * a
   * b
      * ba
<ul class="foswikiTML" id="foswikiPurpleNo342">
   <li class="foswikiTML" id="foswikiPurpleNo343">a</li>
   <li class="foswikiTML" id="foswikiPurpleNo344">b<ul class="foswikiTML" id="foswikiPurpleNo345">
      <li class="foswikiTML" id="foswikiPurpleNo346">ba</li></ul>

This type of work would go a long way to realising WysiwygEditorAndMacros.

-- PaulHarvey - 23 Jan 2010

Have you seen EditChapterPlugin ? If it were WYSIWYG, it would be exactly the sectional editing feature you need

-- StefanosKouzof - 12 May 2010
Topic revision: r4 - 12 May 2010, StefanosKouzof
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy