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

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

Hello Jared!

On Sun, Feb 23, 2025 at 03:13:35PM -0800, Jared Finder wrote:
> I'm not a regular kernel developer, so feel free to ignore my
> recommendations if they are not aligned with the level of documentation
> usually provided.

Thank you! No, it's absolutely appreciated.

You are right that the console IOCTLs are generally under-documented.
I do not have the time to fix that all up, but I am happy to fix it
for the pieces that I'm touching.

> On 2025-02-23 13:36, Günther Noack wrote:
> > * Indent the documented selection modes into tagged paragraphs.
> > * Document constants from the header file (tiocl.h) instead of numbers.
> > 
> > Signed-off-by: Günther Noack <gnoack3000@gmail.com>
> > ---
> >  man/man2const/TIOCLINUX.2const | 23 ++++++++++++++++++-----
> >  1 file changed, 18 insertions(+), 5 deletions(-)
> > 
> > diff --git a/man/man2const/TIOCLINUX.2const
> > b/man/man2const/TIOCLINUX.2const
> > index c0acdd0ea..5db3f6ea6 100644
> > --- a/man/man2const/TIOCLINUX.2const
> > +++ b/man/man2const/TIOCLINUX.2const
> > @@ -65,11 +65,24 @@ 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.
> 
> I would recommend also saying

This sentence is truncated, and there is no special expansion logic in
this case.  I left it as it is for now, unless there is something
better to say here.

> > +.TP
> > +.B TIOCL_SELWORD
> > +Select word-by-word.
> > +The indicated screen characters are highlighted
> > +and saved in a kernel buffer.
> 
> I would recommend also saying something like "The start is expanded backward
> and the end is expanded forwards to select entire words."

Changing it to

  Select word-by-word,
  expanding the selection outwards to align with word boundaries.

Does it sound reasonable to you?

> > +.TP
> > +.B TIOCL_SELLINE
> > +Select line-by-line.
> > +The indicated screen characters are highlighted
> > +and saved in a kernel buffer.
> > +.RE
> 
> Similarly, mention how the start / end is expanded here too.

Made it

  Select line-by-line,
  expanding the selection outwards to select full lines.

–Günther