Document that :class might be needed if :setup-children is used

It was undefined which class would be used if none was specified
explicitly and `:setup-children' is used.  Using `transient-column'
makes sense because, at least for a flat list of suffixes, that is
the default for explicitly specified suffixes too.

[1: df36bc87] accidentally changed the undefined default behavior to
use `transient-columns' instead.  This commit reverts that, but it is
still considered undefined behavior.  We now display a warning if this
is encountered, and that will eventually be turned into an error.

(Note that while not particularly useful, it is allowed to define a
group with neither explicit children nor `:setup-children' (it will
be silently omitted).  At least for now, we keep it that way.)

Closes #277.

1: 2024-02-01 df36bc8745520f4580c8bc9260d57aa53878a053
   transient--parse-group: Detect columns beginning with included group

2 files changed, 32 insertions, 12 deletions

diff --git a/docs/transient.org b/docs/transient.org
index 598910e..3b64c6e 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -1011,9 +1011,19 @@ constructor of that class.
   prefix's ~transient--layout~ property, but it is often more convenient
   to use the same form as understood by ~transient-define-prefix~,
   described below.  If you use the latter approach, you can use the
-  ~transient-parse-child~ and ~transient-parse-children~ functions to
+  ~transient-parse-suffixes~ and ~transient-parse-suffix~ functions to
   transform them from the convenient to the expected form.
 
+  If you explicitly specify children and then transform them using
+  ~:setup-chilren~, then the class of the group is determined as usual,
+  based on explicitly specified children.
+
+  If you do not explicitly specify children and thus rely solely on
+  ~:setup-children~, then you must specify the class using ~:class~.
+  For backward compatibility, if you fail to do so, ~transient-column~
+  is used and a warning is displayed.  This warning will eventually
+  be replaced with an error.
+
 - The boolean ~:pad-keys~ argument controls whether keys of all suffixes
   contained in a group are right padded, effectively aligning the
   descriptions.
@@ -1023,11 +1033,11 @@ The {{{var(ELEMENT)}}}s are either all subgroups, or all suffixes and strings.
 subgroups with commands at the same level, though in principle there
 is nothing that prevents that.)
 
-If the {{{var(ELEMENT)}}}s are not subgroups, then they can be a mixture of lists
-that specify commands and strings.  Strings are inserted verbatim into
-the buffer.  The empty string can be used to insert gaps between
-suffixes, which is particularly useful if the suffixes are outlined as
-a table.
+If the {{{var(ELEMENT)}}}s are not subgroups, then they can be a mixture of
+lists, which specify commands, and strings.  Strings are inserted
+verbatim into the buffer.  The empty string can be used to insert gaps
+between suffixes, which is particularly useful if the suffixes are
+outlined as a table.
 
 Inside group specifications, including inside contained suffix
 specifications, nothing has to be quoted and quoting anyway is
diff --git a/docs/transient.texi b/docs/transient.texi
index d90f726..e74e090 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -1200,9 +1200,19 @@ The returned children must have the same form as stored in the
 prefix's @code{transient--layout} property, but it is often more convenient
 to use the same form as understood by @code{transient-define-prefix},
 described below.  If you use the latter approach, you can use the
-@code{transient-parse-child} and @code{transient-parse-children} functions to
+@code{transient-parse-suffixes} and @code{transient-parse-suffix} functions to
 transform them from the convenient to the expected form.
 
+If you explicitly specify children and then transform them using
+@code{:setup-chilren}, then the class of the group is determined as usual,
+based on explicitly specified children.
+
+If you do not explicitly specify children and thus rely solely on
+@code{:setup-children}, then you must specify the class using @code{:class}.
+For backward compatibility, if you fail to do so, @code{transient-column}
+is used and a warning is displayed.  This warning will eventually
+be replaced with an error.
+
 @item
 The boolean @code{:pad-keys} argument controls whether keys of all suffixes
 contained in a group are right padded, effectively aligning the
@@ -1214,11 +1224,11 @@ The @var{ELEMENT}s are either all subgroups, or all suffixes and strings.
 subgroups with commands at the same level, though in principle there
 is nothing that prevents that.)
 
-If the @var{ELEMENT}s are not subgroups, then they can be a mixture of lists
-that specify commands and strings.  Strings are inserted verbatim into
-the buffer.  The empty string can be used to insert gaps between
-suffixes, which is particularly useful if the suffixes are outlined as
-a table.
+If the @var{ELEMENT}s are not subgroups, then they can be a mixture of
+lists, which specify commands, and strings.  Strings are inserted
+verbatim into the buffer.  The empty string can be used to insert gaps
+between suffixes, which is particularly useful if the suffixes are
+outlined as a table.
 
 Inside group specifications, including inside contained suffix
 specifications, nothing has to be quoted and quoting anyway is