Re: [PATCH man v3 0/2] TIOCLINUX.2const: Document TIOCL_SETSEL selection modes

["Günther Noack" <gnoack3000@gmail.com>]

Hello!

On Wed, Mar 26, 2025 at 09:58:21AM +0100, Alejandro Colomar wrote:
> On Tue, Mar 25, 2025 at 09:48:58PM -0700, Jared Finder wrote:
> > On 2025-03-22 12:37, Alejandro Colomar wrote:
> > > Hi all,
> > > 
> > > On Mon, Mar 17, 2025 at 12:43:40PM -0500, G. Branden Robinson wrote:
> > > > [somewhat whimsical]
> > > > 
> > > > At 2025-03-17T14:23:09+0100, Alejandro Colomar wrote:
> > > > > On Sun, Mar 02, 2025 at 08:43:31PM +0100, Günther Noack wrote:
> > > > > >      +.TP
> > > > > >      +.B TIOCL_SELPOINTER
> > > > > >      +Show the pointer at position
> > > > > >     -+.RI ( xe ,\~ ye ).
> > > > > >     ++.RI ( xs ,\~ ys )
> > > > > >     ++or
> > > > > >     ++.RI ( xe ,\~ ye ),
> > > > > >     ++whichever is greater.
> > > > >
> > > > > Everything else looks good to me.  But,
> > > > >
> > > > > What's "greater" when you have two dimensions?
> > > > 
> > > > Since we can model the terminal display as an inner product space,
> > > > the terminal driver can compute an orthographic projection of the
> > > > plane onto a line and from there use routine arithmetic inequality
> > > > operators.
> > > 
> > > In any case, this is going to be confusing.  Can we get some wording
> > > that is obvious to a school student?
> > 
> > How about something like "... whichever is greater.
> 
> 
> > When the positions span
> > multiple horizontal lines (ys != ye),
> 
> 
> > characters are ordered left to right,
> > top to bottom, similar to when writing English text".
> 
> And greater is a character ordered first or last?

Thanks for your input!  You are correct that saying "bigger" is
unclear.  The alternatives are entertaining in a nerdy way ;-) but I'm
not sure that being mathematically exact here helps the purpose of
this man page. ;-)

The elephant in the room is that in the big scheme of things, this API
is pretty absurd: The API draws the mouse pointer at *one* position,
but there are *two* places where users can specify the coordinates.

Noone in their right mind would actually pass two coordinates and
would try to rely on the exact ordering semantics here.  The only
reasonable thing to do is to pass the coordinate in one of the two
places and leave the other place blank (0, 0).  The only ordering that
*actually* matters to callers is that their passed coordinate is
"bigger" than (0, 0).

These API semantics look like they happened by accident rather than by
intentional planning.  If the goal is to describe how an API *should*
get used, then spending too many words on ordering semantics here
would IMHO be distracting from the real thing that callers should do,
which I think should be *to fill one of the two coordinates and leave
the other blank*. :)

So if we describe this, I would like to make it as succinct as
possible and not draw unnecessary attention to it.

To make a constructive proposal, how about this phrasing:

  Show the pointer at position (xs, ys) or (xe, ye),
  whichever is later in text flow order.

?  Does that sound reasonable?

Thanks,
–Günther