Add a config parameter "documentation"

[aplteam]

While info_url is supposed to be something like a URL pointing to a web site or a GitHub project or something similar, documentation is supposed to point to, well, documentation.

[DavinChurch]

I would consider help and documentation to be somewhat different. I would expect documentation to lead me to a complete manual where all the detailed information was kept but I would expect help to lead me to a quick-reference that just reminds me of commands and syntax.

[aplteam]

All true, but it's up to the package author: you may just provide help with "documentation" but list the full documentation on where info_url points to. Or not.

[DavinChurch]

Well, it's not that important to me, but personally I would have two different ways of getting two different kinds of information, depending on what I needed at the moment. For my purposes, I'd use the like for a quick-reference help only and if they want the full documentation then they can go to the url link and download it. That's rather the opposite of the naming, but it will do. I just didn't think it would be more than 5 minutes' work to add another name next to the one you've got. Davin

[aplteam]

Davin, what exactly would the field carry in order to provide help of any kind? A URL, right?

[DavinChurch]

I think a URL is probably most practical, if you have to choose only a single method. An actual piece of text/markdown would be more useful in many cases, but I don't think that it's too supportable that way. A URL makes more sense for most people even though I can envision circumstances where toolmakers might not be using something like GitHub to hold their system and thus wouldn't have a good URL to refer to. I suppose in such cases they'll just have to do without.

For my current tools, for instance, I might use the documentation URL to point to my full manual and the info/help URL to point to the ReadMe or similar short quick-reference file. I could always use the text from one of them to mention where the source code was kept, if it wasn't obvious (such as in the same GitHub repo).

Other options might be:

• What about making either URL able to accept an email address in place of a URL? That way if a small developer doesn't have their system on-line they could use the email to request details.
• Or perhaps the files might be available via old-fashioned FTP instead of HTTP (though I doubt anyone would be using that method any more)?
• Or it's still conceivable to use (very short) plain text to provide the description, such as "See function XYZ for a quick reference"?
• Or even just provide the name of a function directly which could present the help/documentation itself (and invoke it with a click or Tatin-provided function call)? This might do markdown processing (or obtain dynamic data) at execution time.
• In fact, having a Tatin-provided function (e.g. _TATIN.HELP) to interpret and execute these "links" in the first place could be very handy to call manually or under program control.

There are certainly a number of non-URL options possible, if you'd like to consider any of them.

[aplteam]

Thanks for that.

I've outlined it this way in the documentation:

---

documentation

This can be one of:

• A URL pointing to an online help resource

  It is identified by starting with either "http://" or "https://".

• A local path pointing to a file (or program) within the package

  In this case it must be a relative path since you cannot know in advance where your package ends up.

  It must start with "./".

• A pointer to a function or a variable inside the package

  It must start with "⎕THIS.", and an object with the given name must exist inside the package.

Content that does not qualifiy for one of these will be rejected.

---

I think that gives a lot of freedom to a package author.

Note that an email address will become available soon by other means ("maintainer").

[DavinChurch]

That sounds pretty good. Will there be a Tatin-level function (_TATIN) interface to the documentation & help as well as a command-display (]TATIN) level?

[aplteam]

No, I don't think so, it looks a bit like overkill.

[aplteam]

Added with 0.72.0