Question

I am looking for a convenient way to auto-generate a glossary without actually writing the glossary entries in one large (like TWikiVariables) or in many small articles. What I have in mind is that authors can make every topic a contribution to the glossary.

However, over time an article may become too long to really fit into a glossary which should just be a concise definition of an item. In this case I'd like to avoid having to split into two topics FooBar and FooBarGlossaryEntry or similar.

My requirements are:

1. Topics containing glossary entries should be comprehensible as standalone topics so that it is easily possible to link to particular entries from anywhere.
   • Named anchors within a big glossary topic are too rigid IMHO.
   • It should be possible to develop a glossary entry about FooBar into a full blown article without having to rename the topic or adjust the links from the glossary.
2. From the complete glossary, a link should be provided to the standalone topic - just in case.
3. TWikiForms are a bit too clumsy, or to be honest: I am not familiar enough with them.
4. I consider Tables or <dl> markup not sufficient for a glossary because they have too much restrictions with regard to TML markup (multi-paragraphs <dd>s and nested tables are impossible).

I have found a solution (see below) which almost suits me - with a minor exception: I could not figure out how to look for the percent sign in %SECTION{}%. It has a drawback of becoming rather slow in huge webs, and it relies on being able to search for things which are visible in TML, but not in HTML.

Two questions in this context:

1. Is there a "standard" - convenient - best practice way of doing this? I'd like to learn what others are doing...
2. Could this be a way to allow a merge of the documentation between core and plugin variables in TWikiVariables (see CleanUpTWikiVariables)?

Environment

-- HaraldJoerg - 02 Feb 2006

Answer

This is what I am using at the moment: In a topic which should be included in the glossary I define a named section glossaryentry.

---+ Foo Bar (AKA Fubar)

%SECTION{"glossaryentry"}%
  A !FooBar is like a crossbar, only more foo.
%ENDSECTION{"glossaryentry"}%

Note that the headline is explicitly excluded from the section - this makes it possible to use different formats in the collective glossary.

In the complete glossary, I'm using the following SEARCH (linefeeds added for better legibility - please remove them if you want to use it):

%SEARCH{"SECTION{\"glossaryentry\"}" 
        excludetopic="TrioleGlossary,TRIOLEGlossaryEntry"
        noheader="on" nosearch="on" nosummary="on" nototal="on" 
        format="---++ [[$topic][$pattern(.*?---\++([^\n\r]+).*)]] $n 
                $percntINCLUDE{\"$topic\" section=\"glossaryentry\"}$percnt" }%

It creates a <h2> element containing the first heading of the glossary entry (sometimes easier to read than the topic name) but is linked to the topic.

-- HaraldJoerg - 02 Feb 2006

If you answer a question - or someone answered one of your questions - please remember to edit the page and set the status to answered. The status selector is below the edit box.