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

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

[Günther Noack]

Hi!

TIOCLINUX's TIOCL_SETSEL sub-code has another layer of sub-operations,
called "selection modes" (even though not all of them actually deal
with the mouse selection).

Going forward, the CAP_SYS_ADMIN requirement will be different for
some of these selection modes, which prompted me to at least list the
different selection modes with a short description.  I am leaving
CAP_SYS_ADMIN documentation as it is for now and will send another
patch once these semantics are finalized [1] [2].

Thanks,
–Günther

[1] <https://lore.kernel.org/all/20250221.0a947528d8f3@gnoack.org/>
[2] <https://lore.kernel.org/all/20250223205449.7432-2-gnoack3000@gmail.com/>

History:

V2:
 * Split into a "restructuring" and a "new documentation" commit
 * Use non-breaking space \~
 * Put URIs in <>
 * Added a helpful link to console_codes(4) regarding mouse reporting

V3:
 * Corrections and clarifications for various selection modes
   as suggested by Jared Finder. (Thanks!)

Günther Noack (2):
  TIOCLINUX.2const: Restructure documentation for TIOCL_SETSEL selection
    modes
  TIOCLINUX.2const: Document missing TIOCL_SETSEL selection modes

 man/man2const/TIOCLINUX.2const | 59 +++++++++++++++++++++++++++++++---
 1 file changed, 54 insertions(+), 5 deletions(-)

Range-diff against v2:
1:  5eb2a603e ! 1:  d07edb528 TIOCLINUX.2const: Restructure documentation for TIOCL_SETSEL selection modes
    @@ Commit message
     
         * Indent the documented selection modes into tagged paragraphs.
         * Document constants from the header file (tiocl.h) instead of numbers.
    +    * Clarify expansion semantics as suggested by Jared Finder.
     
         Signed-off-by: Günther Noack <gnoack3000@gmail.com>
     
    @@ man/man2const/TIOCLINUX.2const: are the ending
     +and saved in a kernel buffer.
     +.TP
     +.B TIOCL_SELWORD
    -+Select word-by-word.
    ++Select word-by-word,
    ++expanding the selection outwards to align with word boundaries.
     +The indicated screen characters are highlighted
     +and saved in a kernel buffer.
     +.TP
     +.B TIOCL_SELLINE
    -+Select line-by-line.
    ++Select line-by-line,
    ++expanding the selection outwards to select full lines.
     +The indicated screen characters are highlighted
     +and saved in a kernel buffer.
     +.RE
2:  2f39d5cf9 ! 2:  59f217fb0 TIOCLINUX.2const: Document missing TIOCL_SETSEL selection modes
    @@ Commit message
         mode" is slightly misleading as not all of them actually manipulate
         the kernel's mouse selection buffer.
     
    +    Includes clarified semantics pointed out by Jared Finder.
    +
         Cc: Jared Finder <jared@finder.org>
         Cc: Hanno Böck <hanno@hboeck.de>
         Cc: Jann Horn <jannh@google.com>
    @@ Commit message
         Signed-off-by: Günther Noack <gnoack3000@gmail.com>
     
      ## man/man2const/TIOCLINUX.2const ##
    -@@ man/man2const/TIOCLINUX.2const: and saved in a kernel buffer.
    - Select line-by-line.
    +@@ man/man2const/TIOCLINUX.2const: Select line-by-line,
    + expanding the selection outwards to select full lines.
      The indicated screen characters are highlighted
      and saved in a kernel buffer.
     +.TP
     +.B TIOCL_SELPOINTER
     +Show the pointer at position
    -+.RI ( xe ,\~ ye ).
    ++.RI ( xs ,\~ ys )
    ++or
    ++.RI ( xe ,\~ ye ),
    ++whichever is greater.
     +.TP
     +.B TIOCL_SELCLEAR
     +Remove the current selection highlight, if any,
     +from the console holding the selection.
    ++.IP
    ++This does not affect the stored selected text.
     +.TP
     +.B TIOCL_SELMOUSEREPORT
     +Make the terminal report
-- 
2.48.1

[PATCH man v3 1/2] TIOCLINUX.2const: Restructure documentation for TIOCL_SETSEL selection modes

[Günther Noack]

* Indent the documented selection modes into tagged paragraphs.
* Document constants from the header file (tiocl.h) instead of numbers.
* Clarify expansion semantics as suggested by Jared Finder.

Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man/man2const/TIOCLINUX.2const | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/man/man2const/TIOCLINUX.2const b/man/man2const/TIOCLINUX.2const
index c0acdd0ea..f2c8d0720 100644
--- a/man/man2const/TIOCLINUX.2const
+++ b/man/man2const/TIOCLINUX.2const
@@ -65,11 +65,26 @@ are the ending
 column and row.
 (Upper left corner is row=column=1.)
 .I sel_mode
-is 0 for character-by-character selection,
-1 for word-by-word selection,
-or 2 for line-by-line selection.
-The indicated screen characters are highlighted and saved
-in a kernel buffer.
+may be one of the following operations:
+.RS
+.TP
+.B TIOCL_SELCHAR
+Select character-by-character.
+The indicated screen characters are highlighted
+and saved in a kernel buffer.
+.TP
+.B TIOCL_SELWORD
+Select word-by-word,
+expanding the selection outwards to align with word boundaries.
+The indicated screen characters are highlighted
+and saved in a kernel buffer.
+.TP
+.B TIOCL_SELLINE
+Select line-by-line,
+expanding the selection outwards to select full lines.
+The indicated screen characters are highlighted
+and saved in a kernel buffer.
+.RE
 .IP
 Since Linux 6.7, using this subcode requires the
 .B CAP_SYS_ADMIN
-- 
2.48.1

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

[Günther Noack]

Documents the following TIOCL_SETSEL sub-operations:

* TIOCL_SELPOINTER
* TIOCL_SELCLEAR
* TIOCL_SELMOUSEREPORT

These previously undocumented selection modes for the Linux console
are implemented in drivers/tty/vt/selection.c.  The name "selection
mode" is slightly misleading as not all of them actually manipulate
the kernel's mouse selection buffer.

Includes clarified semantics pointed out by Jared Finder.

Cc: Jared Finder <jared@finder.org>
Cc: Hanno Böck <hanno@hboeck.de>
Cc: Jann Horn <jannh@google.com>
Cc: Jiri Slaby <jirislaby@kernel.org>
Cc: jwilk@jwilk.net
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man/man2const/TIOCLINUX.2const | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/man/man2const/TIOCLINUX.2const b/man/man2const/TIOCLINUX.2const
index f2c8d0720..f1021ce99 100644
--- a/man/man2const/TIOCLINUX.2const
+++ b/man/man2const/TIOCLINUX.2const
@@ -84,6 +84,40 @@ Select line-by-line,
 expanding the selection outwards to select full lines.
 The indicated screen characters are highlighted
 and saved in a kernel buffer.
+.TP
+.B TIOCL_SELPOINTER
+Show the pointer at position
+.RI ( xs ,\~ ys )
+or
+.RI ( xe ,\~ ye ),
+whichever is greater.
+.TP
+.B TIOCL_SELCLEAR
+Remove the current selection highlight, if any,
+from the console holding the selection.
+.IP
+This does not affect the stored selected text.
+.TP
+.B TIOCL_SELMOUSEREPORT
+Make the terminal report
+.RI ( xs ,\~ ys )
+as the current mouse location
+using the
+.BR xterm (1)
+mouse tracking protocol
+(see
+.BR console_codes (4)).
+The lower 4 bits of
+.I sel_mode
+.RB ( TIOCL_SELBUTTONMASK )
+indicate the desired button press and
+modifier key information for the mouse event.
+.\" <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Normal-tracking-mode>
+.IP
+If mouse reporting is not enabled for the terminal,
+this operation yields an
+.B EINVAL
+error.
 .RE
 .IP
 Since Linux 6.7, using this subcode requires the
-- 
2.48.1

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

[Jared Finder]

On 2025-03-02 11:43, Günther Noack wrote:
> Documents the following TIOCL_SETSEL sub-operations:
> 
> * TIOCL_SELPOINTER
> * TIOCL_SELCLEAR
> * TIOCL_SELMOUSEREPORT
> 
> These previously undocumented selection modes for the Linux console
> are implemented in drivers/tty/vt/selection.c.  The name "selection
> mode" is slightly misleading as not all of them actually manipulate
> the kernel's mouse selection buffer.
> 
> Includes clarified semantics pointed out by Jared Finder.
> 
> Cc: Jared Finder <jared@finder.org>
> Cc: Hanno Böck <hanno@hboeck.de>
> Cc: Jann Horn <jannh@google.com>
> Cc: Jiri Slaby <jirislaby@kernel.org>
> Cc: jwilk@jwilk.net
> Signed-off-by: Günther Noack <gnoack3000@gmail.com>
> ---
>  man/man2const/TIOCLINUX.2const | 34 ++++++++++++++++++++++++++++++++++
>  1 file changed, 34 insertions(+)
> 
> diff --git a/man/man2const/TIOCLINUX.2const 
> b/man/man2const/TIOCLINUX.2const
> index f2c8d0720..f1021ce99 100644
> --- a/man/man2const/TIOCLINUX.2const
> +++ b/man/man2const/TIOCLINUX.2const
> @@ -84,6 +84,40 @@ Select line-by-line,
>  expanding the selection outwards to select full lines.
>  The indicated screen characters are highlighted
>  and saved in a kernel buffer.
> +.TP
> +.B TIOCL_SELPOINTER
> +Show the pointer at position
> +.RI ( xs ,\~ ys )
> +or
> +.RI ( xe ,\~ ye ),
> +whichever is greater.
> +.TP
> +.B TIOCL_SELCLEAR
> +Remove the current selection highlight, if any,
> +from the console holding the selection.
> +.IP
> +This does not affect the stored selected text.
> +.TP
> +.B TIOCL_SELMOUSEREPORT
> +Make the terminal report
> +.RI ( xs ,\~ ys )
> +as the current mouse location
> +using the
> +.BR xterm (1)
> +mouse tracking protocol
> +(see
> +.BR console_codes (4)).
> +The lower 4 bits of
> +.I sel_mode
> +.RB ( TIOCL_SELBUTTONMASK )
> +indicate the desired button press and
> +modifier key information for the mouse event.
> +.\" 
> <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Normal-tracking-mode>
> +.IP
> +If mouse reporting is not enabled for the terminal,
> +this operation yields an
> +.B EINVAL
> +error.
>  .RE
>  .IP
>  Since Linux 6.7, using this subcode requires the

No additional comments from me, this looks good.

   -- MJF

Re: [PATCH man v3 1/2] TIOCLINUX.2const: Restructure documentation for TIOCL_SETSEL selection modes

[Jared Finder]

On 2025-03-02 11:43, Günther Noack wrote:
> * Indent the documented selection modes into tagged paragraphs.
> * Document constants from the header file (tiocl.h) instead of numbers.
> * Clarify expansion semantics as suggested by Jared Finder.
> 
> Signed-off-by: Günther Noack <gnoack3000@gmail.com>
> ---
>  man/man2const/TIOCLINUX.2const | 25 ++++++++++++++++++++-----
>  1 file changed, 20 insertions(+), 5 deletions(-)
> 
> diff --git a/man/man2const/TIOCLINUX.2const 
> b/man/man2const/TIOCLINUX.2const
> index c0acdd0ea..f2c8d0720 100644
> --- a/man/man2const/TIOCLINUX.2const
> +++ b/man/man2const/TIOCLINUX.2const
> @@ -65,11 +65,26 @@ are the ending
>  column and row.
>  (Upper left corner is row=column=1.)
>  .I sel_mode
> -is 0 for character-by-character selection,
> -1 for word-by-word selection,
> -or 2 for line-by-line selection.
> -The indicated screen characters are highlighted and saved
> -in a kernel buffer.
> +may be one of the following operations:
> +.RS
> +.TP
> +.B TIOCL_SELCHAR
> +Select character-by-character.
> +The indicated screen characters are highlighted
> +and saved in a kernel buffer.
> +.TP
> +.B TIOCL_SELWORD
> +Select word-by-word,
> +expanding the selection outwards to align with word boundaries.
> +The indicated screen characters are highlighted
> +and saved in a kernel buffer.
> +.TP
> +.B TIOCL_SELLINE
> +Select line-by-line,
> +expanding the selection outwards to select full lines.
> +The indicated screen characters are highlighted
> +and saved in a kernel buffer.
> +.RE
>  .IP
>  Since Linux 6.7, using this subcode requires the
>  .B CAP_SYS_ADMIN

No additional comments from me, this looks good.

   -- MJF

Re: [PATCH man v3 1/2] TIOCLINUX.2const: Restructure documentation for TIOCL_SETSEL selection modes

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 285 bytes --]

Hi Jared,

On Sun, Mar 02, 2025 at 02:50:09PM -0800, Jared Finder wrote:
> 
> No additional comments from me, this looks good.

Do you want to send an explicit Acked-by, or Reviewed-by?


Have a lovely day!
Alex

> 
>   -- MJF

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1099 bytes --]

Hi Günther,

On Sun, Mar 02, 2025 at 08:43:31PM +0100, Günther Noack wrote:
>     -@@ man/man2const/TIOCLINUX.2const: and saved in a kernel buffer.
>     - Select line-by-line.
>     +@@ man/man2const/TIOCLINUX.2const: Select line-by-line,
>     + expanding the selection outwards to select full lines.
>       The indicated screen characters are highlighted
>       and saved in a kernel buffer.
>      +.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?


Have a lovely day!
Alex

>      +.TP
>      +.B TIOCL_SELCLEAR
>      +Remove the current selection highlight, if any,
>      +from the console holding the selection.
>     ++.IP
>     ++This does not affect the stored selected text.
>      +.TP
>      +.B TIOCL_SELMOUSEREPORT
>      +Make the terminal report
> -- 
> 2.48.1
> 

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 914 bytes --]

[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.

The problem with the Linux kernel's terminal driver's lack of developer
attention over the years is obviously a result of it presenting
insufficient features of interest to the linear algebraist.

;-)

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1248 bytes --]

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?


Have a lovely night!
Alex

> 
> The problem with the Linux kernel's terminal driver's lack of developer
> attention over the years is obviously a result of it presenting
> insufficient features of interest to the linear algebraist.
> 
> ;-)
> 
> Regards,
> Branden



-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Jared Finder]

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".

   -- MJF

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1528 bytes --]

Hi Jared,

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?

> 
>   -- MJF


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Günther Noack]

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1751 bytes --]

Hi Günther!

On Sun, Mar 30, 2025 at 12:58:07PM +0200, Günther Noack wrote:
> 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?

Yep, that sounds much better.  Thanks!


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]