Recent Changes - Search:


PmWiki Help

edit SideBar



Currently, feature discovery in ibid consists of saying 'features' to the bot, and getting a very long, unwieldy, and unhelpful list of features, which you then have to dig into using 'help' and 'usage'. Plugin reorganisation has grouped them more logically into files, but we do not want the file in which a plugin resides to have anything to do with the features it provides, or the help you can get on it.

Solution architecture

To assist with feature discovery, we will add an additional layer of querying - categories.

Each feature can be tagged as falling into multiple categories. Each processor can implement multiple features.

Each feature and each category will have plain English descriptions, and each processor will have a usage string. Since features group multiple processors, features will be able to generate their own usage strings by grouping all the usage strings from their processors.

Solution overview

When the user asks something that looks like a feature discovery request, the bot iterates through all the categories it has defined (but only the ones that have one or more features currently enabled/loaded), and gives their English description to the user:

 User:  What can you do?
 Bot:  I can: lookup stuff, convert things, remember things

The user then drills down into one of these categories, and the bot lists a friendly name for each feature that falls in that category:

 User:  What can you lookup?
 Bot:  Factoids, dictionary definitions, stuff on google, ...

The user can then ask for help on a particular feature:

 User: How do I use factoids?
 Bot: <usage string for factoids, constructed of the usage string for each processor that implements factoids>

We can use helpful help for this too, although we should reformulate this to be a bit more friendly. It currently works as follows:

 User: features for calculate
 Bot: Are you looking for bc, hash or nickometer?

Note that most plugins will declare themselves to implement both an overarching features ("quotes" for, FML, MLIA, etc), but will also probably declare themselves part of their own hidden mini-feature ("bash", "fml", and "mlia"). See below about hidden features.

Other requirements

Users and owners should also be able to do the following:

  • Query simple descriptions of features, processors and categories - akin to 'help' currently
  • Query what plugins are loaded (lsmod)
  • Find a link between plugins and features ("What plugin gives me 'insults'?")
  • Load and unload particular features, or entire plugins


At the top of a plugin, categories will be declared, along with their friendly description. Then, features implemented in that plugin will be given a friendly description, and linked to one or more categories.

Since multiple plugins can declare the same category, the English description of one might be overridden by another. This is fine. In addition, multiple plugins might implement the same feature, and this could also result in description override. This is also fine.

# Plugin 1:
ibid.categories['lookup'] = "look stuff up"
ibid.categories['calculations'] = "calculate stuff"

features = {
    'bash': {
        'description': 'get quotes',
        'categories': ('lookup'),
    'google': {
        'description': 'google stuff',
        'categories': ('lookup'),
    'calc': {
        'description': 'calculate things',
        'categories': ('calculations'),
    'quotes': {
            'description': 'get quotes',
            'categories': ('lookup',)

def Bash(Processor):
   features = ['quotes', 'bash']

def Google(Processor):
   features = ['google']


ibid.categories['arbstuff'] = "Do random stuff, like Bryn."
features = {
    'quotes': {'categories': ('lookup', 'arbstuff')},
    # no description given - previous plugin defines it.  If it was given, it might override the previous plugin.

Note that a feature might not be linked to any categories. If this is the case, it is a "hidden features" - it can be queried for help and usage, but won't be discoverable by drilling down through categories. This is fine.

As described above, most processors will declare themselves to implement their own hidden mini-feature. This is so that somebody can treat "look up stuff" as a feature in itself, and query it fine, since most users will see it as a feature by itself, as opposed to simply a subset of a larger feature.

Possible problems

Linking descriptions to internal names

English descriptions for categories and features are fine, but "I can look stuff up" gives no indication of how I can query what is in 'lookup'. We could mandate that the English descriptions have some sort of link: "I can [lookup] stuff", "I can [convert] things", but this will put restrictions on both the English, and the names of features and plugins (as the names will have to fit into English sentences). Maybe a better (but uglier) way would be to just link to the name after each description: "I can look stuff up [lookup]", "I can convert things [conversions]", etc.

Undeclared help strings

Some features and processors may not declare English descriptions. We could consider this to be a bug in the feature, but we should handle it gracefully, maybe just using the feature name as a placeholder?

Edit - History - Print - Recent Changes - Search
Page last modified on January 24, 2010, at 01:34 PM