Description

This is a meta-bug, but this way the Issue will get some visibility.

Note that the TOC macro is closely related to the include macro and that both are sharing code, copy&pasted.

The Include/TOC macro is a stale mess, that nobody wants to touch. It breaks every aspect of the moinmoin plugin architecture and has numerous known bugs that noone is fixing. It needs to be re-implemented.

Plan

Write a filter-parser

This would take two extra argument, from and to, which would be run against the raw text. It wouldn't differentiate the content type of the raw text at this point, just run the regexps until it finds the section between the from and to. It would copy that part in to a new string which I'll called filtered-raw-text.

After it has the filtered-raw-text it would prepend any prosessing intructions from the original raw page in to it. It would then pass it along for the regular parsing and formatting to take place.

Write the new Include-macro

The include macro would use the filter-parser to parse what is to be included. It would also pass along its own formatter in the Page object, so that the existing formatter instance would be used.

Write a formatter that just collects headings

The include and the TOC macro can use it generate the TOC.

Let the formatter generate ids for the topics

Currently, there is id generation code in the both macros. ID's are necessary to have jump anchors in the HTML. The formatter will generate the ID of every heading and return it via a method call.

Other ideas

Just some vague ideas to keep in mind. Doesn't need to be done all at once, though.

• Pages will be gone soon, there will be Items of arbitrary mimetype (including, but not limited to, text/moin-wiki, text/plain). There also will be image/png or application/msword items. Every item should have some include functionality meaning "show that item here". Of course, for some badly supported stuff we won't have any other means than showing a download link.

• As include depends on item class, include functionality maybe shouldn't be implemented in a macro, but in item class, so it can return some piece of text for text items, an image (<img src=...> for html output) for images and some download links (<a href=...> for other stuff. This can be implemented along the item class hierarchy that parallels mimetypes.

• Returning "rendered" text (see point before) is problematic when you want to do TOC and footnotes. There was the idea of using some internal DOM like representation.
• As generic including is some very basic functionality (as basic as generic linking to some location), we maybe should have markup for that.

Questions

• Does this include plans to improve the functionality and usability of the Include macro, or is it simply a refactor? In my opinion, the include macro needs a complete re-think, starting with a description of how it should work. (Currently, the description of the macro is too terse to really know how it is intended to work.) -- SteveDavison 2006-06-16 19:49:04

Current status

There is now an Insert-macro in the docbook-branch. This macro can live alongside the Include macro. It does basically what the old Include macro did, but the code is a bit cleaner, and it uses the current formatter, instead of instanciating a new one. The code should also be quite a bit cleaner and easier to understand. It doesn't use an external filter parser, instead it simply does it it self.

• http://hg.thinkmo.de/moin/1.6-docbook-mvirkkil?f=9fa31589f151;file=MoinMoin/macro/Insert.py

• arguments:
  • pagename only mandatory argument, can be regex, just like Include
  • from= same as Include
  • to= same as Include
  • into= depends on formatter. On html it will generate a link
  • title= the title of the "into" part, usually the link text

  • sort= if not specified -> no sorting, if specified either ascending or descending

  • skip= how many pages to skip, before starting to include pages
  • items= how many pages to include in total

Missing features compared to the Include macros documentation:

• heading - Text for the generated heading which will link to the included page (optional).
  • Could easily be added, but I see little point to this feature
• level - Level (1..5) of the generated heading (optional).
  • Could easily be added, but I see little point to this feature

• editlink - add a footer with links to the included page, both normal and edit (optional, available since MoinMoin 1.3.4).

  • Not sure how/if this works
• titlesonly - Only include a link to the page, not page content (optional).
  • Could easily be added, but I prefer the new "into" way of doing it.

Related bugs

Related feature requests

CategoryMoinMoinBug CategoryForMoin2