Command help location is unreliable

Omikhleia commented 2 years ago

Greetings

SILE 0.10.15 on Ubuntu 20.04

Here is a dump subset of the SILE.Help keys, and the where field of each element.

discretionary: baseclass
dotfill: leaders
dots: autodoc-test.sil
eject: </usr/share/sile/classes/plain.lua:111>
em: </usr/share/sile/classes/plain.lua:111>
enskip: </usr/share/sile/classes/plain.lua:111>
enspace: </usr/share/sile/classes/plain.lua:111>
epigraph: experimental
epigraph:font: experimental
epigraph:source:font: experimental
filbreak: </usr/share/sile/classes/plain.lua:111>
folios: folio
foliostyle: folio

What's wrong with it:

"where" is a poor name for an obscure concept ;) Would a "location" or a "package" name have been intended?
Sometimes it's a full path name - visibly for commands described in SILE scripting (= \define)
Sometimes it's just supposed to be the package name, extracted from the path name - visibly for commands implemented in LUA (= SILE.registerCommand)
Moreover, look at the "epigraph" command (my own package): the file at that point was (some personal path)/packages/epigraph-experimental.lua). It turns out that SILE.registerCommand uses an incorrect regexp:
```
  pack = where:match("(%w+).lua")
```
Additionally, it turns out that SILE.registerCommand can take an explicit package name as argument:
```
SILE.registerCommand = function (name, func, help, pack)
```
It doesn't seem to be widely used (if at all), but the concept seems broken to me, it the "where" field sometimes refer to a path or file name, and sometimes to some string a user / package writer could have (possibly incorrectly) passed.

alerque commented 2 years ago

Confession time? I've actually never made any use of the inline help system at all. Maybe zero. If the documentation doesn't get me going on something I go straight to the source code via a fancy fuzzy grep system to find the function definition. When things go wrong the stack trace is far more useful for finding where things are being done.

This should probably be overhauled to be consistent, but before we do that I think we should decide who and what it is for, when and where it shows, and from there how it should function. Then we should overhaul the built in functions and packages to actually meet that need.

ctrlcctrlv commented 2 years ago

I didn't even know we had an inline help system. I usually just ripgrep inside /usr/share/sile :upside_down_face:

sile-typesetter / sile

Command help location is unreliable #1195