Re: A short defense of shorthands.el (but CL packages are still better)

["João Távora" <joaotavora@gmail.com>]

Richard Stallman <rms@gnu.org> writes:

> I've never used ElDoc and I don't know what it does.

ElDoc is Emacs's built-in at-point documentation system.  It displays
the docstring of the symbol under point in the echo are.  It is active
by default in Elisp files, and nothing has to be done by the user to
benefit from it, so you've probably used it unknowingly.

If x.el's contents were:

   (defun x-foo (point)
      "Conjure xenomorph foos."
      (interactive "d")
      (message "42 %s" point))
   (provide 'x)

   ;; x.el ends here
   ;; Local Variables:
   ;; read-symbol-shorthands: (("x-" . "xenomorph-"))
   ;; End:


You would see, in the Emacs echo area line, the indication

  xenomorph-foo: (POINT)

every time point is over a reference to the function

> Maybe you're right about C-h f, but you have not specified the
> scenario fully.  What does the user actually type, to invoke it?

Type this:

   C-h f x e n o TAB RET

This will most likely lead to a *Help* buffer displaying xenomorph-foo's
docstring.

But here's a much better example.  Even without any clients of x.el the
way you invoke the interactive function defined above is

   M-x xenomorph-foo RET

_not_

   M-x x-foo

And if the function ever signals an error, and you have the debugger
activated, then this is what shows up in the Backtrace:

   Debugger entered--Lisp error: (error "ohno")
     signal(error ("ohno"))
     error("ohno")
     xenomorph-foo(104)
     funcall-interactively(xenomorph-foo 104)

This is all consistent with the fact that the symbol actually interned
is always xenomorph-foo, not x-foo or any other context-dependent
shorthand to xenomorph-foo.

Understanding that a shorthand is just a convened-upon shortcut to a
name is key to a full proper name, with given spatial and temporal
validity, is key to operating within a namespacing system.

Curiously, most people have no problem grasping this concept when
operating namespacing systems of non-programming realities: it's well
understood that in this conversation the string "Richard" refers to you.
"RMS", a shorter string, also refers to you.  But if Richard Wagner were
to join the conversation, the first string would become ambiguous and we
could decide to replace it with something else.  We could use the latter
"RMS" shorthand for you and "WRW" for the famous composer.  But if this
were a discussion on electrical engineering, then also the shorthand
"RMS" would become ambiguous as it usually means "Root-Mean-Square" in
that context.

> I think the same grep issue will occur with actual CL packages, or
> anything that mimics them.  Shorthands are neither better nor worse in
> this case.

We are absolutely in agreement here.  This "breaks grep" characteristic
is an innate characteristc of any namespacing system.

But it is not impossible to design cross-referencing systems that
understand namespaces.  There is a good amount of prior art for the CL
package system, for example.

João