<commit_before>\chapter{Pane names}
\label{chap-spec-issue-pane-names}

There are several places in the specification where \emph{pane names}
are mentioned.

\section{Pane initialization and pane properties}
\label{sec-spec-issue-pane-name-pane-initialization-and-pane-properties}

The first place is in sections 29.2.1 (Pane Initialization Options).
In this section, we learn that the keyword argument \texttt{:name} can
be used as an initialization option to the function \texttt{make-pane}
and to the generic function \texttt{make-pane-1}, and that the default
value of this option is \texttt{nil}.  There is no indication
regarding the \emph{type} that the value of this option can take, but
all the examples used in the specification use symbols for this name.
This section also mentions that the \texttt{:name} initialization
option must be accepted by all pane classes.

The second place where \emph{pane names} are mentioned is in section
29.2.2 (Pane Properties).  In this section, we learn that the generic
function named \texttt{pane-name} returns the name of the pane.  The
is no corresponding \texttt{setf} function, indicating that the name
of the pane is immutable.

In other parts of the specification, there are hints that indicate
that panes may be unnamed.  Presumably, when \texttt{nil} is the value
of the initialization option, this indicates that the pane is unnamed,
but this fact is nowhere explicitly mentioned in the specification.

\section{Application frame functions}

The third place where \emph{pane names} are mentioned is in section
28.3 (Application Frame Functions).  There ares several occurrences of
pane names in this section

\subsection{\texttt{frame-standard-output}}

The description of the generic function \texttt{frame-standard-output}
says that the default method returns the first named pane of type
\texttt{application-pane} that is visible in the current layout, and
that if there is no such pane, then it returns the first pane of type
\texttt{interactor-pane} that is exposed in the current layout.

First of all, the description of this function does not mention what
is returned if there is no pane that fits this description.

More importantly, one may wonder why the candidate application pane
has to be named.  As we mentioned in
\refSec{sec-spec-issue-pane-name-pane-initialization-and-pane-properties},
presumably a pane is considered unnamed when its name was initialized
to \texttt{nil}.  According to the specification, an unnamed
application pane does not qualify, and if no named application pane
fitting the description can be found, then instead an interactor pane
is chosen.  According to the specification, that interactor pane does
not have to be named, however.

\subsection{\texttt{frame-standard-input}}

The description of the generic function \texttt{frame-standard-input}
says that the default method returns the first named pane of type
\texttt{interactor-pane} that is visible in the current layout, and
that if there is no such pane, then it returns the value returned by a
call to \texttt{frame-standard-output}.

As a consequence of this rule, it appears that it is preferable to
have a named pane than to have a pane of type
\texttt{interactor-pane}.

\subsection{\texttt{frame-panes}}

According to the specification, this generic function return the pane
that is the top-level pane in the current layout of the named panes of
the frame given as an argument.  It is hard to understand what is
meant by the restriction regarding the names here.  Presumably, it is
possible for some children of the top-level pane to be unnamed.

\subsection{\texttt{frame-current-panes}}

According to the specification, this generic function returns a list
of the named panes in the current layout of the frame given as an
argument.  And if there are no named panes, then the specification
says that only the single, top-level pane is returned.

It is not clear whether in the second case, a \emph{list} containing
that single pane is returned, or whether that pane is returned as an
atom.

\subsection{\texttt{get-frame-pane}}

According to the specification, this generic function returns the
named CLIM stream pane with the name given as an argument.  Again, no
indication is given as to the nature of the name, nor what equality
function might be used to determine whether the right name has been
found.  And, no indication is given as to what happens if there is no
pane with the name given.

\subsection{\texttt{find-pane-named}}

According to the specification, this generic function returns the
pane with the name given as argument.  The difference between this
function and the function \texttt{get-frame-pane} is that this
function can return a pane of any type, and not just a CLIM stream
pane.  Otherwise, the same omissions apply.

\subsection{\texttt{redisplay-frame-pane}}

This generic function is called in order to redisplay a particular
pane of a frame.  The \textit{pane} argument can be a pane object or
the name of a pane.<commit_msg>New section describing pane names in DEFINE-APPLICATION-FRAME.<commit_after>\chapter{Pane names}
\label{chap-spec-issue-pane-names}

There are several places in the specification where \emph{pane names}
are mentioned.

\section{Pane initialization and pane properties}
\label{sec-spec-issue-pane-name-pane-initialization-and-pane-properties}

The first place is in sections 29.2.1 (Pane Initialization Options).
In this section, we learn that the keyword argument \texttt{:name} can
be used as an initialization option to the function \texttt{make-pane}
and to the generic function \texttt{make-pane-1}, and that the default
value of this option is \texttt{nil}.  There is no indication
regarding the \emph{type} that the value of this option can take, but
all the examples used in the specification use symbols for this name.
This section also mentions that the \texttt{:name} initialization
option must be accepted by all pane classes.

The second place where \emph{pane names} are mentioned is in section
29.2.2 (Pane Properties).  In this section, we learn that the generic
function named \texttt{pane-name} returns the name of the pane.  The
is no corresponding \texttt{setf} function, indicating that the name
of the pane is immutable.

In other parts of the specification, there are hints that indicate
that panes may be unnamed.  Presumably, when \texttt{nil} is the value
of the initialization option, this indicates that the pane is unnamed,
but this fact is nowhere explicitly mentioned in the specification.

\section{Application frame functions}

The third place where \emph{pane names} are mentioned is in section
28.3 (Application Frame Functions).  There ares several occurrences of
pane names in this section

\subsection{\texttt{frame-standard-output}}

The description of the generic function \texttt{frame-standard-output}
says that the default method returns the first named pane of type
\texttt{application-pane} that is visible in the current layout, and
that if there is no such pane, then it returns the first pane of type
\texttt{interactor-pane} that is exposed in the current layout.

First of all, the description of this function does not mention what
is returned if there is no pane that fits this description.

More importantly, one may wonder why the candidate application pane
has to be named.  As we mentioned in
\refSec{sec-spec-issue-pane-name-pane-initialization-and-pane-properties},
presumably a pane is considered unnamed when its name was initialized
to \texttt{nil}.  According to the specification, an unnamed
application pane does not qualify, and if no named application pane
fitting the description can be found, then instead an interactor pane
is chosen.  According to the specification, that interactor pane does
not have to be named, however.

\subsection{\texttt{frame-standard-input}}

The description of the generic function \texttt{frame-standard-input}
says that the default method returns the first named pane of type
\texttt{interactor-pane} that is visible in the current layout, and
that if there is no such pane, then it returns the value returned by a
call to \texttt{frame-standard-output}.

As a consequence of this rule, it appears that it is preferable to
have a named pane than to have a pane of type
\texttt{interactor-pane}.

\subsection{\texttt{frame-panes}}

According to the specification, this generic function return the pane
that is the top-level pane in the current layout of the named panes of
the frame given as an argument.  It is hard to understand what is
meant by the restriction regarding the names here.  Presumably, it is
possible for some children of the top-level pane to be unnamed.

\subsection{\texttt{frame-current-panes}}

According to the specification, this generic function returns a list
of the named panes in the current layout of the frame given as an
argument.  And if there are no named panes, then the specification
says that only the single, top-level pane is returned.

It is not clear whether in the second case, a \emph{list} containing
that single pane is returned, or whether that pane is returned as an
atom.

\subsection{\texttt{get-frame-pane}}

According to the specification, this generic function returns the
named CLIM stream pane with the name given as an argument.  Again, no
indication is given as to the nature of the name, nor what equality
function might be used to determine whether the right name has been
found.  And, no indication is given as to what happens if there is no
pane with the name given.

\subsection{\texttt{find-pane-named}}

According to the specification, this generic function returns the
pane with the name given as argument.  The difference between this
function and the function \texttt{get-frame-pane} is that this
function can return a pane of any type, and not just a CLIM stream
pane.  Otherwise, the same omissions apply.

\subsection{\texttt{redisplay-frame-pane}}

This generic function is called in order to redisplay a particular
pane of a frame.  The \textit{pane} argument can be a pane object or
the name of a pane.

\section{Specifying panes of an application frame}

The fourth place where \emph{pane names} are mentioned is in section
28.2.1 (Specifying the Panes of a Frame).  The \texttt{:panes} option
of the frame-defining macro \texttt{define-application-frame} take a
list of entries, where each entry specifies how some pane is to be
created.  Each entry is of the very general form
\texttt{(}\textit{name} \texttt{.}  \textit{body}\texttt{)}.  The
description of the syntax of the \textit{body} can be a bit confusing
because of the \emph{consing dot} between the \textit{name} and the
\textit{body}, so we will instead describe the forms that an entire
entry can take on.

When the entry has the syntax \texttt{(}\textit{name}
\textit{compound-form}\texttt{)}, then \textit{compound-form} is
simply a form that will be evaluated in order to return some pane.
Presumably, the \textit{name} then becomes the name of the pane
returned by the evaluation of the form.  However, since
\textit{compound-form} can consist of some arbitrary code, the only
way \textit{name} can become the name of the resulting pane is to use
either some unspecified way of assigning a (new) name to the page, or
to use \texttt{reinitialize-instance}, passing it the \texttt{:name}
initialization option.  At the time of this writing, McCLIM uses the
unspecified way of calling \texttt{(setf slot-value)} using the name
of the slot holding the pane name.

If the entry does not have the syntax described in the previous
paragraph, it must have the syntax \texttt{(}\textit{name}
\textit{pane-type} \textit{pane-option...}\texttt{)}, where
\textit{pane-type} is a symbol that indicates the type of the pane to
be created.  For gadgets, the \textit{pane-type} is just the class
name of the abstract gadget type, such as \texttt{slider} or
\texttt{push-button}.  For CLIM stream panes, an abbreviation in the
form of a \commonlisp{} keyword symbol is possible.  Naming the pane
in this case is easier, since it suffices for CLIM to add the pair
\texttt{:name} \textit{name} to the front of the list of pane
options.

While the description above does not seem to imply any particular
difficulties, things are not as simple as they might seem.  The
problem stems from a bunch of small phrases in section 29.4 (CLIM
Stream Panes).  Specifically, in section 29.4.2 (CLIM Stream Pane
Classes), each specific pane class mentions default values for pane
initialization options, and in particular for the option
\texttt{:scroll-bars}.  As it happens, \texttt{:scroll-bars} is not
one of the possible options mentioned in section 29.4.1 (CLIM Stream
Pane Options).  Let us analyze a few possible scenarios:

\begin{enumerate}
\item The \texttt{:scroll-bars} option is not a possible option for
  CLIM stream panes.  Either it was listed by mistake (not likely), or
  it was an option at some point and was later removed from section
  29.4.1 while it lingered in the description of the specific panes.
\item The options listen in section 29.4.2, and specifically the
  \texttt{:scroll-bars} option is not an option accepted when an
  instance of a pane class is created, but only as an option supplied
  to the function \texttt{make-clim-stream-pane}.  In this scenario,
  when this function is called, it does not pass the
  \texttt{:scroll-bars} option on to the pane initialization.
  Instead, it wraps the CLIM stream pane that it creates in a
  \texttt{scroller-pane} with the scroll bars indicated, and if the
  option \texttt{:scroll-bars} is not given in the call to
  \texttt{make-clim-stream-pane}, it is the default in section 29.4.2
  that applies, depending on the sub-type of the pane to be created.
\end{enumerate}

\subsection{CLIM stream panes do not accept \texttt{:scroll-bars}}

Scenario number $1$ is likely.  In fact, in every example of the use
of the \texttt{:panes} option of \texttt{define-application-frame} in
the CLIM II specification, there is not a single example of the use of
the option \texttt{:scroll-bars}.  Instead, scrolling is achieved
by the use of the \texttt{scrolling} macro in the \texttt{:layouts}
option of \texttt{define-application-frame}.

In fact, since scrolling is always achieved by the use of a scroller
pane, if it were possible to supply a \texttt{:scroll-bars} option in
the \texttt{:panes} option of \texttt{define-application-frame} for
the creation of a CLIM stream pane, then the resulting pane would not
be a CLIM stream pane, but some layout pane containing a scroller
pane, scroll-bar panes, and the application pane.  And then, to which
of these panes would the \textit{name} be attached?

Even though the specification does not contain any example of using
the \texttt{:scroll-bars} option in the \texttt{:panes} option of
\texttt{define-application-frame}, unfortunately the Genera CLIM user
manual does contain such an example (for the 15-puzzle).  The
existence of this example is unfortunate, because without it, scenario
is not only very likely; we could declare it so and eliminate the
\texttt{:scroll-bars} option from the CLIM stream pane classes.

\subsection{The \texttt{:scroll-bars} option is for \texttt{make-clim-stream-pane}}

Scenario number $2$ is unlikely.  The reason is that the function
\texttt{make-clim-stream-pane} lists its own defaults for the
\texttt{:scroll-bars} option.  If scenario number $2$ were correct,
the description of this function would instead say that the default
for the option depends on the type of the pane to be created.
{'fraction_non_alphanumeric': 0.06006545594558172, 'fraction_numerical': 0.003593659757427966, 'mean_word_length': 4.466152227288671, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3398954', 'n_tokens_mistral': 4237, 'n_tokens_neox': 4066, 'n_words': 2270}