Feature Proposal: Additional section include ability

Motivation

I find that section includes can be too daunting for many end users. They're already breaking topics up with Headings, and TOC. Sections should be referencable via Heading name (or Chapters in EditChapterPlugin speak). One quite likely knows the topic name and Heading title of a section they'd like to include in their topic. It seems unrealistic for most end users to construct a regex pattern, and too onerous to save where they're at, go to the topic to be included, insert start and stop include macros, and/or section names. The section already has a relevant section name in the form of the title. It can be assumed that the section ends at the next ---+ or end of Topic.

Description and Documentation

Extend VarInclude with a Heading parameter. Which will do a pattern match on ---+*[Heading name] to the next ---+* or End of Topic.

Examples

%INCLUDE{"TopicTitle" heading="Heading Text"}%

Impact

WhatDoesItAffect:

Implementation

When passed a parameter in an include of:

heading="some text here"

That the include macro would construct a pattern along the lines of:

pattern="^---+*.some.text.here(.*?)^---+.*

-- Contributors: CraigBowers - 01 Jul 2009

Discussion

I see two problems with this

• The included topic will have no signal built in that a section is included anywhere. If anyone changes the header text the including topic will be broken. With the (I admit much more geeky) section macros the editor of the included topic will have to rename the section or remove the macros to breaks things and I believe you are less likely to do that without checking things out first.
• The syntax %INCLUDE{"TopicTitle" heading="Heading Text"}% will to the casual user seeing it used in a topic would more indicate that you include something and put a heading text before the included topic. This could easily be solved by a different word like %INCLUDE{"TopicTitle" includeheading="Heading Text"}% or %INCLUDE{"TopicTitle" headingsection="Heading Text"}% or similar more intention revealing word.

I do understand the problem and I do see in practical life that only the more daring users get to a skill level where they can include sections.

Our current implementation also has the limitation that you need to have edit rights to the included topic to add sections. If you only have read rights the only option today is a regex from hell which is more likely to break when the topic is edited.

So I do not wish to raise concern against the proposal should a committed developer add himself. This was just some food for thinking.

-- KennethLavrsen - 13 Nov 2009

Some valid points, though without an alternative, it still seems to leave section includes needlessly hobbled to rarified atmosphere. It greatly expands the scope but is it feasible for a plugin to TinyMCE to popup a selector allowing the input of a Topic Title, which would then bring up a list of Heading titles. Selecting a Heading would then have to construct an Include statement in the Topic being edited, and then insert the Section start and Stop items in the selected Topic and Heading. That also sounds fragile.

I'm not sure there's any more risk of subsequent edits to Headings breaking section includes than there is to Includes of entire Topics (which is much more approachable currently for end users). Renaming a topic allows the optional repair of references in other topics, but does it update the reference currently in an Include statement? If no the risk is the same as we already have with Include (apart from a statistical greater chance of a Heading edit, over a Topic name edit, which was perhaps your point).

-- CraigBowers - 13 Nov 2009

Interesting idea. Off the top of my head, some issues to consider.

1. Headings are frequently built using macros. ---+ %TOPIC%, for example, which expands to ---+ SimpleVarInclude before final rendering. However the final heading is not available to a pattern match.
2. In the same way, headings can be terminated in a number of different ways - for example, a %INCLUDE that includes a topic that contains a heading. If the pattern has to work on the unprocessed topic (and I can't see how it would work otherwise) it won't see that closing heading.

-- CrawfordCurrie - 14 Nov 2009

I think caching heading sections in DBCacheContrib has been considered before, hasn't it? Certainly MichaelDaum has some experimental code to assume a %META:FIELD{TopicTitle}% based on the first heading found in a topic. I suspect that a few common macros - %WEB% and %TOPIC% could have assumed values for indexing. As for %BASETOPIC% (and all other macros), the only avenue for meaningful titles without trying to expand them each time the topic is INCLUDEd that comes to me... is caching the titles on each view. But then, an INCLUDE would have to have the opportunity to trigger such an expansion too, if the headings aren't available in cache...

-- PaulHarvey - 14 Nov 2009

No activity or developer for 2+ years. Changing to ParkedProposal.