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

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

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