[pmwiki-users] WikiTerms

[Pico]

On Tue, May 30, 2006 1:22 pm Patrick R. Michaud wrote
> On Tue, May 30, 2006 at 11:14:21AM -0700, Pico wrote:
> > I am trying to think through a broad proposal for a system that would 
> > make it easier to define, maintain and reference common terms, 
> > including terms that contain special characters, such as "(:markup:)"
> > [...]
> 
> Thanks for starting this -- it's very timely and useful.  
> 
> I'll start with a different perspective on this problem.  I tend to
> want to do things with the tools that already exist, as opposed to
> creating new tools for every situation we can envision.  This was
> true for creating/maintaining the FAQ, and I think it might apply here
> as well.

Yes, that makes sense and it is how I started thinking about this: I walked myself through doing this with a separate group and separate pages.  Here are the notes that I wrote up:

Currently, such a system could be setup by:
1. creating separate pages for each term, 
2. assigning the term to the page name, or title, 
3. assigning the corresponding definition to the description page variable, 
4. adding links to related pages, either manually, or using a category approach, and 
5. linking back to the term page when the using the term on other pages.

That approach works fine so long as the referenced terms can, and should, be turned into separate pages, that is, the terms only contain allowable characters and their role warrant the creation of separate pages (WikiStyle, WikiTrail, WikiWord).   If such terms cannot be stated as valid page names, they can probably be stated as titles, in which case it would be helpful to provide an option that allows standard searches to return titles, rather than page names.  

Limitations only arise when this approach is applied to terms that do not warrant their own separate pages, whether due to their scope (either too narrow or too broad) or their relationship to broader topics.  For example, the [@(:markup:)@] directive is widely applied on countless documentation pages, but is never defined and explained (it is identified on the (undistributed) Directives page and the (index) MarkupMasterIndex page.  Merely supplying the missing definition on some (arguably arbitrary) page does not solve the problem of being able to search for and reference the [@(:markup:)@] directive.  

To incorporate terms that are clustered together on a single page might require adding markup to each of the terms defined on a page and a customized format to the PagelistTemplate, along the lines of what Pm did with the FAQ pagelist: add markup that defines the start (and end) of a term and of its included definitions, and incorporate those in a pagelist formate that returns the page, the term, and the definition.  To facilitate searches, customized searchboxes would need to be added to supply the various parameters.

All the coding work required to provide enhanced search results would still require additional coding to cross-reference to those page locations when the term is used on other pages.  While the coding of anchors will have facilitated this process, in the end, we will still need to determine the name of the page that includes a particular term before we can provide a link to that term.  And then, if the term is ever relocated to a different page, we will need to recode all of the links to refer to the new page.  To tackle that issue, we would have to come up with approach to track the names of pages that contain multiple terms delineated by anchors.

> My first reaction is that if we (temporarily?) suspend the requirement
> that terms be allowed to contain special characters, then we can
> do things using wikigroups.  For example, [[terms/title]] can
> easily link to a page that describes the meaning of the term "title";
> the page describing "title" can easily have full markup.
> 
As noted above, we might not have a problem with special characters if we used the (:title:) directive.

> Or, just put the "Terms" wikigroup into the $PagePathFmt, so that
> [[title]] can automatically find it there.
> 

Could we enable WikiWords for existing pages in the Terms WikiGroup?

> It wouldn't be so easy to have multiple definitions on a page,
> but one could use (:include:) or (:pagelist:) to combine
> several definition pages into an overall summary or list of terms.
> 
> It'd be trivial to use (:pagelist link=terms/title:) to find all
> of the pages that reference the "title" term, or to come up with
> a fmt= parameter that promotes pages in the Terms/ wikigroup to the
> top of the search result list.
> 
> (Or, instead of using wikigroups, one could use InterMap links,
> such that term:title would generate a url for the definition of
> "title".)
> 
> Looked at another way, for a very long time PmWiki (and many other
> wikis) would respond to a request for a non-existent XYZ page 
> with the text "Describe XYZ here."  In other words, the whole notion
> of a wiki is to use pages to map terms directly to a description 
> or definition.  
> 
> I agree there are some details that would need to be handled. 
> For example, perhaps we need to find a way to allow more special
> characters into pagenames (although my first thought is that
> this makes searching more complex, not less).
> 
> Ultimately I think I'd prefer a strategy that allows us to achieve
> the desired results using the existing frameworks we already have
> available, as opposed to layering yet another index, markup, cache,
> and search framework on top of PmWiki.  For any particular capability
> there's a tendency to want to build a complete support system
> around it, when what we really want to do is extend our existing
> systems to be able to handle it (again, the FAQ is an example of
> this).
> 

So, for a concrete example, would you, persoanlly, be willing to accept the addition of a separate WikiGroup with the potential for separate pages to cover each of term (including directives and variables)?  If not, is that because the end result is not important, or because the cost seems too high?

> Pm