Relative Heading Levels for INCLUDE

Motivation

Heading levels can be off when a big document is composed of many included topics. This can be fixed of there is a way to adjust the level of headings in INCLUDEd topics.

Documentation

Add this in VarINCLUDE:

Example

SomeTopic has this:

---+ Cars
---++ Sedans
---+++ BMW
---+++ Mercedes
---++ Trucks
---+++ Mack
---+++ Volvo

Now, if you %INCLUDE{ "SomeTopic" headingoffset="1" }% you get this result after the include:

---++ Cars
---+++ Sedans
---++++ BMW
---++++ Mercedes
---+++ Trucks
---++++ Mack
---++++ Volvo

E.g. it changes H1 to H3, H2 to H4, etc.

-- Contributors: PeterThoeny - 2010-06-22

Discussions

I use %INCLUDE ... fairly regularly.

It always places me in a quandary: should I start my include headings as level H1, e.g. ---+, or should I arrange them to start at some deeper level, like H3, ---+++.

If I start at H1, then the included headings may mess up a table of contents in the includer.

If I start at a deeper level, then the page itself may look a little bit odd.

Enhancement request: add a parameter to INCLUDE to indicate what heading level ---+ should correspond to. E.g.

   ---++ H2
   %INCLUDE{PageBeginningAtH1,"header_level=3"}%

-- AndyGlew - 26 Oct 2004

Interesting idea. If we had ParameterizedIncludes you could do this:

   ---++ H2
   %INCLUDE{"PageBeginningAtH1" hbase="+++"}%

---%hbase% A heading

-- CrawfordCurrie - 26 Oct 2004

I asked the same question in Support.AdjustingHeadingsDuringInclude

-- MartinCleaver - 26 Oct 2004

It's not clear from above if this is intended so I'll say it.

The base should be reletive to the lowest non-hidden (from TOC) heading of the included topic. So if you include with a base of ---+++, it would skip a ---+!! heading, find the lowest (not necessarily first) non-hidden heading of ---++ and then increase all headings by 1.

-- SamHasler - 26 Oct 2004

Dynamically showing sections depending on their header level was not meant, I think. Wouldn't NamedIncludeSections and hand-crafted including topics already address that need?

AndyGlew addressed tho old problem, that topics have fixed header levels in them. If you want to re-use a topic in a bigger paper, the header levels can be right only for one view. So either your single page has odd tiny headings, or your big printed manual has a lousy table of contents, see TWikiForBookAuthoring or PrintUsingPDF.

The proposed syntax of INCLUDE{... hbase="+++"} looks good. Not sure I would want to edit all included topics to switch to
---%hbase% A Variable Heading. Why not simply let them as-is, implicitely adding the hbase on the go? So you write
---+ A Fixed Heading Level 1, but within an
INCLUDE{... hbase="2"} it would turn into <h3>. Recursive INCLUDES should add relative to the current shift level, then the end of the INCLUDE would restore the previous shift level. An absolute shift is easier to implement, but would introduce the same problem again, if you include including pages.
Hmm. A relative level is probably more appropriately named hshift

-- PeterKlausner - 29 Oct 2004

"Dynamically showing sections depending on their header level was not meant, I think."

It's not what I meant either. By skip I meant for the purposes of determining relative heading levels, all the included content would still be included. Now that I think about it, it's not a good idea. Headings that don't appear in the TOC are usually

The reason I think the base should be relative is so that you can change the depth of all the headings in the included topic to be one deeper/less deep without affecting their depth in the topic they are included into.

-- SamHasler - 29 Oct 2004

It would be really good if someone took ownership of a project to address this question. I can offer an extended include, but it's obvious from the various plugins and TWikiForBookAuthoring that some greater smarts need to be applied to headings, web-wide, in includes, and the assembly of TOX.

-- CrawfordCurrie - 29 Oct 2004

A guest in Support.IncludingTopicButLoweringHeadingLevel suggest this syntax:

%INCLUDE{ "UsingAMainpage" level="-1" }%

-- PeterThoeny - 21 Feb 2005

rather than specifying a parameter for the inlcuded headings, why not just make them all relative to the location in the parent document they're being included into? So if they are included after a ---++ the included H1 becomes an H3?

-- MattWilkie - 21 Feb 2005

I think that the suggestion is better than the current behaviour. How about we introduce a flag and preference to disable the suggested new behaviour?

-- MartinCleaver - 13 May 2005

Which suggestion?

-- ArthurClemens - 13 May 2005

I recently brushedoff my LaTeX for some documents. One of the first things I did was create "dySection" commands to allow me to include other files and adjust the heading level.

-- AndyGlew - 24 Jun 2005

Is there anyone working on this? Or is there another means that this functionality has been implemented?

-- DanielHelsten - 05 Jun 2006

The direction I am headed towards is to include all of the wiki markup language, scan it, look for the highest heading level, and use that to adjust the heading level.

E.g.

I also need this to work for EmbedTopicPlugin

-- AndyGlew - 09 Jun 2006

Oh, yeah - I did not mean conditional inclusion. That's a separate topic. Here I just meant adjusting the header levels.

-- AndyGlew - 09 Jun 2006

As for work status - my current pet project is to convert wiki markup language to LaTeX, so that I can get a nicely formated document printed. I needs must do this header adjustment as part of this process, although, as already noted, I have my LaTeX dySection macros to do it for me.

By the way, if anyone has Wiki markup language to LaTeX, please tell me. I'm also considering plain old HTML or XHTML to LaTeX.

-- AndyGlew - 09 Jun 2006

anybody working on this feature ?

in my opinion an implementation of AndyGlew's proposal of 09 Jun 2006 E.g.

would be the the optimal solution and would result in a big boost to the technique of INCLUDing Topics (unfortunately I'm not able to do this work by myself)

-- ThomasDoetterl - 10 Nov 2006

First, the spec should be further clarified.

E.g., what happens if you are in a section at level ---+++ and you are including text that is at level ---+? Should that become ---++++? What about if you include text that is at level ---++ and below. What should that become? My intuition says ---++++, but probably a good argument could be made for ---+++++ also.

Further, what should happen if text is included that is below a heading, but the %STARTINCLUDE% is after the heading? Does it get the level it has in the included topic or is it assumed to be outside all levels?

Depending how fancy this should be, we need something like the solution for NeedBeforeIncludeHandler.

-- ThomasWeigert - 13 Nov 2006

Auto-adjusting levels sounds useful. For compatibility I suggest to add an explicit flag, such as autoheadinglevels="on".

-- PeterThoeny - 13 Nov 2006

RE: ThomasWeigert - 13 Nov 2006
I think the machinery should be as simple as possible so I suggest

• only look at the included "text" no matter how the context (i.e. the heading-structure) looks in the source-Topic
  => if the in the source-Topic excludes a heading -> ignore it
  • rationale: the author of the sourc-Topic explicitly did not want it to be included in other topics
    (by placing the )
• the highest Level in the source-Topic should be adjusted to be one level under the current level in the destination-Topic
  this normally results in decrementing the heading-levels of the icluded text
  however, it could also result in incrementing it
  • rationale: the author of the destination-Topic deliberately places the INCLUDE-clause below a specific heading
    so the following "chapters" should be "sub-chapters" of this heading

e.g.

-- ThomasDoetterl - 13 Nov 2006

I have implemented something simple, which may not solve all problems, but may be is a step in the right direction. Look at the patch for all the details, documentation (patch to VarINCLUDE) and demo in IncludeTest (name collision here!). The basics is that it just uses the proposed %EXTRA% hack, except you don't need to change the included document so it still can be used stand alone.

• simple-include-offset-headings.diff: Simple headings offset patch

• simple-include-offset-headings-v0.2.diff: Simple headings offset patch, version 0.2, with recursive support and better examples

-- MarcSCHAEFER - 27 Nov 2007

Here's an easy to grasp spec that should do in most cases: All levels of headlines are relative to a root. On a normal topic view, the root starts counting at level zero. An include happens on a certain level of headlines and this becomes the new root for the included text.

So including a ---+ inside a ---+++ will result in the same header level ---++++ as the other way around.

IMHO, the depth of INCLUDEs should not be taken under consideration when computing the resulting level, as these might happen quite arbitrary.

-- MichaelDaum - 29 Nov 2007

considering the numbe rof times i've come across a topic that has no h1 and h2 headers 'because they looked too big' I agree with what Michael is saying:

the header depths should be brought in as relative, not absolute, with the lowest level in the INCLUDEd section being either the same as the current level they are brought in to, or one smaller.

This is probably time for a diagram, but I think I'll goto sleep instead.

-- SvenDowideit - 29 Nov 2007

I agree that relative is more useful than absolute. I'd go so far to use an offset, e.g. a %INCLUDE{ "SomeTopic" headingoffset="+2" }% changes H1 to H3, H2 to H4, etc. (I just realize that was already suggested inSupport.IncludingTopicButLoweringHeadingLevel.)

-- PeterThoeny - 03 Dec 2007

fix for the previously documented implementation

• simple-include-offset-headings-v0.3.diff.gz: Simple headings offset patch, v0.3

-- MarcSCHAEFER - 29 Jan 2008

This proposal has been lingering for a long time. I defined a spec (see above) and put myself as committed developer.

-- PeterThoeny - 2010-06-22

This is now AcceptedBy7DayFeedbackPeriod.

-- PeterThoeny - 2010-06-30

Now implemented and documented in SVN trunk.

-- PeterThoeny - 2010-07-07