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

Previous Next

Full log

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.

Previous Next

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