Bart Schaefer wrote on Sat, 28 May 2022 18:43 +00:00:
> On Sat, May 28, 2022 at 3:06 AM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>> +cindex(widgets, shadowing standard)
>
> "Shadow(ing)" is not a term I'd think to search for in this context.
> Wrap, override, overload, replace, re-implement, ...?
>

Most of these terms imply particular semantics (e.g., "wrap" implies the
new definition calls the old one).  I think "shadow" is the right term
here, so how about:

+cindex(widgets, shadowing standard)
+cindex(widgets, overriding standard)
+User-defined widgets may shadow (override) standard widgets: for instance,

>> +However, each standard widget `var(foo)' is also available under the
>> +name `tt(.)var(foo)', and this name can't be rebound to a different widget.
>
> I would probably have used something like var(std) or even
> var(stdwidg) here, but that's a nit.
>

Personally I find it easier to read with "foo", but I suppose that's
a matter of taste.  I'll write it whichever way is the house style.

>> +Therefore, for forward compatibility with future versions of the shell,
>> +it is recommended that user-defined widgets should not have names
>>  starting with `tt(.)'.
>
> It's actually prohibited to name a user-defined widget the same as one
> of the reserved dot-names, so this recommendation could be more
> specific.
>

OK, can spell out the problem.  Wouldn't that make the paragraph a bit
of a wall of text, though?  Also, it would further break the flow
(example, recommendation, rationale of the recommendation, continuation
of example).  That flow was one of the things that I wasn't happy about
regarding the v1 of the patch.

+Therefore, for forward compatibility with future versions of the shell,
+it is recommended that user-defined widgets should not have names
-starting with `tt(.)'.
+starting with `tt(.)'.  (If a user-defined widget is named `tt(.)var(some-name)'
+and a future version of the shell introduces a built-in `var(some-name)' widget,
+the user-defined widget's definition will raise an error under that future
+version of the shell.)

>> +then tt(myfunc) would have been called again, effecting a bottomless
>> +recursion.
>
> Perhaps my old-fogey-ness (or USA-centrism) is showing, but I've never
> seen the word "bottomless" used in this context before, only
> "infinite" or more rarely "endless".  Another nit, as it doesn't
> really change the clarity, just mentioning because I found it curious.

Prior art:

(1995) https://github.com/freebsd/freebsd-src/commit/cd02a0b741846be432ea4646890e617c8c3b445d

(2003) https://www.freebsd.org/cgi/man.cgi?query=exit&apropos=0&sektion=3&manpath=FreeBSD+5.0-RELEASE&arch=default&format=html

It does seem to be rather rare, though.

Thanks for the review!

Daniel