• View
• Edit
• History
• Print
• Backlinks

WikiTerms-Proposal

Overall goal

Provide a system for defining and referencing frequently used terms, including terms that contain special characters, such as (:markup:), where such terms can be defined on any page, and their definitions and locations can be returned when the terms are used in a search or link.

Background

The idea for this proposal arose in the context of PmWiki documentation and, specifically, to address issues of ensuring that basic terms (including functions, markup and variables) are defined, current, consistent and easily findable through a simple search. The potential application extends well beyond PmWiki documentation and can be particularly appropriate in any context where terms need to be defined and easily searched and referenced.

Desired features

1. Enhanced definition markup and tracking where:
   • A term can include markup and special characters: no markup rendering is applied to the term (see the (:title:) directive and note that html definition lists allow for a title attribute).
   • more than one term can be defined on a page (a pagevariable array?)
   • more than one page can contain defined terms (i.e. don't restrict to a WikiTrail or XLPage approach)
   • the location -- page and position (anchor, line, etc) -- of each term is efficiently tracked (cache pairings of terms and their locations)
   • the format of the term and definition pairing is distinctive (boxed, or light background, etc).
2. Enhanced search results that:
   • display term and definition together with link(s)
   • highlight (by promoting to the top of the results), or single out (by limiting results) the displayed term and definition, or both
3. Enhanced linking where:
   • authors can link to a term without knowing the location where that term is defined
   • linked term can be entered and displayed as escaped markup, i.e., type something like ``(:title:)`` to generate a link like (:title:) that points to the page and location where the (:title:) directive is defined.
   • distinctive display of links (add italics, use dotted underline, or add icon), e.g. (:title:)
   • distinctive display of undefined terms (question mark) e.g. (:title:)?
   • definitions available as tool tips (onmouseover)

Proposal viewed from existing PmWiki features

In response to Pm's comments on the list, this section looks at this proposal from the perspective of PmWiki's existing framework.

Using definition lists

Pm created a wonderful system for using definiition lists to store and track variables where:

1. Certain strings (a dollar sign followed by a WikiWord)
2. Are rendered as links to the page and location where such strings have been defined, where
   1. The possible source pages are specified by a trail appearing on a designated page (Variables)
   2. The strings are defined using ordinary definition list markup, where the string is the term
   3. Undefined strings render as ordinary text
3. The code is provided by the vardoc.php file
4. See Pm's post

This approach looks really good, and would be great feature even if it was only extended to delineated WikiWords (i.e. not to string contained markup). So far, however, Pm has not seen the markup, or the broad appeal, justify extending this as part of the core. See Pm's post. Note that Cookbook:AtLinks by PRZ uses an at sign (@) to delineate links.

Using separate pages

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.

(:searchbox trail=PmWiki.DocumentationIndex "[[#faq]]" fmt=#includefaq order=name:)

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.

Splitting proposal (from list posting)

At this point, the temptation is to split off the proposal into different pieces: (1) improved searching for defined terms and (2) a reference system for PmWiki terms, directives, variables, and functions.

1. Improved searching for defined terms.

In Google, you can preface a search with "define:" and get a targeted result. For example, if I do a Google search for "define:PmWiki" I get the following results:

Definitions of PmWiki on the Web:

PmWiki is free wiki software written by Patrick Michaud in the PHP programming language. en.wikipedia.org/wiki/PmWiki

That's it, nothing more, nothing less. How could we support such a functionality?

The ability to target a search to some identifiable portion of a page would seem like a great improvement that could start to address many of the issues that have been raised about search results. For example, if a search could be limited to a particular division and could return the entire text of that division, then authors could structure their content accordingly, for example:

>>define<<
PmWiki is free wiki software written by Patrick Michaud in the PHP programming language.
>><<

If a search could be limited by division name, then the above-referenced description would be returned when a search was posted for "define:PmWiki". Note, however, the same results would appear if I searched for any other term included in the division, e.g., "define:PHP" or "define:programming" The ability to search portions of a page, or specific divisions, could be a great feature.

When it comes to defined terms, however, It would be even better if we could make use of the existing html and PmWiki feature of defined lists. Using the example above, if we added the following to a page:

: PmWiki : Free wiki software written by Patrick Michaud in the PHP programming language.:

Could we then provide a search functionality where "define:PmWiki" only searched the term (DT) portion of definition lists and reported that together with the definition (DD) portion?

That would be really great. If we went down that road, we could simply use the existing PmWiki markup for definition lists. While authors may use definition lists for its style, rather than as an indicator of content type, the consequences might not be very noticeable, since the search would only be looking in the term (DT) and, if the searched term was over-reported in this way, the results might still seem pretty relevant. An alternative might be to use this opportunity to consider adopting an enhanced definition list PmWiki markup, such as the extended markup recipe, or adopting the term attribute of html definition lists, and tie such markup more directly to definition content and searching.

2. A Reference system for PmWiki terms, directives, variables, and functions.

If we went down the road of establishing a new group with separate pages for the various terms, directives, etc., in PmWiki, then I think it would make sense to provide more content than a simple definitional snippet.

Such pages could include basic reference information identifying the type of term, e.g. inline markup, start of line markup, page variable, page directive, etc., which we could then use to generate pagelists of page directives, for example.

The reference could also include basic information identifying allowable arguments and parameters and useage.

When Pm introduces new markup, he could create a new page and record the basic information (including the version number) leaving others to come along and incorporate that into the existing documentation.

When Pm adds enhancements to markup, entries could be added to that page that identifies what was changed and when (version number). That could be great for troubleshooting. For example, when a user finds some wonderful markup but can't get it to work on their PmWiki (e.g., think of the various enhancements to pagelist), they can check the reference page for pagelist and see that what enhancements were added in more recent versions of PmWiki that theirs.

Comments

If I understand the proposal correctly, I'd like to suggest that we design the feature to allow for site-wide terms, group terms and page-specific terms. Scott Connard

Possible approaches

• Use PageVariables to establish the initial assoication between a term and its location, assuming that such variables can embrace arrays where multiple keys (the terms) are defined by authors, using markup, rather than by administrators using functions in php files
• Use a cache to store the associations between terms and their locations
• Update cache only when necessary, when the page has been saved or, better yet, when the array has been changed.

Possibly related features and proposals.

• Cookbook:SubpageMarkup
• FAQs Pagelist

List discussion

Original thread