Feature Proposal: Allow an Include or a Search to increase/decrease header levels of extracted text

Motivation

One of TWiki's strengths is the ability to reuse information from other pages using the %INCLUDE and %SEARCH% variables.

However the headers in the included text often don't fit into the new header hierarchy in the including page. This isn't surprising since the headers of the included page form their own hierarchy that doesn't need to match that of the including page.

For example: I include a section of the page IncludeMe that has headers at level 2 and 3 (---++ and ---+++). I want to include the text under a header at level 3. Currently I will end up with level 3 header from the including document, followed by a level 2 header and a level 3 header from the included document.

What I need is a level 3 header from the including document and the level 2 header from the included document moves to a level 4 header. Then the level 3 header from the included document moves to level 5 to maintain the relative header relations of the included document within the including document.

Description and Documentation

I suggest adding a new parameter headershift to %SEARCH% and %INCLUDE%. It will take a single integer argument in the range -6 to +6. It will accept a value of 0, which produces the same output as when the parameter is not seecified.

It will take any headers in the included/search extracted text and shift them by the specified amount. Positive numbers shift away from an H1 header toward an H6 header. Negative numbers move in the opposite direction.

Example:

The twiki variable:

 %INCLUDE%{"!ThisTopic" headershift="2"}%

will take any header at level 2 in the included part of ThisTopic and shift it to level 4. A level 3 header becomes a level 5 header and a level 4 or greater header becomes a level 6 header (since there is no H7 tag in html).

Similarly:

 %SEARCH%{"!ThisTopic" headershift="-1" format="%pattern(...)"}%

Will move an H6 tagged item to header level 5 (H5). Any level 1 or 2 header item in the extracted part of ThisTopic becomes a level 1 header in the displayed document.

Examples

Impact

Implementation

-- Contributors: JohnRouillard - 09 Apr 2008

Discussion

I agree - I would also like to see a headershift="relative" which would rejig the header levels to put the INCLUDED headers automatically to the correct level for the topic its being brought into - though this will need to have some sort of delayed processing, where all the other TML processing is done, then the heading levels are resolved.

Additionally, it would be useful to be able to set a min and max header limit for a web / twiki - I'd like my topics to never define a h1, irrespective of the user's input, as the h1 is set via a topic name / heading, which is then the same as the title...

-- SvenDowideit - 09 Apr 2008

This is done for INCLUDE in IstanbulRelease in RelativeHeadingLevelsforINCLUDE. Feature pending for SEARCH.

I suggest to create a new feature proposal for adjusting header level of SEARCH.

-- PeterThoeny - 2010-07-29

Let's close this proposal. Follow-up for SEARCH enhancement in RelativeHeadingLevelsforSEARCH.

-- PeterThoeny - 2010-07-29