Add findhelp subcommand to assist with VS Code integration

[sfkleach]

The next step for VS Code integration is to be able to retrieve Poplog documentation. However the Poplog help system is not declarative but procedural and not static but extensible. So an accurate integration requires an "API" into Poplog. The natural place to supply that API is through the poplog-command itself.

This change makes it possible to extend the poplog-command using autoloadable Pop-11 files, to provide a subcommand extension that can interrogate the file-based documentation using the internal library functions, and to list the results as JSON.

In essence:

• A command of the form poplog findhelp <options> <topic> that is available on a standard installation of GetPoplog. Options that take arguments will be of the form --{option}={value}.

• Which allows for the specification of a single category e.g. poplog findhelp --category=help <topic>.

• There are 5 categories: help, teach, ref, doc, showlib. The default category is 'help'.

• An exact-match can be specified e.g. poplog findhelp --exact <topic>.

• The response will be a ranked list of matches in JSON format; a schema will be provided. It will include:

  • version of poplog

• Each match will include:

  • quality of match (from 0.0 to 1.0, 1.0 being best)
  • title of matching resource.
  • summary - a short description, which may not be available, signified by null.
  • category - n.b. a search in one category may legitimately yield matches in another)
  • file-path - the absolute file path as a string.
  • from line number in the file at which the description starts, may be null.
  • to line number in the file at which the description finishes, may be null.

The schema for that JSON is available as a gist and also included below for convenience:

{
  "$id": "https://github.com/GetPoplog/findhelp.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "FindHelp",
  "type": "object",
  "properties": {
    "version": {
      "description": "A string describing the version of Poplog.",
      "type": "string"
    },
    "documentation": {
      "description": "Matching documentation.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "quality": {
            "description": "A number from 0 to 1.0 indicating the match quality, with 1 being a perfect match.",
            "type": "number"
          },
          "category": {
            "description": "The category of documentation, reflecting the level formality and technical detail.",
            "type": "string",
            "enum": [ "help", "teach", "doc", "ref" ]
          },
          "title": {
            "description": "The title of the resource.",
            "type": "string"
          },
          "summary": {
            "description": "An optional summary of the resource, which may be null.",
            "type": ["string", "null"]
          },
          "path": {
            "description": "File path of the resource.",
            "type": "string"
          },
          "from": {
            "description": "Line number the description starts on (1-indexed), which may be null.",
            "type": ["integer", "null"]
          },
          "to": {
            "description": "Line number of the last line of the description (inclusive), which may be null.",
            "type": ["integer", "null"]
          }
        },
        "required": ["quality", "title", "summary", "path", "from", "to", "category"]
      }
    },
    "required": ["popversion", "documentation"]
  }
}