Consider a simple core help text for color module:

The color module allows a site administrator to quickly and easily change the color scheme of certain themes. Although not all themes support color module, both Garland (the default theme) and Minnelli were designed to take advantage of its features. By using color module with a compatible theme, you can easily change the color of links, backgrounds, text, and other theme elements. Color module requires that your file download method be set to public.

It is important to remember that color module saves a modified copy of the theme's specified stylesheets in the files directory. This means that if you make any manual changes to your theme's stylesheet, you must save your color settings again, even if they haven't changed. This causes the color module generated version of the stylesheets in the files directory to be recreated using the new version of the original file.

To change the color settings for a compatible theme, select the "configure" link for the theme on the themes administration page.

For more information, see the online handbook entry for Color module.

What if we had some type of syntax to provide index entries for this help text, and then code in advanced help (or in the core module implementing advanced help features) that automatically displayed these index entries.

Color module index entries may include:

Garland:change color of
Minnelli:change color of
files directory:color module's use of
re-colorable themes
colorable themes
color module

In the automatically generated index, entries without a : would be at the root level of the index, while entries with a : would be included as a entry underneath a main entry, like:

color module
colorable themes
files directory
  color module's use of
Garland
  change color of
Minnelli
  change color of
re-colorable themes

Each entry would link to the page that provided it.

Any thoughts on the syntax of this? What would be the best way to delimit these index entries in the html file itself?

Comments

keith.smith’s picture

Or, alternatively, perhaps index entries should be included in the *.help.ini files themselves?

merlinofchaos’s picture

I think this is neat, though potentially somewhat difficult to achieve, in the sense of actually setting up all of the text to do this. I think actual implementation isn't too difficult, though we have to be careful to choose a syntax that will not interfere with the actual text, and of course, we need to make it easy for translators to preserve the proper words.

I think I am more in favor of creating a keywords selector in the .ini file, which will not require additional filtering of the text and is probably easier on translators, but that is more of a 'leaning' than a preference and would listen to discussion in either direction.

fgm’s picture

Status: Active » Postponed (maintainer needs more info)

If I understand you well, this type of need is covered by using headings in the page text and something like #818946: New table of contents feature (6.x and 7.x) to generate the index/ToC. This approach does not require any additional domain-specific markup.

Is this what you are suggesting ?

gisle’s picture

Status: Postponed (maintainer needs more info) » Closed (won't fix)

Five years in the state "Postponed (maintainer needs more info" has passed with no follow-up information. Time to close.

Please feel free to reopen (explaining in more detail what it is you request) if you still think this is an issue.