bug#10127: 24.0.91; wrong window width calc for `C-u C-x =' when *Help* in separate frame

[Drew Adams]

> No matter how you format the various fields of the information
> displayed by "C-u C-x =", it will eventually happen that the
> window is not wide enough to display something like this:
>    foo bar: bla-bla-bla yak-yak-yak
> in a single screen line.

Agreed, assuming a conventional line length limit for a *Help* buffer (which I
support).

In fact, that is already the case.  I see this, for instance:

          display: by this font (glyph code)
    uniscribe:-outline-Lucida
Console-normal-normal-normal-mono-14-*-*-*-c-*-iso8859-1 (#x25)

The `display:' field has the normal alignment for the colon.  The `uniscribe:'
field does not.  Some leading whitespace was apparently sacrificed to try to
compensate a little, but it is not sufficient.  The text in the line is just too
long - it violates the max *Help* line length convention.

> When this happens, the current code does the following:
>   . it inserts a newline after the colon
>   . it indents to the column just past the one occupied by the colon
>   . it then inserts the remaining text at that point
>
> The result is roughly this:
>     foo bar:
>              bla-bla-bla yak-yak-yak

FWIW, It does not seem to do that in the case I just mentioned.  If it did, the
result would presumably be this:

          uniscribe:
                    -outline-Lucida
Console-normal-normal-normal-mono-14-*-*-*-c-*-iso8859-1 (#x25)

> There are several possible ways to change this.  One is just
> displaying the value disregarding the window width, producing a
> continuation line:
>     foo bar: bla-bla-bla yak-\
>  yak-yak

That violates the *Help* line-limit convention (already the case, for a font).
And it works against frame/window fitting to the buffer text.

> Another is to force word-wrap in the *Help* buffer, resulting in
>     foo bar: bla-bla-bla \
>  yak-yak-yak

Word-wrapping is a bad idea here, IMO, as some of these fields do not have a
notion of "word", and whitespace can be significant in some cases (e.g. fonts).

> Yet another is do the equivalent of M-q, with this result:
>     foo bar: bla-bla-bla
>              yak-yak-yak

Again, that will be wrong in some cases, particular cases like a font name,
where whitespace in the value is significant.

> There are others, I'm sure. So which one is the best?

First, a comment wrt my own use case, which has a separate frame for *Help*.  In
my case, having lines that are longer than the usual limit is not a problem.  My
setup automatically fits the frame to the buffer text, no matter how wide (up to
the screen width or a user-defined limit).

See attached screenshots for examples.  With the current behavior, the longest
line in the example help text is 93 chars.  That's too long, IMO, but it is
still OK wrt frame-fitting and practical use, as can be seen.

(Screenshots *help.png and *help-1.png both show what current, vanilla Emacs
gives, with different widths for the window where you hit `C-u C-x ='.)

That's an aside, but it's worth mentioning.  The line-length limit is not so
pertinent in my use case.  But yes, I would prefer that *Help* always impose its
conventional line length limit.

(Note that the `preferred charset' and `file code' fields are already
wrapped/multiline, presumably on purpose.  And the char code properties and text
properties fields are likewise already multiline.  I'm guessing these are all
special-cased in the code - dunno.)

Wrt which is best: IMO, again, best is probably to keep it simple.

Without knowing or thinking much about the particular field values possible
(thus ignoring special-casing), I'd say we should:

1. Hard-wrap (i.e., insert a newline) at the *Help* line-width limit (70?).

2. Add an extra newline after a (final) multiline value, to visually separate
the multiline field from the next field.

(A multiline field includes a continuation-line field, from #1.)

E.g.:
     foo bar: bla-bla-bla yak-
yak-yak

Yes, any use of continuation lines (whether inserting newlines or not) can be
ugly, making it difficult to distinguish field headings from continued values.
The same problem can arise with other choices, though not necessarily to the
same degree.  #2 hopes to help with this.

So far, this assumes that you choose to continue with the current
right-alignment of field headings (names).  If instead you follow my suggestion
of doing something simpler then I think things could be clearer.  See the other
attached screenshots (*help-[2345].png), all of which follow this same general
suggestion:

1. A hard line-length limit for all *Help* buffers.
2. A newline after each field (i.e., after its last value line).
3. Field headers left-aligned, followed by a colon.
4. Field values (but not their continuation lines) indented
   wrt field headers.

#2 could be relaxed, e.g., inserting the newline only if the field value is
multiline.

In screenshot *help-2.png I did not reformat the last two fields, which
themselves are lists, and I did not reformat `category:' (didn't realize it was
a list).

Formatting of list values could be done the same way, using an additional
indentation level.  The other screenshots (*help-[345].png) show that.
Screenshot *help-5.png combines this with the relaxation described for #2.

(Note that I also moved the `customize what to show' link before the colon, as I
guess it is not part of the field value itself.  I.e.:

  Character code properties (customize what to show):

vs

  Character code properties: customiize what to show
)

Yes, there is a tradeoff to some extent between (a) readability and compactness,
on the one hand, and (b) flexibility and ability to represent any field value
unambiguously and without "jumps" (see below) or overrunning the line-length
limit.

I think screenshot *help-5.png compares favorably with the current Emacs display
(*help[1].png).  But some more complicated special treatment like what is done
now could be factored in if you prefer, to perhaps improve the
formatting/readability (dunno).  Again, I'm not against any complicated
treatment, as long as the result is good for users (readable, flexible).

Comparing just screenshots *help-5.png and *help[1].png:

 38 lines vs 27/30 (could be 26 with a wide starting window)
 no long lines vs one
 no "jumps" (extra newlines after headers) vs one/four
 consistent vs inconsistent treatment of fields & subfields
 no need to divine the target window's width vs guessing

Wrt the "jumps": hitting `C-u C-x =' in a narrower window produces more jumps in
current Emacs.  It would never produce jumps with the suggested formatting.

HTH.

throw-char-desc-help.png
Description: PNG image

throw-char-desc-help-2.png
Description: PNG image

throw-char-desc-help-3.png
Description: PNG image

throw-char-desc-help-4.png
Description: PNG image

throw-char-desc-help-5.png
Description: PNG image

throw-char-desc-help-1.png
Description: PNG image