GNU bug report logs - #6755
24.0.50; Customize buffer is too wide. Put doc string on separate line.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 6755 in the body.
You can then email your comments to 6755 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Thu, 29 Jul 2010 09:29:24 -0700

[Message part 1 (text/plain, inline)]

emacs -Q
 
See attached screenshots.  The first is what actually exists.  The *FIXED*
screenshot shows the kind of thing you should see instead.
 
The first line of the doc string should be on a separate line.  It
should not be on the same line as the Value Menu button.  Otherwise, the buffer
text is much too wide.

Just as for *Info* *Help* and similar buffers, Emacs should make
a reasonable effort to keep the buffer text width within 70, or
at most 80, chars.
 
We go to great trouble to ensure that doc string text width is
reasonable, but Customize currently defeats that effort by simply
appending the doc string to existing text and buttons in the buffer.

This bug has consequences for any code that tries to fit the window or frame
width to the (max) width of the buffer text.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-07-19 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags -Ic:/xpm/include'
 

[bug-emacs-customize-doc-string-FIXED.png (image/png, attachment)]

[bug-emacs-customize-doc-string.png (image/png, attachment)]

Message #8 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 6755 <at> debbugs.gnu.org
Subject: Re: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Sun, 03 Jul 2011 15:17:13 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> See attached screenshots.  The first is what actually exists.  The *FIXED*
> screenshot shows the kind of thing you should see instead.
>
> The first line of the doc string should be on a separate line.  It
> should not be on the same line as the Value Menu button.  Otherwise, the buffer
> text is much too wide.

I've tried this with a few `choice' defcustoms, but they all displayed
properly.  And the one you included in the screenshots is not available
in Emacs 24, so I can't reproduce the bug.

Do you have an example that shows this behaviour for a defcustom in
Emacs 24?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #11 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 6755 <at> debbugs.gnu.org
Subject: RE: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Sun, 3 Jul 2011 07:13:16 -0700

> I've tried this with a few `choice' defcustoms, but they all displayed
> properly.  And the one you included in the screenshots is not 
> available in Emacs 24, so I can't reproduce the bug.
> 
> Do you have an example that shows this behaviour for a defcustom in
> Emacs 24?

Yes, the same example.  Here is the defcustom:

(defcustom icicle-incremental-completion-flag t
  "..."
  :type 
  '(choice
    (const 
     :tag
     "Do not update `*Completions*' incrementally"                
     nil)
    (const 
     :tag
     "Update `*Completions*' incrementally if already displayed"  
     t)
    (other 
     :tag
     "Update `*Completions*' incrementally always"                
     always))
  :group 'Icicles-Completions-Display)

But _any_ defcustom with a longish :tag in the choice will do.
The :tag string here is only 57 chars wide.
We should be able to display :tag strings up to, say, 70 chars.

You do not need to "reproduce the bug" - you can see what it is.
The :tag string should be shown on a new line, at least when its
length is greater than, say, `(- 70 current-column)', modulo
perhaps some fuzz.

Message #14 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 6755 <at> debbugs.gnu.org
Subject: Re: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Sun, 03 Jul 2011 16:51:51 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> Yes, the same example.  Here is the defcustom:
>
> (defcustom icicle-incremental-completion-flag t
>   "..."
>   :type 
>   '(choice
>     (const 
>      :tag
>      "Do not update `*Completions*' incrementally"                
>      nil)
>     (const 
>      :tag
>      "Update `*Completions*' incrementally if already displayed"  
>      t)
>     (other 
>      :tag
>      "Update `*Completions*' incrementally always"                
>      always))
>   :group 'Icicles-Completions-Display)

Thanks.

> But _any_ defcustom with a longish :tag in the choice will do.
> The :tag string here is only 57 chars wide.
> We should be able to display :tag strings up to, say, 70 chars.
>
> You do not need to "reproduce the bug" - you can see what it is.

I never fix bugs "blind" if I can help it.  I need to reproduce the bug
so that I can test that I've really fixed it after I think I've fixed
it.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #17 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 6755 <at> debbugs.gnu.org
Subject: RE: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Sun, 3 Jul 2011 08:12:05 -0700

> I never fix bugs "blind" if I can help it.  I need to 
> reproduce the bug so that I can test that I've really fixed
> it after I think I've fixed it.

You are of course 100% right in doing that.

I meant only that I thought that in this case the bug was communicated by the
screenshots and you would be able to figure out the cause and fix from that
info.

Message #20 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 6755 <at> debbugs.gnu.org
Subject: Re: bug#6755: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Sun, 03 Jul 2011 17:19:04 +0200

Lars Magne Ingebrigtsen <larsi <at> gnus.org> writes:

>> (defcustom icicle-incremental-completion-flag t
>>   "..."
>>   :type 
>>   '(choice
>>     (const 
>>      :tag
>>      "Do not update `*Completions*' incrementally"                
>>      nil)
>>     (const 
>>      :tag
>>      "Update `*Completions*' incrementally if already displayed"  
>>      t)
>>     (other 
>>      :tag
>>      "Update `*Completions*' incrementally always"                
>>      always))
>>   :group 'Icicles-Completions-Display)
>
> Thanks.

The widget code is really involved, but I think I've finally figured out
what's inserting the string in question:

(defun widget-create-child-value (parent type value)
  "Create widget of TYPE with value VALUE."
  (let ((widget (widget-copy type)))
    (widget-put widget :value (widget-apply widget :value-to-internal value))
    (widget-put widget :parent parent)
    (unless (widget-get widget :indent)
      (widget-put widget :indent (+ (or (widget-get parent :indent) 0)
				    (or (widget-get widget :extra-offset) 0)
				    (widget-get parent :offset))))
    (widget-apply widget :create)
    widget))

So now the question is how the text should be formatted.  Perhaps
folding it after inserting it is the right way?  Anybody know how?  :-)
(I mean, without breaking the widget machinery...)


-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #23 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 6755 <at> debbugs.gnu.org
Subject: Re: bug#6755: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Sun, 03 Jul 2011 17:25:23 +0200

Actually, I give up on this one.  I have no idea how the wid-* machinery
is supposed to work.

`widget-create-child-value' is called from all over the place, and calls
`(widget-apply widget :create)', and *that* function mysteriously
inserts text into the buffer.

So I have no idea how all this is supposed to fit together, so I'm
punting on this bug to somebody who understands the widget library.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #26 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 6755 <at> debbugs.gnu.org
Subject: RE: bug#6755: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Sun, 3 Jul 2011 21:48:28 -0700

> So now the question is how the text should be formatted.  Perhaps
> folding it after inserting it is the right way?  Anybody know 
> how?  :-)
> (I mean, without breaking the widget machinery...)

Not sure if this is what you are asking, but just make sure it starts on a new
line.  That would take care of this problem and similar.  IOW, start with a
newline.

Message #29 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 6755 <at> debbugs.gnu.org
Subject: Re: bug#6755: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Mon, 04 Jul 2011 14:24:17 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

>> So now the question is how the text should be formatted.  Perhaps
>> folding it after inserting it is the right way?  Anybody know 
>> how?  :-)
>> (I mean, without breaking the widget machinery...)
>
> Not sure if this is what you are asking, but just make sure it starts
> on a new line.  That would take care of this problem and similar.
> IOW, start with a newline.

Starting with a newline didn't look very nice.  Most of the option
values are short, and moving them away from the button made the
interface less understandable.

I think the right solution is to output the string where it is now, but
to fill it if it's too long.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #32 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 6755 <at> debbugs.gnu.org
Subject: RE: bug#6755: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Mon, 4 Jul 2011 09:21:12 -0700

> Starting with a newline didn't look very nice.  Most of the option
> values are short, and moving them away from the button made the
> interface less understandable.
> 
> I think the right solution is to output the string where it 
> is now, but to fill it if it's too long.

Why not just start it on a new line if it would wrap?

IOW, instead of just filling, if it would wrap then start it on a new line.

(You could also then fill it, after starting on a new line, but I doubt that
:tag string will be more than 70 chars.  Still, it wouldn't hurt to do that.)

Message #35 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 6755 <at> debbugs.gnu.org
Subject: Re: bug#6755: 24.0.50;
	Customize buffer is too wide. Put doc string on separate line.
Date: Tue, 05 Jul 2011 15:36:38 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

>> Starting with a newline didn't look very nice.  Most of the option
>> values are short, and moving them away from the button made the
>> interface less understandable.
>> 
>> I think the right solution is to output the string where it 
>> is now, but to fill it if it's too long.
>
> Why not just start it on a new line if it would wrap?

That would work, too, but not be as nice-looking, and would be as
difficult (or easy) to implement as filling it where it is.

In either case, it's beyond me.  Somebody else who understands the
widget machinery will have to handle this.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #38 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Mauro Aranda <maurooaranda <at> gmail.com>
To: 6755 <at> debbugs.gnu.org
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Mon, 16 Sep 2019 11:54:27 -0300

[Message part 1 (text/plain, inline)]

Lars Magne Ingebrigtsen <larsi <at> gnus.org> writes:

> "Drew Adams" <drew.adams <at> oracle.com> writes:
>
>>> So now the question is how the text should be formatted.  Perhaps
>>> folding it after inserting it is the right way?  Anybody know
>>> how?  :-)
>>> (I mean, without breaking the widget machinery...)
>>
>> Not sure if this is what you are asking, but just make sure it starts
>> on a new line.  That would take care of this problem and similar.
>> IOW, start with a newline.
>
> Starting with a newline didn't look very nice.  Most of the option
> values are short, and moving them away from the button made the
> interface less understandable.
>
> I think the right solution is to output the string where it is now, but
> to fill it if it's too long.

I have an idea on how to implement the solution proposed by Lars.
I think filling after inserting the :tag property of a widget would be
enough.

But I wanted to ask first, do we really want to make this behavior
unconditional in the widget library?  Or would it be better to provide
it as an option, for customize (and possibly other clients) to set it?

Best regards,
Mauro.

[Message part 2 (text/html, inline)]

Message #41 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Mauro Aranda <maurooaranda <at> gmail.com>
Cc: 6755 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Mon, 16 Sep 2019 22:10:30 +0200

Mauro Aranda <maurooaranda <at> gmail.com> writes:

> But I wanted to ask first, do we really want to make this behavior
> unconditional in the widget library?  Or would it be better to provide
> it as an option, for customize (and possibly other clients) to set it?

I think an option here would be nice, because I think this is something
the caller would want to control.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #44 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Mauro Aranda <maurooaranda <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 6755 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Tue, 17 Sep 2019 09:04:43 -0300

[Message part 1 (text/plain, inline)]

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Mauro Aranda <maurooaranda <at> gmail.com> writes:
>
>> But I wanted to ask first, do we really want to make this behavior
>> unconditional in the widget library?  Or would it be better to provide
>> it as an option, for customize (and possibly other clients) to set it?
>
> I think an option here would be nice, because I think this is something
> the caller would want to control.

I agree with you.  I've come up with the attached patch, let me know
what you think.

For a quick way to test it, I used the option window-combination-limit:

emacs -Q
M-x customize-variable window-combination-limit

Changing the values, it can be seen when the tag string is filled and
when it's not.

[Message part 2 (text/html, inline)]

[0001-Fill-tag-strings-in-customize-buffers-Bug-6755.patch (text/x-patch, attachment)]

Message #47 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Mauro Aranda <maurooaranda <at> gmail.com>
Cc: 6755 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Wed, 18 Sep 2019 15:26:20 +0200

Mauro Aranda <maurooaranda <at> gmail.com> writes:

> diff --git a/lisp/cus-edit.el b/lisp/cus-edit.el
> index 8a8bad9..0c392ff 100644
> --- a/lisp/cus-edit.el
> +++ b/lisp/cus-edit.el
> @@ -4833,6 +4833,7 @@ custom--initialize-widget-variables
>      (setq-local widget-push-button-suffix "")
>      (setq-local widget-link-prefix "")
>      (setq-local widget-link-suffix ""))
> +  (setq-local widget-fill-tag-string t)
>    (setq show-trailing-whitespace nil))

Hm...  what is the interface here?  You set this variable
buffer-locally...


[...]

> +			 (princ (widget-get widget :value) (current-buffer))))
> +                  (when widget-fill-tag-string
> +                    (save-restriction
> +                      (widen)
> +                      (fill-region opoint (point) nil t)))))

And then fill all the widgets of this type in this buffer?  But doesn't
that mean that it's impossible to have two widgets, one with filling and
one without, in the same buffer?

I'm not very familiar with the widget code, so I may well be
misunderstanding here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #50 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Mauro Aranda <maurooaranda <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 6755 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sat, 21 Sep 2019 07:53:53 -0300

[Message part 1 (text/plain, inline)]

Hello Lars,

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Mauro Aranda <maurooaranda <at> gmail.com> writes:
>
>> diff --git a/lisp/cus-edit.el b/lisp/cus-edit.el
>> index 8a8bad9..0c392ff 100644
>> --- a/lisp/cus-edit.el
>> +++ b/lisp/cus-edit.el
>> @@ -4833,6 +4833,7 @@ custom--initialize-widget-variables
>>      (setq-local widget-push-button-suffix "")
>>      (setq-local widget-link-prefix "")
>>      (setq-local widget-link-suffix ""))
>> +  (setq-local widget-fill-tag-string t)
>>    (setq show-trailing-whitespace nil))
>
> Hm...  what is the interface here?  You set this variable
> buffer-locally...
>
>
> [...]
>
>> + (princ (widget-get widget :value) (current-buffer))))
>> +                  (when widget-fill-tag-string
>> +                    (save-restriction
>> +                      (widen)
>> +                      (fill-region opoint (point) nil t)))))
>
> And then fill all the widgets of this type in this buffer?  But doesn't
> that mean that it's impossible to have two widgets, one with filling and
> one without, in the same buffer?

As it stands now, yes, all widgets in customize would get its tag
filled, unless a different :create function is provided for that
widget.

I didn't thought of the case of wanting one widget with its tag filled
and another one with its tag not filled, in a customize buffer.  I didn't
see the need in that.  When would that be a good thing?

If it makes sense, a widget could have a :fill property set to t, for
example, and in the code that calls the widget creation functions (e.g.,
widget-create), widget-fill-tag-string would be bound to t.  This goes,
of course, for all other users of the widget library.

Best regards,
Mauro.

[Message part 2 (text/html, inline)]

Message #53 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Mauro Aranda <maurooaranda <at> gmail.com>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 6755 <at> debbugs.gnu.org
Subject: RE: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sat, 21 Sep 2019 14:44:39 +0000 (UTC)

OP, here.

FWIW, this enhancement request (or bug report)
did not ask for the doc string to be filled.  It
asked for it to be moved to its own line.  Those
are not at all the same thing.

A doc string should be under the control of its
author.  It should already follow the conventions
for doc string line length.  The doc string line
length is NOT the problem.

The OP report says this:

  We go to great trouble to ensure that doc
  string text width is reasonable, but Customize
  currently defeats that effort by simply
  appending the doc string to existing text and
  buttons in the buffer.

Please respect that motivation.  Authors go to
great trouble to format doc strings.  Please do
not override that willy nilly by filling the
doc they've gone to some trouble to format.

If you want to add an _option_ to _also_ fill the
doc string, that's a different enhancement request,
not this one.

That should in any case be independent.  If a user
wants doc strings to be blindly filled systematically
that's her right, so I'm not against adding such an
option.

But that's not a fulfillment of _this_ enhancement
request (or bug fix).  What's needed for this report
is to move the doc string to its own line.  Can that
please be done, or at least considered?

And if you _also_ want to consider filling the doc
string (that should be a separate enhancement
request), please do _not_ do so systematically.  Let
users choose to do that (opt in), with a user option.

Message #56 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Mauro Aranda <maurooaranda <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 6755 <at> debbugs.gnu.org
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sat, 21 Sep 2019 14:04:00 -0300

[Message part 1 (text/plain, inline)]

Drew Adams <drew.adams <at> oracle.com> writes:

> OP, here.

Hello.

> FWIW, this enhancement request (or bug report)
> did not ask for the doc string to be filled.  It
> asked for it to be moved to its own line.  Those
> are not at all the same thing.

I see.  When I read the bug report, I thought it was just a suggestion to
fix the problem of the customize buffer getting too wide.  Perhaps I was
wrong.

> But that's not a fulfillment of _this_ enhancement
> request (or bug fix).  What's needed for this report
> is to move the doc string to its own line.  Can that
> please be done, or at least considered?

May I ask you then, what is the :format option missing for this situation?

For example, if one of the const types of the defcustom you provided
had the following format-string:
(const
 :tag
 "Update `*Completions*' incrementally if already displayed"
 :format "\n%t\n%d"
 t)

then the tag would go to its own line.  And that avoids making the
customize buffer too wide.

> And if you _also_ want to consider filling the doc
> string (that should be a separate enhancement
> request), please do _not_ do so systematically.  Let
> users choose to do that (opt in), with a user option.

I take all the points you raised about the filling option, but I think
it might be better to at least postpone that discussion.

[Message part 2 (text/html, inline)]

Message #59 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Mauro Aranda <maurooaranda <at> gmail.com>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 6755 <at> debbugs.gnu.org
Subject: RE: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sat, 21 Sep 2019 22:36:23 +0000 (UTC)

>> FWIW, this enhancement request (or bug report)
>> did not ask for the doc string to be filled.  It
>> asked for it to be moved to its own line.  Those
>> are not at all the same thing.
>
> I see.  When I read the bug report, I thought it was just a suggestion to
> fix the problem of the customize buffer getting too wide.  Perhaps I was
> wrong.

The bug report just asks that the first line of a doc
string be put on its own line, and likewise for :tag
lines.

>> But that's not a fulfillment of _this_ enhancement
>> request (or bug fix).  What's needed for this report
>> is to move the doc string to its own line.  Can that
>> please be done, or at least considered?
>
> May I ask you then, what is the :format option missing for this situation?
>
> For example, if one of the const types of the defcustom you provided
> had the following format-string:
> (const 
> :tag
> "Update `*Completions*' incrementally if already displayed"
> :format "\n%t\n%d"
> t)
>
> then the tag would go to its own line.  And that avoids making the
> customize buffer too wide.

Maybe so, but defcustom writers should not need to worry
about that.  See above.

Imagine if when you do `C-h f' the *Help* buffer stuffed
a bunch of stuff in front of the first docstring line.

That's just obstruction; it just gets in the way.  And
it's not necessary.

Customize should just assume that a docstring has the
honor of being shown starting in column 1.  And the same
for a :tag line.

>> And if you _also_ want to consider filling the doc
>> string (that should be a separate enhancement
>> request), please do _not_ do so systematically.  Let
>> users choose to do that (opt in), with a user option.
>
> I take all the points you raised about the filling option, but I think
> it might be better to at least postpone that discussion.

Filling is not part of this enhancement request (bug
report).  Please don't fill docstrings or :tag lines,
at least not for this bug.  If someone wants to consider
doing that, and open a discussion about it, please file
a separate enhancement request.

When I spoke of authors carefully "formatting" doc strings
I meant that they manually adjust the text and its line
lengths, to fit the convention.  That includes, e.g.,
taking `\\[...]', `\\<...>' and `\\{...}' into account.

Whatever an author implements as the source for a doc
string should be respected.  Likewise, for a :tag line.

If an author wants to use `:format' in this context
she can do so.  She should not be forced to do that
systematically, just to get a docstring or :tag line
to start in column 1, i.e., on its own line.

Message #62 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Mauro Aranda <maurooaranda <at> gmail.com>
Cc: 6755 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sun, 22 Sep 2019 14:30:48 +0200

Mauro Aranda <maurooaranda <at> gmail.com> writes:

> As it stands now, yes, all widgets in customize would get its tag
> filled, unless a different :create function is provided for that
> widget.
>
> I didn't thought of the case of wanting one widget with its tag filled
> and another one with its tag not filled, in a customize buffer.  I didn't
> see the need in that.  When would that be a good thing?

If we're adding a way to allow controlling whether to fill or not, then
it should be flexible.

> If it makes sense, a widget could have a :fill property set to t, for
> example, and in the code that calls the widget creation functions (e.g.,
> widget-create), widget-fill-tag-string would be bound to t.  This goes,
> of course, for all other users of the widget library.

Yes, adding a :fill property sounds better to me...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #65 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, maurooaranda <at> gmail.com, 6755 <at> debbugs.gnu.org
Subject: Re: bug#6755: 24.0.50;
 Customize buffer is too wide. Put doc string on separate line.
Date: Sun, 22 Sep 2019 17:55:56 +0300

> Date: Sat, 21 Sep 2019 22:36:23 +0000 (UTC)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 6755 <at> debbugs.gnu.org
> 
> The bug report just asks that the first line of a doc
> string be put on its own line, and likewise for :tag
> lines.

There's some kind of serious confusion in this bug report.  The text
that is displayed to the right of the "Value Menu" button is not the
doc string, it's the textual description of the current value.
Therefore, it makes no sense at all to start that text on a new line.
I also don't see how filling of any kind can make the situation better
when the textual description is too long.

Reading the discussions, I think they were mostly based on the above
misunderstanding, so I think we should either close this bug, or maybe
start discussing it anew, after forgetting everything that was said
and suggested, because none of that makes sense to me.

Message #68 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, maurooaranda <at> gmail.com, 6755 <at> debbugs.gnu.org
Subject: RE: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sun, 22 Sep 2019 09:09:52 -0700 (PDT)

> > The bug report just asks that the first line of a doc
> > string be put on its own line, and likewise for :tag
> > lines.
> 
> There's some kind of serious confusion in this bug report.  The text
> that is displayed to the right of the "Value Menu" button is not the
> doc string, it's the textual description of the current value.

Correct.  I guess there is no problem with the
doc-string display - my bad for mentioning doc
strings.

It's about :tag lines.  The screenshots and the
defcustom provided make that clear, I believe.

> Therefore, it makes no sense at all to start that text on a new line.

Why do you think that follows logically?  I don't.

This bug report / enhancement request is precisely to
put that text on its own line.  At least do so when
the text would go past the conventional limit (70 chars
or whatever) when placed after Customize constructs
(boilerplate text, buttons, etc.).

> I also don't see how filling of any kind can make the situation better
> when the textual description is too long.

This bug report does not ask for text filling, at all.
Please move consideration/discussion of filling to
a new bug report, if you're interested in that.

> Reading the discussions, I think they were mostly based on the above
> misunderstanding, 

No mention of filling is in the bug report.  That
misunderstanding apparently came out of the sky,
perhaps just based on mention of the buffer content
being too wide.

> so I think we should either close this bug, or maybe
> start discussing it anew, after forgetting everything that was said
> and suggested, because none of that makes sense to me.

It should not be closed.  And there is no reason to
forget "everything that was said".

You can certainly forget about filling, and I guess
you can forget about the doc string (my apologies for
mentioning the doc string).

The problem is :tag lines.  They should be moved to
their own line - at least when combining them with
widget artifacts makes the resulting displayed content
too wide.

It's reasonable for :tag text to be up to, say, 70
chars.  It's probably even reasonable for :tag text
to contain newlines - like a doc string.

It's not reasonable/helpful for :tag text to simply
be tacked onto the end of a line where Customize has
itself inserted lots of other stuff.

Message #71 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, maurooaranda <at> gmail.com, 6755 <at> debbugs.gnu.org
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sun, 22 Sep 2019 19:57:25 +0300

> Date: Sun, 22 Sep 2019 09:09:52 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: maurooaranda <at> gmail.com, larsi <at> gnus.org, 6755 <at> debbugs.gnu.org
> 
> It's about :tag lines.  The screenshots and the
> defcustom provided make that clear, I believe.
> 
> > Therefore, it makes no sense at all to start that text on a new line.
> 
> Why do you think that follows logically?  I don't.
> 
> This bug report / enhancement request is precisely to
> put that text on its own line.

And that's exactly what makes no sense: we would be artificially
separating the value menu button from the description of the current
value.

So if you insist on doing this, I object to this proposal.

> At least do so when the text would go past the conventional limit
> (70 chars or whatever) when placed after Customize constructs
> (boilerplate text, buttons, etc.).

No.  It is up to the Lisp programmers to make sure the text is short
enough to not cause this.  Exactly like with doc strings.

> > I also don't see how filling of any kind can make the situation better
> > when the textual description is too long.
> 
> This bug report does not ask for text filling, at all.
> Please move consideration/discussion of filling to
> a new bug report, if you're interested in that.

I only mentioned filling because that was one of the proposed
solutions.  We should NOT do any filling here.

> The problem is :tag lines.  They should be moved to
> their own line - at least when combining them with
> widget artifacts makes the resulting displayed content
> too wide.

Disagree.

Message #74 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Mauro Aranda <maurooaranda <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 6755 <at> debbugs.gnu.org,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sun, 22 Sep 2019 14:24:06 -0300

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> There's some kind of serious confusion in this bug report.  The text
> that is displayed to the right of the "Value Menu" button is not the
> doc string, it's the textual description of the current value.

Thanks for clarifying.

> Therefore, it makes no sense at all to start that text on a new line.

FWIW, I agree.

> I also don't see how filling of any kind can make the situation better
> when the textual description is too long.

OK.  FTR, I ask everyone to ignore the patch I sent, please.

[Message part 2 (text/html, inline)]

Message #77 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mauro Aranda <maurooaranda <at> gmail.com>
Cc: larsi <at> gnus.org, 6755 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sun, 22 Sep 2019 22:11:28 +0300

> From: Mauro Aranda <maurooaranda <at> gmail.com>
> Date: Sun, 22 Sep 2019 14:24:06 -0300
> Cc: Drew Adams <drew.adams <at> oracle.com>, Lars Ingebrigtsen <larsi <at> gnus.org>, 6755 <at> debbugs.gnu.org
> 
> > I also don't see how filling of any kind can make the situation better
> > when the textual description is too long.
> 
> OK.  FTR, I ask everyone to ignore the patch I sent, please.

Thanks for working on this, regardless.

Message #80 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, maurooaranda <at> gmail.com, 6755 <at> debbugs.gnu.org
Subject: RE: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Sun, 22 Sep 2019 15:56:04 -0700 (PDT)

> > It's about :tag lines.  The screenshots and the
> > defcustom provided make that clear, I believe.
> >
> > > Therefore, it makes no sense at all to start that text on a new line.
> >
> > Why do you think that follows logically?  I don't.
> >
> > This bug report / enhancement request is precisely to
> > put that text on its own line.
> 
> And that's exactly what makes no sense: 

I disagree that it makes no sense.  In fact I think it
makes a lot of sense.  Hence this enhancement request.

> we would be artificially separating the value menu
> button from the description of the current value.

Look at the screenshots.  I don't see why anyone would
find it odd, let alone "make no sense") to show the doc
for the current value just below button, on the next line.

But there's no accounting for tastes, as they say.
You have yours; I have mine.

To me it's artificial to show the :tag text to the right
of the button, especially when it is more than a few
chars long.

> So if you insist on doing this, I object to this proposal.

That's what this enhancement request is about.  Does
that count as "insistence"?

> > At least do so when the text would go past the conventional limit
> > (70 chars or whatever) when placed after Customize constructs
> > (boilerplate text, buttons, etc.).
> 
> No.  It is up to the Lisp programmers to make sure the text is short
> enough to not cause this.  Exactly like with doc strings.

Not the same at all.  Why? because Customize sticks
a variable amount of stuff before the :tag text.

1. You know where a doc string will be displayed,
   and it always starts in column 1.

2. But :tag text depends on the stuff that Customize
   adds to the buffer before it.

   In the case of the `Value Menu' button, that
   stuff includes the option (or face) name, which
   varies from option to option.

   That means that the longer the option name, the
   less room for the :tag string.  There should be
   no such relation between their lengths.  (Why
   would there be?)

   The :tag in the screenshot is 55 chars.  Given
   the option name of 34 chars, plus the colon,
   `Value Menu' button, and spaces Customize adds,
   there is only room for a :tag of 30 chars.

3. Imagine if we did something similar for `C-h v':
   Put, say, the first line of the doc string (or
   some other descriptive text, if you don't like
   that hypothetical) to the right of the var name.

   That wouldn't make much sense, would it?  Why?
   Because a long variable name would mean you'd
   have to use a short description.

   There's no reason to impose any relation between
   those lengths.  Doing so "makes no sense", to me.
 
> > The problem is :tag lines.  They should be moved to
> > their own line - at least when combining them with
> > widget artifacts makes the resulting displayed content
> > too wide.
> 
> Disagree.

Message #83 received at 6755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: maurooaranda <at> gmail.com, Drew Adams <drew.adams <at> oracle.com>,
 6755 <at> debbugs.gnu.org
Subject: Re: bug#6755: 24.0.50; Customize buffer is too wide. Put doc string
 on separate line.
Date: Mon, 23 Sep 2019 12:10:20 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> No.  It is up to the Lisp programmers to make sure the text is short
> enough to not cause this.  Exactly like with doc strings.

If you have very long variable names, it can be difficult to make the
tags short enough...  But I've grepped through the Emacs sources, and
after eyeballing :tag usage here, I'm estimating that approx. none of
the in-tree instances have this problem, so I agree with you.

And I'm closing this bug report.

Thanks for working on this, Mauro, anyway.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.