Re: master c19dd8e9d6c 2/2: Add more documentation for TTY child frames

Re: master c19dd8e9d6c 2/2: Add more documentation for TTY child frames

[Stefan Kangas]

Robert Pluim <rpluim@gmail.com> writes:

> branch: master
> commit c19dd8e9d6c54080426623129a824e5bb2fcf7be
> Author: Robert Pluim <rpluim@gmail.com>
> Commit: Robert Pluim <rpluim@gmail.com>
>
>     Add more documentation for TTY child frames
>
>     * doc/lispref/frames.texi (Child Frames): Document that TTY
>     child frames are now supported.
>     * etc/NEWS: Document another limitation of TTY child frames.
> ---
>  doc/lispref/frames.texi | 4 ++--
>  etc/NEWS                | 7 +++++--
>  2 files changed, 7 insertions(+), 4 deletions(-)
>
> diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
> index bf4d5c05f3a..cc7d3f79a7f 100644
> --- a/doc/lispref/frames.texi
> +++ b/doc/lispref/frames.texi
> @@ -3393,8 +3393,8 @@ of its sibling child frames.
>
>    By design, operations to make or modify child frames are implemented
>  with the help of frame parameters (@pxref{Frame Parameters}) without any
> -specialized functions or customizable variables.  Note that child frames
> -are meaningful on graphical terminals only.
> +specialized functions or customizable variables.  Child frames
> +are meaningful on graphical and text terminals.

Thanks, this is an improvement.  Two comments:
1. s/meaningful/supported/  ?
2. Should we explain the limitations of child frames on text terminals
   here as well?

>    To create a new child frame or to convert a normal frame into a child
>  frame, set that frame's @code{parent-frame} parameter (@pxref{Frame
> diff --git a/etc/NEWS b/etc/NEWS
> index 7e5a73818ff..9a7b320acdb 100644
> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -47,8 +47,11 @@ enabled, you can disable mouse tracking by putting '(xterm-mouse-mode
>  ** Child frames are now supported on TTY frames.
>  This supports use-cases like Posframe, Corfu, and child frames acting
>  like tooltips.  Other use-cases of child frames are not supported yet.
> -In particular, trying to create minibuffer-only child frames on a TTY
> -frame will signal an error.
> +In particular:
> +
> +- trying to create minibuffer-only child frames on a TTY frame will
> +  signal an error.
> +- a TTY child frame cannot be converted to a root frame or vice-versa.
>
>  To enable tooltips on TTY frames, call 'tty-tip-mode'.

I note that we use the terminology "TTY frame" in NEWS, and "text
terminal" in the manual above.  In other places, we talk about "text
frames".

Which terminology do we prefer, and does it help avoid any confusion if
we are consistent?

Re: master c19dd8e9d6c 2/2: Add more documentation for TTY child frames

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Thu, 19 Dec 2024 12:23:52 -0500
> 
> >  To enable tooltips on TTY frames, call 'tty-tip-mode'.
> 
> I note that we use the terminology "TTY frame" in NEWS, and "text
> terminal" in the manual above.  In other places, we talk about "text
> frames".
> 
> Which terminology do we prefer, and does it help avoid any confusion if
> we are consistent?

We use both "text-only frames" and "TTY frames".

Re: master c19dd8e9d6c 2/2: Add more documentation for TTY child frames

[Robert Pluim]

>>>>> On Thu, 19 Dec 2024 12:23:52 -0500, Stefan Kangas <stefankangas@gmail.com> said:
    Stefan> Thanks, this is an improvement.  Two comments:
    Stefan> 1. s/meaningful/supported/  ?

I kept the original terminology. 'Supported' sounds like inviting bug
reports when things donʼt work the same between GUI and TTY.

    Stefan> 2. Should we explain the limitations of child frames on text terminals
    Stefan>    here as well?

Elsethread Eli preferred to keep the limitations in NEWS for now.

Robert
--