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

From: "Drew Adams" <[email-masked]>
Date: Fri, 27 Jan 2012 13:43:56 -0800

> > 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.