bug#10600: 24.0.92; `describe-char': text properties and [Show]

bug#10600: 24.0.92; `describe-char': text properties and [Show]

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 1910 bytes --]

When there are text properties on the char, `describe-char' (hence also
`C-u C-x =') shows each of them using the button `[Show]'.
 
1. A user must click each button to see the value.  And if buffer `*Pp
Eval Output*' happens to be a special-display buffer then it is shown in
a separate frame.  
 
This might be appropriate for some values - e.g., values that are too
long to fit on a line of the standard max length for `*Help*', but it
does not make much sense for values that are not too long.  It just
means more work and annoyance for the user.
 
2. If you then do, say, `C-h f forward-char', so that `*Help*' now shows
something different, and then you click `[back]', you get the previous
`describe-char' output, but this time all of the `[Show]' fields have
been replaced by their values.
 
See the attached screenshots.
 
What you see in #2 should not be different from what you see in #1.  And
what you see in #2 is in most cases more user-friendly: most such values
can be shown completely on the same line - there is no need to force
users to futz around with `[Show]' buttons.
 
Please DTRT for users:
 
a) Show all values that can be shown on the same line, instead of
using`[Show]' buttons for them.
 
b) Show the same output initially and when `[back]' or `[forward]' is
clicked.
 
In GNU Emacs 24.0.92.1 (i386-mingw-nt5.1.2600) of 2012-01-22 on MARVIN
 Windowing system distributor `Microsoft Corp.', version 5.1.2600
 configured using `configure --with-gcc (4.6) --no-opt --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include --ldflags
 -LD:/devel/emacs/libs/gnutls-3.0.9/lib'
 

[-- Attachment #2: throw-emacs-bug-describe-char-Show-2.png --]
[-- Type: image/png, Size: 6190 bytes --]

[-- Attachment #3: throw-emacs-bug-describe-char-Show-1.png --]
[-- Type: image/png, Size: 5142 bytes --]

bug#10600: 24.0.92; `describe-char': text properties and [Show]

[Chong Yidong]

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

> When there are text properties on the char, `describe-char' (hence also
> `C-u C-x =') shows each of them using the button `[Show]'.

Please provide a precise step-by-step recipe to reproduce the problem,
starting from emacs -Q.

bug#10600: 24.0.92; `describe-char': text properties and [Show]

[Drew Adams]

> > When there are text properties on the char, `describe-char' 
> > (hence also `C-u C-x =') shows each of them using the button `[Show]'.
> 
> Please provide a precise step-by-step recipe to reproduce the problem,
> starting from emacs -Q.

I looked a bit closer.  The problem is apparently the same as for bug #10127:

The *Help* buffer being prepared has not yet been displayed, so it has no
associated window.  Yet the code calls (window-width) to determine the width of
the yet-to-be-displayed buffer.  This is obviously wrong.

The current window for that calculation does not correspond to *Help* at all.
It is wrong to assume that *Help* will be displayed in a window having the same
width as the window where the help command is invoked.  In particular, when
pop-up frames are used or *Help* is a special-display buffer then its width will
not, in general correspond to the initial window.  Another case is where windows
are split side-by-side.

It's simply misguided to base the assumed *Help* window width on the width of
any existing window.  It makes more sense to do something like this:

Use the maximum default width for *Help* _buffer text_, which is no doubt
something like 70 (less than 80, in any case).  We already go to the trouble of
wrapping help text at such a limit.  That limit should be also the basis for
determining the width of this help display.

bug#10600: 24.0.92; `describe-char': text properties and [Show]

[Juanma Barranquero]

On Fri, Jan 27, 2012 at 17:15, Drew Adams <drew.adams@oracle.com> wrote:

> The current window for that calculation does not correspond to *Help* at all.
> It is wrong to assume that *Help* will be displayed in a window having the same
> width as the window where the help command is invoked.

Yes.

> It's simply misguided to base the assumed *Help* window width on the width of
> any existing window.

I disagree. I think it makes  sense to base it on the width of the
window used to display it. In cases like this one, it should be
possible to display the (empty) buffer, then generate its output.

> We already go to the trouble of
> wrapping help text at such a limit.

By hand, you mean? Because if you define a function with a docstring
100 chars long, and do M-x describe-function my-test-func <RET>,
there's no wrap at all.

    Juanma

bug#10600: 24.0.92; `describe-char': text properties and [Show]

[Drew Adams]

> > The current window for that calculation does not correspond 
> > to *Help* at all.  It is wrong to assume that *Help* will be
> > displayed in a window having the same width as the window
> > where the help command is invoked.
> 
> Yes.
> 
> > It's simply misguided to base the assumed *Help* window 
> > width on the width of any existing window.
> 
> I disagree. I think it makes  sense to base it on the width of the
> window used to display it. In cases like this one, it should be
> possible to display the (empty) buffer, then generate its output.

For one thing, that is not done today, so your statement about disagreeing does
not in fact point to any _existing_ window (today) which it makes sense to use
as the measure of the yet-to-be-displayed *Help* window.

For another thing, the width of the window chosen to display the *Help* buffer
text can depend on the width of that buffer text.  That we do not do that often
today is not a reason not to allow for it.  That is exactly what I do with
frames, for example: I fit the frame to the buffer text, and I rely upon the
help functions to produce a reasonable buffer layout.

But yes, for a window or a frame, there are default widths that are in effect as
well.

At any rate, I am not necessarily opposed to what you describe - as one user
choice (and not as something to be imposed).

But in that case, the key is to know what the display window is.  That is a far
cry from what we do today, which is to use the current window to guess the width
of the to-be-displayed *Help* window.  That makes no sense at all.

> > We already go to the trouble of wrapping help text at such a limit.
> 
> By hand, you mean?  Because if you define a function with a docstring
> 100 chars long, and do M-x describe-function my-test-func <RET>,
> there's no wrap at all.

Yes there is, or there should be a wrap, for doc strings provided by Emacs
itself.  That's a long accepted design criterion, though yes, there are
occasionally bugs (which do get fixed).  And yes, we typically write doc strings
by hand, and we decide where to break lines (often with the help of `M-q').

And in addition to doc strings, which are conventionally as described above, for
the most part dynamically composed *Help* text is filled, which uses the current
value of `fill-column'.  And that's often the default value, 70.

So in practice it is rare (and IMO a bug) when a *Help* buffer is much wider
than, say 80 chars.

---

FWIW, I have coded my own version of `describe-char' that DTRT.  The code passes
an optional WIDTH-SO-FAR arg to functions such as `describe-text-sexp',
`describe-property-list', `describe-text-properties', and
`describe-text-properties-1', and it has such functions update and return the
max such width they've contributed to.

If interested, you can find it here:
http://www.emacswiki.org/emacs/download/descr-text%2b.el.  If really interested,
I could send it in the form of a patch.

(This code also fixes bug #10129: It shows also the cursor position, which is
otherwise missing and appears only in an ephemeral message.)

---

In general, it is (and it should be) up to the individual functions that compose
(any) bits of *Help* text to decide whether and where to fill or break it.  In
the case of `describe-char', it seems to be the font name that is the typically
longest line.  I have no problem with that line not being broken and serving to
set the window (frame) width.  The `[Show]' fields mentioned in the bug report
come after that longest line anyway, so at least in the case of `describe-char'
they are typically all shown completely.

bug#10600: 24.0.92; `describe-char': text properties and [Show]

[Juanma Barranquero]

On Fri, Jan 27, 2012 at 22:43, Drew Adams <drew.adams@oracle.com> wrote:

> For one thing, that is not done today, so your statement about disagreeing does
> not in fact point to any _existing_ window (today) which it makes sense to use
> as the measure of the yet-to-be-displayed *Help* window.

When you say

> It's simply misguided to base the assumed *Help* window
> width on the width of any existing window.

that's a general statement, not specifically about today's windows.

> For another thing, the width of the window chosen to display the *Help* buffer
> text can depend on the width of that buffer text.  That we do not do that often
> today is not a reason not to allow for it.  That is exactly what I do with
> frames, for example: I fit the frame to the buffer text, and I rely upon the
> help functions to produce a reasonable buffer layout.

So you're computing the window (and frame) width from the buffer text,
and complaining that you don't like how the buffer text is
distributed, because it exceeds the maximum width you want to give to
a window or frame. But, as reflowing the buffer text according to the
window width would defeat your method, the only option left is to
chose an arbitrary limit and stick to it, even if, in some cases, a
different width is best for most users...

In many, but not all, *Help* buffers, reflowing or not reflowing their
contents is largely irrelevant. But for the output of describe-char,
the way it is now is IMHO much, *much* better that what you proposed
before (getting rid of the right-alignment of field names), and
certainly I don't think reflowing it would improve things, on the
contrary it would make them less clear.

> But in that case, the key is to know what the display window is.  That is a far
> cry from what we do today, which is to use the current window to guess the width
> of the to-be-displayed *Help* window.  That makes no sense at all.

I wouldn't go as far as to say that it does "make no sense at all",
because it obviously works in many common cases. But it is erroneous,
sure.

> Yes there is, or there should be a wrap, for doc strings provided by Emacs itself.

On the contrary, I disagree on that "should be". *Help* buffers try to
give useful information, and manual reflowing is almost always better
than automatic reflowing. It fails for some narrow windows, but that's
why we use 70 chars or so as a limit. Automatic reflow to support the
likely very few users who use extremelly narrow windows seems a waste
and a step back.

> And in addition to doc strings, which are conventionally as described above, for
> the most part dynamically composed *Help* text is filled, which uses the current
> value of `fill-column'.  And that's often the default value, 70.

I think most dynamically composed *Help* text tends to be
line-oriented (i.e, it adds \n with glee), but obviously, in cases
where the text does not need careful formating, leaving it to
automatic reflowing is a valid answer. That does not mean that it is
the best, or preferred, method to write *Help* output. That depends
entirely of the output.

> So in practice it is rare (and IMO a bug) when a *Help* buffer is much wider
> than, say 80 chars.

Again, that depends on the output. There are cases where using more,
if the window is wide enough, is clearer.

    Juanma

bug#10600: 24.0.92; `describe-char': text properties and [Show]

[Drew Adams]

Just try the code (essentially a patch) I pointed you to.

It DTRT, IMO, deciding whether to use `[Show]' or the button's real text based
on the maximum line length up to that point.  IOW, the longest line (which is
typically the font name) determines the buffer width.  And given knowledge of
that width, full button text or `[Show]' is used accordingly.

http://www.emacswiki.org/emacs/download/descr-text%2b.el.

bug#10600: 24.0.92; `describe-char': text properties and [Show]

[Kevin Rodgers]

On 1/28/12 10:15 AM, Juanma Barranquero wrote:
> On Fri, Jan 27, 2012 at 22:43, Drew Adams<drew.adams@oracle.com>  wrote:
...
>> For another thing, the width of the window chosen to display the *Help* buffer
>> text can depend on the width of that buffer text.  That we do not do that often
>> today is not a reason not to allow for it.  That is exactly what I do with
>> frames, for example: I fit the frame to the buffer text, and I rely upon the
>> help functions to produce a reasonable buffer layout.
>
> So you're computing the window (and frame) width from the buffer text,
> and complaining that you don't like how the buffer text is
> distributed, because it exceeds the maximum width you want to give to
> a window or frame. But, as reflowing the buffer text according to the
> window width would defeat your method, the only option left is to
> chose an arbitrary limit and stick to it, even if, in some cases, a
> different width is best for most users...
>
> In many, but not all, *Help* buffers, reflowing or not reflowing their
> contents is largely irrelevant. But for the output of describe-char,
> the way it is now is IMHO much, *much* better that what you proposed
> before (getting rid of the right-alignment of field names), and
> certainly I don't think reflowing it would improve things, on the
> contrary it would make them less clear.
>
>> But in that case, the key is to know what the display window is.  That is a far
>> cry from what we do today, which is to use the current window to guess the width
>> of the to-be-displayed *Help* window.  That makes no sense at all.
>
> I wouldn't go as far as to say that it does "make no sense at all",
> because it obviously works in many common cases. But it is erroneous,
> sure.
>
>> Yes there is, or there should be a wrap, for doc strings provided by Emacs itself.
>
> On the contrary, I disagree on that "should be". *Help* buffers try to
> give useful information, and manual reflowing is almost always better
> than automatic reflowing. It fails for some narrow windows, but that's
> why we use 70 chars or so as a limit. Automatic reflow to support the
> likely very few users who use extremelly narrow windows seems a waste
> and a step back.

Would it be feasible to create a temporary *Help* buffer/window/frame
with no text at all, which is "displayed" by Emacs but not rendered to
the user (i.e. not mapped by the terminal / window system), for the
purpose of querying its width and using that value when filling the real
*Help* buffer text?

-- 
Kevin Rodgers
Denver, Colorado, USA

bug#10600: 24.0.92; `describe-char': text properties and [Show]

[martin rudalics]

 > Would it be feasible to create a temporary *Help* buffer/window/frame
 > with no text at all, which is "displayed" by Emacs but not rendered to
 > the user (i.e. not mapped by the terminal / window system), for the
 > purpose of querying its width and using that value when filling the real
 > *Help* buffer text?

There are many ways to handle the problems cited (and also that of
formatting man buffers).  Basically, we should either know the size of
the window before rendering the buffer or know the rendering of the
buffer before creating the window.  I'm afraid though that any of these
approaches will require rewriting lots of `with-output-to-temp-buffer'
and similar functions.

martin