TIOCLINUX.2const: Document TIOCL_SETSEL selection modes

* 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 <[email protected]>

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

man/man2const/TIOCLINUX.2const +13 -5

index c0acdd0ea..f2c8d0720 100644
@@ -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.

No additional comments from me, this looks good.

-- MJF

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 <[email protected]>

Cc Hanno Böck <[email protected]>

Cc Jann Horn <[email protected]>

Cc Jiri Slaby <[email protected]>

Cc [email protected]

Signed-off-by Günther Noack <[email protected]>

---
 man/man2const/TIOCLINUX.2const | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

man/man2const/TIOCLINUX.2const +29 -0

index f2c8d0720..f1021ce99 100644
@@ -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

-@@ 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

Signature · 1 line

2.48.1

Quoted 8 lines · Günther Noack

     +.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?

[somewhat whimsical]

Quoted 10 lines · Alejandro Colomar

Quoted 8 lines · Günther Noack

     +.TP
     +.B TIOCL_SELPOINTER
     +Show the pointer at position
    -+.RI ( xe ,\~ ye ).
    ++.RI ( xs ,\~ ys )
    ++or
    ++.RI ( xe ,\~ ye ),
    ++whichever is greater.

Quoted 3 lines

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

Hi all,

Quoted 17 lines · G. Branden Robinson

[somewhat whimsical]

Quoted 13 lines · Alejandro Colomar

Quoted 8 lines · Günther Noack

     +.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?

Quoted 4 lines

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?

Quoted 20 lines · Alejandro Colomar

Hi all,

Quoted 17 lines · G. Branden Robinson

[somewhat whimsical]

Quoted 13 lines · Alejandro Colomar

Quoted 8 lines · Günther Noack

     +.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?

Quoted 7 lines

Quoted 4 lines

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

Quoted 30 lines · Jared Finder

Quoted 20 lines · Alejandro Colomar

Hi all,

Quoted 17 lines · G. Branden Robinson

[somewhat whimsical]

Quoted 13 lines · Alejandro Colomar

Quoted 8 lines · Günther Noack

     +.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?

Quoted 7 lines

Quoted 4 lines

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.

Quoted 6 lines

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?