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.
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.
(:title:) directive and note that html definition lists allow for a title attribute).
``(:title:)`` to generate a link like (:title:) that points to the page and location where the (:title:) directive is defined.
(:title:)
(:title:)?
In response to Pm?'s comments on the list, this section looks at this proposal from the perspective of PmWiki's existing framework.
Pm created a wonderful system for using definiition lists to store and track variables where:
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.
Currently, such a system could be setup by:
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.
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.
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.
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.
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?