[pmwiki-users] WikiTerms

[Pico]

Patrick R. Michaud wrote:
> On Tue, May 30, 2006 at 03:57:45PM -0700, Pico wrote:
>> To use the example of "title" we have (:title:) page directive 
>> and the {$Title} page variable that would 
>> each point to the same page under your proposal: both 
>> (:[[title]]:) and {$[[Title]]} would point to [[Title]].
> 
> This isn't necessarily a bad thing.  From a typical searcher's 
> perspective, they just know that they're looking for something to do 
> with titles, they don't really know that they're looking for
> "(:title:)" or "{$Title}".  So, we do want all of the different
> forms to appear when someone does "Title".
> 
> As far as telling the difference -- I think a Wikipedia-like
> disambiguation approach might be most appropriate:
> 
>     Title (Disambiguation)
>     Title (Directive)
>     Title (Page Variable)
> 

Wow (+/-)
+ I like the idea of disambiguation pages, in the abstract
- This is starting to seem like a tremendous amount of overhead just to 
support a feature that, at its core, is nothing more than a simple 
pairings of terms and their definitions.

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.

>> From an author's perspective, it would be best if you could 
>> just identify the term, whether (:title:) or {$Title} and 
>> mark it with something that identified it as a link containing 
>> an escaped string.  
> 
> I'm not sure this occurs frequently enough in text to warrant its
> own markup.  I'm not even sure it occurs frequently in PmWiki
> documentation, as a general rule.  Do we have some ready examples
> of pages where the special markup would really be necessary?
> 

No ready examples and, as may be apparent from the above, I would tend 
to place a higher value on providing targeted search results than on 
being able to link terms, when we are talking about simple pairings of 
definitions and terms.  With good search results, links could be based 
on targeted searches.

On the other hand, if we went with a reference group for PmWiki 
documentation, these links would be readily available.

The question, at that point, would be whether the reference group could 
be used as a category, so that links to the reference pages would 
generate listings of referring pages.  In other contexts, Pm has 
explained that he wanted to avoid the overhead of categories in the 
distributed documentation.


>> What would not be helpful, however, is requiring the author to 
>> make the necessary translations between a term and its page name 
>> before being able to refer to it as a term that has been, or 
>> should be, defined [...]
> 
> One of the advantages of a wiki is that authors are never "required"
> to do anything, or to get things right the first time.  The important
> thing is to get the information stored somewhere.  An author can
> create a link called [[title]], and if that goes to the wrong place,
> someone will likely notice it and fix it.  The target of [[title]]
> can then contain links (i.e., disambiguation) that redirects 
> searchers to the correct page, and perhaps encourages them to
> correct the link that brought them to the disambiguation in the
> first place.
> 

Yes.

Pico