bug#32536: 24.3; Feature Request: change defaults or behaviour

bug#32536: 24.3; Feature Request: change defaults or behaviour

[hw]

This is not bug report but a change or a feature request:

Please change the default behaviour of the (man) function or the default
value of Man-width to 75 such that manual pages are formatted to a
reasonable width by default.  The same goes for other manuals that are
being formatted before displayed.

Text is best read when it is displayed in about 70--80 characters per
line.  The size of the window the text is displayed in does not change
this.  It is reasonable to assume that users rather have manual pages
displayed with line lengths that make them easy to read than having them
displayed at about 300 characters per line when the window happens to be
full screen or 140 when they have two windows side by side.  When a user
needs wider text, they can still change the default.


As a feature request:

How about changing the effect of Man-width, or an additional setting:
Emacs could usefully format manual pages to fit the window when the
window is narrower than the default width of manual pages (unless the
window is ridiculously narrow, in which case it could fall back to the
default width for manual pages) and format them no wider than the
default width of manual pages for windows that are wider.  It could
also, depending on a(nother) setting(s), dynamically re-format the
manual pages to

min(
    (width_of_window <= ridiculously_narrow) ?
    max_width_of_manual_pages : width_of_window,
    max_width_of_manual_pages
   )

when the window is resized and had been less wide than the maximal width
for manual pages before.

The "max_width_of_manual_pages" could be a range, like 70 to 100,
because it may be desirable to use a couple more characters per line
when the width of the window allows it, without going crazy.  The
default for "ridiculously_narrow" might be like 60.  Of course, this
can all be changed by the user.

This feature might be cool for those who like dynamic (re-)formatting; I
don't think it's much needed.



In GNU Emacs 24.3.1 (x86_64-redhat-linux-gnu, GTK+ Version 3.22.10)
 of 2017-09-20 on c1bm.rdu2.centos.org
Configured using:
 `configure '--build=x86_64-redhat-linux-gnu'
 '--host=x86_64-redhat-linux-gnu' '--program-prefix='
 '--disable-dependency-tracking' '--prefix=/usr' '--exec-prefix=/usr'
 '--bindir=/usr/bin' '--sbindir=/usr/sbin' '--sysconfdir=/etc'
 '--datadir=/usr/share' '--includedir=/usr/include'
 '--libdir=/usr/lib64' '--libexecdir=/usr/libexec'
 '--localstatedir=/var' '--sharedstatedir=/var/lib'
 '--mandir=/usr/share/man' '--infodir=/usr/share/info' '--with-dbus'
 '--with-gif' '--with-jpeg' '--with-png' '--with-rsvg' '--with-tiff'
 '--with-xft' '--with-xpm' '--with-x-toolkit=gtk3' '--with-gpm=no'
 'build_alias=x86_64-redhat-linux-gnu'
 'host_alias=x86_64-redhat-linux-gnu' 'CFLAGS=-DMAIL_USE_LOCKF -O2 -g
 -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions
 -fstack-protector-strong --param=ssp-buffer-size=4
 -grecord-gcc-switches -m64 -mtune=generic' 'LDFLAGS=-Wl,-z,relro ''

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8
  default enable-multibyte-characters: t

Major mode: Org

Minor modes in effect:
  diff-auto-refine-mode: t
  shell-dirtrack-mode: t
  show-paren-mode: t
  desktop-save-mode: t
  tags-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  size-indication-mode: t
  column-number-mode: t
  line-number-mode: t
  auto-fill-function: org-auto-fill-function
  transient-mark-mode: t

Recent input:
O A ESC O A ESC O A ESC O A ESC O A ESC O A ESC O A 
ESC O A ESC O A ESC O A ESC O A ESC O A ESC O A ESC 
O A ESC O A ESC O B ESC O C ESC O B ESC O C C-x b * 
G r TAB RET L C-s C-s ESC O D RET ESC < ESC > ESC O 
A ESC O A ESC O A ESC O A ESC O A ESC O A ESC O A ESC 
O A ESC O A ESC O A ESC O A ESC O A ESC O A ESC O A 
ESC O A ESC O A ESC O A ESC O A ESC O A ESC O A ESC 
O A ESC O A ESC O A ESC O A ESC O A ESC O B ESC O B 
ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC 
O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B 
ESC O B ESC O B ESC O B ESC O B ESC O B ESC O B ESC 
O B ESC O A ESC O A ESC O A ESC O A ESC O A ESC O A 
ESC O A ESC O A ESC O A ESC O A ESC O A ESC O A ESC 
O A ESC O A RET C-x b RET C-x 1 C-x b e d TAB RET C-s 
d e b C-s C-s C-s C-s C-s C-s C-s C-s C-a C-s g n u 
C-s C-s C-s C-s C-a ESC x r e p o r TAB RET

Recent messages:
SUBTREE (NO CHILDREN)
FOLDED
Mark saved where search started
No more unseen articles
No more unread articles
Mark set [2 times]
Mark saved where search started [2 times]

Load-path shadows:
None found.

Features:
(shadow emacsbug bookmark shr browse-url gnus-dired pp etags man
mule-util network-stream starttls url-http url-gw url-cache url-auth url
url-proxy url-privacy url-expand url-methods url-history url-cookie
url-domsuf url-util url-parse url-vars linum tabify org-table asm-mode
info diff-mode jka-compr gnus-draft debug shell gnus-dup misearch
multi-isearch help-mode hi-lock cperl-mode flyspell ispell sort
gnus-cite flow-fill mm-archive mail-extr gnus-async gnus-bcklg
parse-time qp gnus-ml disp-table utf-7 utf7 rfc2104 tls imap auth-source
eieio nndraft nnmh nnfolder nnml gnus-agent gnus-srvr gnus-score
score-mode nnvirtual gnus-msg gnus-cache gnus-demon nntp gnus-diary
gnus-art mm-uu mml2015 epg-config mm-view mml-smime smime password-cache
dig mailcap nndiary gnus-sum gnus-group gnus-undo nnmail mail-source
nnoo gnus-start gnus-spec gnus-int gnus-range gnus-win gnus gnus-ems
nnheader wid-edit rst compile conf-mode cc-langs cl cc-mode cc-fonts
cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs
sh-script smie executable eldoc python rx vc-git org-wl org-w3m org-vm
org-rmail org-mhe org-mew org-irc org-jsinfo org-infojs org-html org-exp
ob-exp org-exp-blocks org-agenda org-info org-gnus gnus-util org-docview
org-bibtex bibtex org-bbdb org byte-opt warnings bytecomp byte-compile
cconv ob-tangle ob-ref ob-lob ob-table org-footnote org-src ob-comint
ob-keys org-pcomplete pcomplete comint ansi-color ring org-list
org-faces org-entities noutline outline easy-mmode org-version
ob-emacs-lisp ob org-compat org-macs ob-eval org-loaddefs find-func
cal-menu calendar cal-loaddefs message sendmail format-spec rfc822 mml
mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 rfc2047 rfc2045
ietf-drums mm-util mail-prsvr mailabbrev mail-utils gmm-utils mailheader
finder-inf package uniquify advice help-fns cl-lib advice-preload server
two-column edmacro kmacro time-date paren cus-start cus-load desktop
dired fvwm-mode easymenu lsl-mode tooltip ediff-hook vc-hooks
lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image regexp-opt
fringe tabulated-list newcomment lisp-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax
facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer loaddefs button faces
cus-face macroexp files text-properties overlay sha1 md5 base64 format
env code-pages mule custom widget hashtable-print-readable backquote
make-network-process dbusbind dynamic-setting system-font-setting
font-render-setting move-toolbar gtk x-toolkit x multi-tty emacs)

-- 

bug#32536: displayed width of man pages

[Juri Linkov]

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

> As a feature request:
>
> How about changing the effect of Man-width, or an additional setting:
> Emacs could usefully format manual pages to fit the window when the
> window is narrower than the default width of manual pages (unless the
> window is ridiculously narrow, in which case it could fall back to the
> default width for manual pages) and format them no wider than the
> default width of manual pages for windows that are wider.

Thanks for the feature request.

As proposed in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=9385
this patch implements a new option "Maximum width" as a hard limit
that prevents the width to grow over this value:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: man-maximum-width.1.patch --]
[-- Type: text/x-diff, Size: 1526 bytes --]

diff --git a/lisp/man.el b/lisp/man.el
index 1a6eda13b7..fcf9085d20 100644
--- a/lisp/man.el
+++ b/lisp/man.el
@@ -179,6 +179,7 @@ Man-width
 The value also can be a positive integer for a fixed width."
   :type '(choice (const :tag "Window width" nil)
                  (const :tag "Frame width" t)
+                 (cons :tag "Maximum width" (const :value max) (integer :value 80))
                  (integer :tag "Fixed width" :value 65))
   :group 'man)
 
@@ -1045,16 +1046,20 @@ Man-start-calling
 			 (cond
 			  ((and (integerp Man-width) (> Man-width 0))
 			   Man-width)
-			  (Man-width
+			  ((eq Man-width t)
 			   (if (window-live-p (get-buffer-window (current-buffer) t))
 			       (with-selected-window (get-buffer-window (current-buffer) t)
 				 (frame-width))
 			     (frame-width)))
 			  (t
-			   (if (window-live-p (get-buffer-window (current-buffer) t))
-			       (with-selected-window (get-buffer-window (current-buffer) t)
-				 (window-width))
-			     (window-width)))))))
+			   (let ((width
+				  (if (window-live-p (get-buffer-window (current-buffer) t))
+				      (with-selected-window (get-buffer-window (current-buffer) t)
+					(window-width))
+				    (window-width))))
+			     (if (eq (car-safe Man-width) 'max)
+				 (min width (cdr Man-width))
+			       width)))))))
     ;; Since man-db 2.4.3-1, man writes plain text with no escape
     ;; sequences when stdout is not a tty.	In 2.5.0, the following
     ;; env-var was added to allow control of this (see Debian Bug#340673).

bug#32536: displayed width of man pages

[martin rudalics]

 > As proposed in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=9385
 > this patch implements a new option "Maximum width" as a hard limit
 > that prevents the width to grow over this value:

While you're there could you please do some idiomatic changes that
avoid selecting a window in order to calculate its width:

For example, replace

(let ((width
        (if (window-live-p (get-buffer-window (current-buffer) t))
	   (with-selected-window (get-buffer-window (current-buffer) t)
	     (window-width))
	 (window-width)))))

with something like

(window-width (get-buffer-window nil t))

and

(if (window-live-p (get-buffer-window (current-buffer) t))
     (with-selected-window (get-buffer-window (current-buffer) t)
       (frame-width))
   (frame-width))

with something like

(let ((window (get-buffer-window nil t)))
   (frame-width (and window (window-frame window))))

Probably you also want to add a version tag for 'Man-width'.

Thanks, martin

bug#32536: displayed width of man pages

[Juri Linkov]

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

> While you're there could you please do some idiomatic changes that
> avoid selecting a window in order to calculate its width:
>
> For example, replace
>
> (let ((width
>        (if (window-live-p (get-buffer-window (current-buffer) t))
> 	   (with-selected-window (get-buffer-window (current-buffer) t)
> 	     (window-width))
> 	 (window-width)))))
>
> with something like
>
> (window-width (get-buffer-window nil t))
>
> and
>
> (if (window-live-p (get-buffer-window (current-buffer) t))
>     (with-selected-window (get-buffer-window (current-buffer) t)
>       (frame-width))
>   (frame-width))
>
> with something like
>
> (let ((window (get-buffer-window nil t)))
>   (frame-width (and window (window-frame window))))
>
> Probably you also want to add a version tag for 'Man-width'.

Right, fixed in the next patch where a version tag is added not to
`Man-width', but to the new customizable variable `Man-width-max'.
This is better since like when man-pages are formatted in their
web versions they limit the width using the CSS property `max-width',
so like CSS has both `width' and `max-width', man.el will have
`Man-width' and `Man-width-max'.

Regarding the request for dynamic reformatting, I'm not sure if
man pages should be reformatted on resizing windows (I remember
seeing a window resize hook, but can't find it now).

Such window resize is necessary also for some other modes,
for example, when a visited image is saved to the desktop file,
it has a wrong size after loading the desktop, because the
image size is calculated when the image file is not yet displayed
in a window.  The image size should be recalculated after
displaying the image buffer.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: man-maximum-width.2.patch --]
[-- Type: text/x-diff, Size: 2625 bytes --]

diff --git a/lisp/man.el b/lisp/man.el
index 1a6eda13b7..08a913b119 100644
--- a/lisp/man.el
+++ b/lisp/man.el
@@ -182,6 +182,20 @@ Man-width
                  (integer :tag "Fixed width" :value 65))
   :group 'man)
 
+(defcustom Man-width-max nil
+  "Maximum number of columns allowed for the width of manual pages.
+It defines the maximum width for the case when `Man-width' is customized
+to a dynamically calculated value depending on the frame/window width.
+If the width calculated for `Man-width' is larger than the maximum width,
+it will be automatically reduced to the width defined by this variable.
+If the calculated width is smaller than the maximum width, the value
+of this variable has no effect.
+When nil, there is no limit on maximum width."
+  :type '(choice (const :tag "No limit" nil)
+                 (integer :tag "Max width" :value 80))
+  :version "27.1"
+  :group 'man)
+
 (defcustom Man-frame-parameters nil
   "Frame parameter list for creating a new frame for a manual page."
   :type '(repeat (cons :format "%v"
@@ -1041,20 +1055,19 @@ Man-start-calling
 	      (not (or (getenv "MANWIDTH") (getenv "COLUMNS"))))
       ;; Since the page buffer is displayed beforehand,
       ;; we can select its window and get the window/frame width.
-      (setenv "COLUMNS" (number-to-string
-			 (cond
-			  ((and (integerp Man-width) (> Man-width 0))
-			   Man-width)
-			  (Man-width
-			   (if (window-live-p (get-buffer-window (current-buffer) t))
-			       (with-selected-window (get-buffer-window (current-buffer) t)
-				 (frame-width))
-			     (frame-width)))
-			  (t
-			   (if (window-live-p (get-buffer-window (current-buffer) t))
-			       (with-selected-window (get-buffer-window (current-buffer) t)
-				 (window-width))
-			     (window-width)))))))
+      (let ((width (cond
+                    ((and (integerp Man-width) (> Man-width 0))
+                     Man-width)
+                    (Man-width
+                     (let ((window (get-buffer-window nil t)))
+                       (frame-width (and window (window-frame window)))))
+                    (t
+                     (window-width (get-buffer-window nil t))))))
+        (when (and (integerp Man-width-max)
+                   (> Man-width-max 0)
+                   (> width Man-width-max))
+          (setq width (min width Man-width-max)))
+        (setenv "COLUMNS" (number-to-string width))))
     ;; Since man-db 2.4.3-1, man writes plain text with no escape
     ;; sequences when stdout is not a tty.	In 2.5.0, the following
     ;; env-var was added to allow control of this (see Debian Bug#340673).

bug#32536: displayed width of man pages

[martin rudalics]

 > Regarding the request for dynamic reformatting, I'm not sure if
 > man pages should be reformatted on resizing windows (I remember
 > seeing a window resize hook, but can't find it now).

It's called 'window-size-change-functions'.

 > Such window resize is necessary also for some other modes,

Why "Such window resize"?  We talk about reformatting buffer contents
when a window gets resized for some reason.  We do not want to resize
the window when reformatting a man page because we know the length of
Man lines beforehand.

 > for example, when a visited image is saved to the desktop file,
 > it has a wrong size after loading the desktop, because the
 > image size is calculated when the image file is not yet displayed
 > in a window.  The image size should be recalculated after
 > displaying the image buffer.

This would be probably about fitting a window to the image it
displays.  But why do we have to display the image first and then
recalculate its size?  Don't we know the image size in advance?

martin

bug#32536: displayed width of man pages

[hw]

Juri Linkov <juri@linkov.net> writes:

> [...]
> Regarding the request for dynamic reformatting, I'm not sure if
> man pages should be reformatted on resizing windows (I remember
> seeing a window resize hook, but can't find it now).

Perhaps if they /can/ be reformatted dynamically, have a variable like
`Man-dynamic-reformat-lines-max' so users can prevent the reformatting
for instances in which it takes too long.  Then a problem is that the
number of lines varies with the width of the page, and instead of the
number of lines, the size in bytes (kB, MB ...) of the page might be
more relevant for reformatting it.

Unfortunately, users usually have no idea what the size of a manual page
in bytes is, and the pages are even stored compressed.  Users would have
to try out what size makes sense to dynamically reformat on their
particular hardware and may end up simply turning the feature off
because they do not resize windows while reading manual pages anyway.

Does it take longer to format the same manual page into 2500 lines or
into 5000 lines?

Would it be possible to do the reformatting in the background, and
delayed, like fontifying a buffer?

bug#32536: displayed width of man pages

[Juri Linkov]

> Perhaps if they /can/ be reformatted dynamically, have a variable like
> `Man-dynamic-reformat-lines-max' so users can prevent the reformatting
> for instances in which it takes too long.  Then a problem is that the
> number of lines varies with the width of the page, and instead of the
> number of lines, the size in bytes (kB, MB ...) of the page might be
> more relevant for reformatting it.
>
> Unfortunately, users usually have no idea what the size of a manual page
> in bytes is, and the pages are even stored compressed.  Users would have
> to try out what size makes sense to dynamically reformat on their
> particular hardware and may end up simply turning the feature off
> because they do not resize windows while reading manual pages anyway.
>
> Does it take longer to format the same manual page into 2500 lines or
> into 5000 lines?
>
> Would it be possible to do the reformatting in the background, and
> delayed, like fontifying a buffer?

Man pages are already formatted asynchronously in the background,
so actually reformatting on window resize should be quite responsible
even for large manuals (maybe an addition flag is needed to prevent
updating when a previous update is in progress).

You can try and see how fast it reformats, typing repeatedly the key `u'
(Man-update-manpage).

bug#32536: displayed width of man pages

[Juri Linkov]

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

>> Regarding the request for dynamic reformatting, I'm not sure if
>> man pages should be reformatted on resizing windows (I remember
>> seeing a window resize hook, but can't find it now).
>
> It's called 'window-size-change-functions'.

Thanks, I tried window-size-change-functions, and it works pretty well
with the patch attached.  But there are a few problems:

1. In Man-mode we have to add hook window-size-change-functions only
   buffer-locally (using the arg LOCAL of add-hook) rather than globally,
   because otherwise we can't remove this hook when a Man buffer is
   not displayed anymore.  But the problem is that buffer-local
   window-size-change-functions is called only when the current buffer
   is in Man-mode.  If it's not, it's not called even when resizing of
   the current non-Man buffer causes the resize of a Man-mode buffer
   in an adjacent window.

2. What if the same Man-mode buffer is displayed in two adjacent windows
   side-by-side?  I guess we need to find all windows with the same buffer,
   compare their widths, and call Man-update-manpage only in the window
   with minimal width.  Also it seems window-size-change-functions is
   not called twice for every window with Man-mode buffer, this is good.

3. When windows are resized using the mouse, is it possible to call
   window-size-change-functions only when the mouse button is released?
   This will increase responsiveness.  But the same problem will remain
   for keyboard resizing with e.g. C-x } } }
   A debounce-like function could help, but I can't find its Emacs Lisp
   implementation anywhere.   I mean something similar to
   https://stackoverflow.com/questions/15927371/what-does-debounce-do
   It's easy to implement using timers, but better to have idiomatic
   implementation.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Man-window-size-change.1.patch --]
[-- Type: text/x-diff, Size: 966 bytes --]

diff --git a/lisp/man.el b/lisp/man.el
index 1a6eda13b7..f737594de7 100644
--- a/lisp/man.el
+++ b/lisp/man.el
@@ -1524,7 +1537,17 @@ Man-mode
   (set (make-local-variable 'outline-regexp) Man-heading-regexp)
   (set (make-local-variable 'outline-level) (lambda () 1))
   (set (make-local-variable 'bookmark-make-record-function)
-       'Man-bookmark-make-record))
+       'Man-bookmark-make-record)
+  (add-hook 'window-size-change-functions 'Man-window-size-change nil t))
+
+(defun Man-window-size-change (frame)
+  (walk-windows (lambda (window)
+                  (when (/= (window-pixel-width-before-size-change window)
+                            (window-pixel-width window))
+                    (with-current-buffer (window-buffer window)
+                      (when (derived-mode-p 'Man-mode)
+                        (Man-update-manpage)))))
+                'nomini frame))
 
 (defun Man-build-section-list ()
   "Build the list of manpage sections."

bug#32536: displayed width of man pages

[Juri Linkov]

>> for example, when a visited image is saved to the desktop file,
>> it has a wrong size after loading the desktop, because the
>> image size is calculated when the image file is not yet displayed
>> in a window.  The image size should be recalculated after
>> displaying the image buffer.
>
> This would be probably about fitting a window to the image it
> displays.  But why do we have to display the image first and then
> recalculate its size?  Don't we know the image size in advance?

Currently image-mode resizes the displayed image to fit into the window.
It can't do this when an image buffer is restored from the desktop file
and not yet displayed.

bug#32536: displayed width of man pages

[martin rudalics]

 > 1. In Man-mode we have to add hook window-size-change-functions only
 >     buffer-locally (using the arg LOCAL of add-hook) rather than globally,
 >     because otherwise we can't remove this hook when a Man buffer is
 >     not displayed anymore.

I can't follow you here.  Shouldn't we remove the hook _when_ a Man
buffer is not displayed anymore.  That is, when
'Man-window-size-change' detects that no Man buffer is displayed
anymore, remove it from 'window-size-change-functions' and re-add it
as soon as a Man buffer gets displayed again.

 >     But the problem is that buffer-local
 >     window-size-change-functions is called only when the current buffer
 >     is in Man-mode.  If it's not, it's not called even when resizing of
 >     the current non-Man buffer causes the resize of a Man-mode buffer
 >     in an adjacent window.
 >
 > 2. What if the same Man-mode buffer is displayed in two adjacent windows
 >     side-by-side?  I guess we need to find all windows with the same buffer,
 >     compare their widths, and call Man-update-manpage only in the window
 >     with minimal width.  Also it seems window-size-change-functions is
 >     not called twice for every window with Man-mode buffer, this is good.

I think 'Man-window-size-change' will have to take care of such cases.
Also we'll have to look into how 'follow-mode' works when displaying a
Man buffer in several side-by-side windows.

 > 3. When windows are resized using the mouse, is it possible to call
 >     window-size-change-functions only when the mouse button is released?
 >     This will increase responsiveness.  But the same problem will remain
 >     for keyboard resizing with e.g. C-x } } }
 >     A debounce-like function could help, but I can't find its Emacs Lisp
 >     implementation anywhere.   I mean something similar to
 >     https://stackoverflow.com/questions/15927371/what-does-debounce-do
 >     It's easy to implement using timers, but better to have idiomatic
 >     implementation.

I used a timer in 'mouse-autoselect-window'.  It might be interesting
to come up with a generic function.

martin

bug#32536: displayed width of man pages

[martin rudalics]

 > Currently image-mode resizes the displayed image to fit into the window.
 > It can't do this when an image buffer is restored from the desktop file
 > and not yet displayed.

You mean that after frameset has established a window/buffer
association there's no way to inform image-mode about that?

martin

bug#32536: displayed width of man pages

[Filipp Gunbin]

Hi, 

On 02/09/2018 01:27 +0300, Juri Linkov wrote:

> +      (let ((width (cond
> +                    ((and (integerp Man-width) (> Man-width 0))
> +                     Man-width)
> +                    (Man-width
> +                     (let ((window (get-buffer-window nil t)))
> +                       (frame-width (and window (window-frame window)))))
> +                    (t
> +                     (window-width (get-buffer-window nil t))))))
> +        (when (and (integerp Man-width-max)
> +                   (> Man-width-max 0)
> +                   (> width Man-width-max))
                      ^^^^^^^^^^^^^^^^^^^^^^
                      this check is not needed, as you call min in the
                      next line

> +          (setq width (min width Man-width-max)))
> +        (setenv "COLUMNS" (number-to-string width))))

bug#32536: displayed width of man pages

[Juri Linkov]

>> 1. In Man-mode we have to add hook window-size-change-functions only
>>     buffer-locally (using the arg LOCAL of add-hook) rather than globally,
>>     because otherwise we can't remove this hook when a Man buffer is
>>     not displayed anymore.
>
> I can't follow you here.  Shouldn't we remove the hook _when_ a Man
> buffer is not displayed anymore.  That is, when
> 'Man-window-size-change' detects that no Man buffer is displayed
> anymore, remove it from 'window-size-change-functions' and re-add it
> as soon as a Man buffer gets displayed again.

How to know the moment when a Man buffer gets displayed again?
Is there a corresponding hook for this event?

bug#32536: displayed width of man pages

[Juri Linkov]

>> Currently image-mode resizes the displayed image to fit into the window.
>> It can't do this when an image buffer is restored from the desktop file
>> and not yet displayed.
>
> You mean that after frameset has established a window/buffer
> association there's no way to inform image-mode about that?

image-mode can fit the image to the window sizes only when
the image buffer is displayed in a window.  Is there a hook
that is called when a buffer is displayed in a window?

bug#32536: displayed width of man pages

[hw]

Juri Linkov <juri@linkov.net> writes:

>> Perhaps if they /can/ be reformatted dynamically, have a variable like
>> `Man-dynamic-reformat-lines-max' so users can prevent the reformatting
>> for instances in which it takes too long.
> [...]
>> Would it be possible to do the reformatting in the background, and
>> delayed, like fontifying a buffer?
>
> Man pages are already formatted asynchronously in the background,
> so actually reformatting on window resize should be quite responsible
> even for large manuals (maybe an addition flag is needed to prevent
> updating when a previous update is in progress).

and maybe something that prevents multiple update requests piling up
while the window is being resized, unless the flag already takes care of
that

> You can try and see how fast it reformats, typing repeatedly the key `u'
> (Man-update-manpage).

Ah, hm, ok, that's maybe 0.25 seconds for the man page of fvwm with 9441
lines.  It may not be a good test because the width does not change in
my case, and I have fast hardware.

Is there a reason for not to skip such an update when the length of the
lines did not change?

I didn't know you could update; this is like perfect because who prefers
dynamic updates can use those and who doesn't can use `u' if need be :)

bug#32536: displayed width of man pages

[hw]

Juri Linkov <juri@linkov.net> writes:

>>> Regarding the request for dynamic reformatting, I'm not sure if
>>> man pages should be reformatted on resizing windows (I remember
>>> seeing a window resize hook, but can't find it now).
>>
>> It's called 'window-size-change-functions'.
>
> Thanks, I tried window-size-change-functions, and it works pretty well
> with the patch attached.  But there are a few problems:
>
> 1. In Man-mode we have to add hook window-size-change-functions only
> [...]
>
> 2. What if the same Man-mode buffer is displayed in two adjacent windows
>    side-by-side?  I guess we need to find all windows with the same buffer,
>    compare their widths, and call Man-update-manpage only in the window
>    with minimal width.  Also it seems window-size-change-functions is
>    not called twice for every window with Man-mode buffer, this is good.

How about a couple rules to make this simple:


A manual page should not be updated when


+ the size, or a change of the size, of a window displaying it does not
  require a change of the length of the lines

+ the desired length of the lines can not be determined.


Creating another window to display the same or a different buffer does
not require a change of the length of the lines.

Using multiple windows of different widths to display the same buffer
means that the desired length of the lines can not be determined.

When considering the width of each window displaying the same buffer, or
any buffer, leads to the same length of the lines, a length has been
determined.  This may be the desired length of the lines for Man-mode
buffers or not.


Above rules mean that you can ignore 1..

Just note this in the documentation so it becomes understandable why the
buffers in Man-mode are dynamically updated the way they are.  When
someone has a good idea how to figure out the desired length of lines
under all circumstances, they can always make a suggestion.

BTW, what is the default for the minimum length of the lines?  Is the
default for the maximum length the same?

bug#32536: displayed width of man pages

[martin rudalics]

 >> I can't follow you here.  Shouldn't we remove the hook _when_ a Man
 >> buffer is not displayed anymore.  That is, when
 >> 'Man-window-size-change' detects that no Man buffer is displayed
 >> anymore, remove it from 'window-size-change-functions' and re-add it
 >> as soon as a Man buffer gets displayed again.
 >
 > How to know the moment when a Man buffer gets displayed again?
 > Is there a corresponding hook for this event?

'window-configuration-change-hook' I presume.  Though this raises the
question how to remove anything from there when finishing browsing.

martin

bug#32536: displayed width of man pages

[martin rudalics]

 > image-mode can fit the image to the window sizes only when
 > the image buffer is displayed in a window.  Is there a hook
 > that is called when a buffer is displayed in a window?

'window-configuration-change-hook' traces the case where a different
buffer is displayed in a window.

martin

bug#32536: displayed width of man pages

[Juri Linkov]

> BTW, what is the default for the minimum length of the lines?  Is the
> default for the maximum length the same?

Like the new Man-width-max, we could also add Man-width-min as well.

bug#32536: displayed width of man pages

[Juri Linkov]

>>> I can't follow you here.  Shouldn't we remove the hook _when_ a Man
>>> buffer is not displayed anymore.  That is, when
>>> 'Man-window-size-change' detects that no Man buffer is displayed
>>> anymore, remove it from 'window-size-change-functions' and re-add it
>>> as soon as a Man buffer gets displayed again.
>>
>> How to know the moment when a Man buffer gets displayed again?
>> Is there a corresponding hook for this event?
>
> 'window-configuration-change-hook' I presume.  Though this raises the
> question how to remove anything from there when finishing browsing.

Using window-configuration-change-hook is a hugely cumbersome workaround
for deficiencies in window-size-change-functions.

I reported this in bug#32637, please see there.

bug#32536: displayed width of man pages

[hw]

Juri Linkov <juri@linkov.net> writes:

>> BTW, what is the default for the minimum length of the lines?  Is the
>> default for the maximum length the same?
>
> Like the new Man-width-max, we could also add Man-width-min as well.

I thought the line length would be determined depending on Man-width,
the new maximum width and the width of the window displaying the buffer.
That would make Man-width what specifies the minimum length:

If the width of the window suggests using a line length between
Man-width and the new maximum length, use the suggested length.
Otherwise use Man-width if the window is narrower than that, or the new
maximum length if the window is wider than the new maximum length.

Renaming Man-width to Man-width-min would make sense then, unless there
were a third option:  Always use the line length specified by
Man-width.  If this option would kick in when Man-width-min and
Man-width-max are not set, the behaviour would not change for anyone who
has set Man-width.

The default for all of them would be nil, assuming that Man-width-min
and Man-width-max do nothing when they are nil.

BTW, how come that describing Man-width says it is not documented as a
variable before man-mode has been active at least once, but its value is
known (as the value I set it to), and later used?  It seems unsave being
able to set arbitrary variables and having their values quietly accepted
without question by functions that are eventually loaded and which the
value of the variable may not have been intended for.

bug#32536: displayed width of man pages

[martin rudalics]

 > Using window-configuration-change-hook is a hugely cumbersome workaround
 > for deficiencies in window-size-change-functions.

But you want to track whether a window changes its buffer.  How does
this relate to 'window-size-change-functions' at all?

martin

bug#32536: displayed width of man pages

[Juri Linkov]

>>> BTW, what is the default for the minimum length of the lines?  Is the
>>> default for the maximum length the same?
>>
>> Like the new Man-width-max, we could also add Man-width-min as well.
>
> I thought the line length would be determined depending on Man-width,
> the new maximum width and the width of the window displaying the buffer.
> That would make Man-width what specifies the minimum length:
>
> If the width of the window suggests using a line length between
> Man-width and the new maximum length, use the suggested length.
> Otherwise use Man-width if the window is narrower than that, or the new
> maximum length if the window is wider than the new maximum length.
>
> Renaming Man-width to Man-width-min would make sense then, unless there
> were a third option:  Always use the line length specified by
> Man-width.  If this option would kick in when Man-width-min and
> Man-width-max are not set, the behaviour would not change for anyone who
> has set Man-width.
>
> The default for all of them would be nil, assuming that Man-width-min
> and Man-width-max do nothing when they are nil.

The value nil of Man-width means to dynamically calculate the line length
from the width of the window displaying the buffer.

bug#32536: displayed width of man pages

[hw]

Juri Linkov <juri@linkov.net> writes:

>>>> BTW, what is the default for the minimum length of the lines?  Is the
>>>> default for the maximum length the same?
>>>
>>> Like the new Man-width-max, we could also add Man-width-min as well.
>>
>> I thought the line length would be determined depending on Man-width,
>> the new maximum width and the width of the window displaying the buffer.
>> That would make Man-width what specifies the minimum length:
>>
>> If the width of the window suggests using a line length between
>> Man-width and the new maximum length, use the suggested length.
>> Otherwise use Man-width if the window is narrower than that, or the new
>> maximum length if the window is wider than the new maximum length.
>>
>> Renaming Man-width to Man-width-min would make sense then, unless there
>> were a third option:  Always use the line length specified by
>> Man-width.  If this option would kick in when Man-width-min and
>> Man-width-max are not set, the behaviour would not change for anyone who
>> has set Man-width.
>>
>> The default for all of them would be nil, assuming that Man-width-min
>> and Man-width-max do nothing when they are nil.
>
> The value nil of Man-width means to dynamically calculate the line length
> from the width of the window displaying the buffer.

Yes, I suggested this because it would not change the current default
behaviour.  If you want to change the default behaviour, I'd suggest 70
for Man-width-min and 80 for Man-width-max.

bug#32536: displayed width of man pages

[Juri Linkov]

> I reported this in bug#32637, please see there.

Thanks to Martin, a request in bug#32637 is now implemented and closed.

But still this bug#32536 can't be closed because I found an insolvable
problem: 'M-x occur' is impossible to use on automatically resized
Man-mode buffers: after running 'M-x occur' in a Man buffer, it splits
the wide frame horizontally, that changes the width of the Man buffer,
that causes window-size-change-functions to run, that starts a new
Man process to reformat the Man buffer according to the new width of the
Man buffer.  After that, typing RET on all matching lines in the Occur buffer
will jump to the beginning of the Man buffer, because reformatting invalidates
all markers that point from lines in the Occur buffer to lines in the
Man buffer, i.e. typing 'C-u C-x =' on all lines in the Occur buffer
displays the same:

  There are text properties here:
    occur-target         #<marker at 1 in *Man bash*>

bug#32536: displayed width of man pages

[martin rudalics]

 >> I reported this in bug#32637, please see there.
 >
 > Thanks to Martin, a request in bug#32637 is now implemented and closed.

BTW, I plan to change the behavior of 'window-size-change-functions'
as follows.

(1) Run the buffer-local hook not only once for each buffer per frame
     but for each window showing the buffer.

(2) Run the buffer-local hook with the window as argument instead of
     the frame.

(3) Run the buffer-local hook for changes of the window's body size
     too.

(4) Run the buffer-local hook also when a window has not shown the
     buffer the last time this hook was run.

This way, a function that should be run whenever a window showing a
certain buffer is created/used or changes size is guaranteed to run in
each case and no further checks are needed.

All changes would be strictly based on 'local-variable-p' (and not on
'buffer-local-value') so any calls from 'window-size-change-functions'
in Emacs < 27.1 would remain unaffected.  WDYT?

 > But still this bug#32536 can't be closed because I found an insolvable
 > problem: 'M-x occur' is impossible to use on automatically resized
 > Man-mode buffers: after running 'M-x occur' in a Man buffer, it splits
 > the wide frame horizontally, that changes the width of the Man buffer,
 > that causes window-size-change-functions to run, that starts a new
 > Man process to reformat the Man buffer according to the new width of the
 > Man buffer.  After that, typing RET on all matching lines in the Occur buffer
 > will jump to the beginning of the Man buffer, because reformatting invalidates
 > all markers that point from lines in the Occur buffer to lines in the
 > Man buffer, i.e. typing 'C-u C-x =' on all lines in the Occur buffer
 > displays the same:
 >
 >    There are text properties here:
 >      occur-target         #<marker at 1 in *Man bash*>

So essentially you would have to rerun occur whenever the Man buffer
is reformatted.

Otherwise, I see only one way to handle this.  Before reformatting,
store the context of each marker (in a bookmark-like or diff-like
fashion) and restore the markers from that context.  The matching done
in the restore step would have to identify and ignore "soft" changes
of whitespace.

martin

bug#32536: displayed width of man pages

[Juri Linkov]

> BTW, I plan to change the behavior of 'window-size-change-functions'
> as follows.
>
> (1) Run the buffer-local hook not only once for each buffer per frame
>     but for each window showing the buffer.

Good, so buffer-local hooks won't need to use walk-windows.

> (2) Run the buffer-local hook with the window as argument instead of
>     the frame.

Good.  When needed, it's easy to get the frame from the window argument.

> (3) Run the buffer-local hook for changes of the window's body size
>     too.

What might cause these changes?

> (4) Run the buffer-local hook also when a window has not shown the
>     buffer the last time this hook was run.

Good, so initial buffer display will be automatically handled as well.

> All changes would be strictly based on 'local-variable-p' (and not on
> 'buffer-local-value') so any calls from 'window-size-change-functions'
> in Emacs < 27.1 would remain unaffected.  WDYT?

This makes better sense.

>>    There are text properties here:
>>      occur-target         #<marker at 1 in *Man bash*>
>
> So essentially you would have to rerun occur whenever the Man buffer
> is reformatted.

It's too ad-hoc to find all Occur buffers created from the Man buffer,
and revert all of them.

> Otherwise, I see only one way to handle this.  Before reformatting,
> store the context of each marker (in a bookmark-like or diff-like
> fashion) and restore the markers from that context.  The matching done
> in the restore step would have to identify and ignore "soft" changes
> of whitespace.

This means additionally to finding all affected Occur buffers like above,
instead of reverting them, perform much more complex processing of
their markers.

It seems a more practical solution is to limit the width of Man buffers
to at least 80 columns by default, so splitting such windows will not
resize their number of columns, so they won't be reverted and reformatted.

bug#32536: displayed width of man pages

[martin rudalics]

 >> (3) Run the buffer-local hook for changes of the window's body size
 >>      too.
 >
 > What might cause these changes?

Adding/removing fringes, dividers, scroll bars, mode or header lines
to/from a window.  Usually, applications do not care for the total
size of a window - they want to know the size of the text area only.

 > (4) Run the buffer-local hook also when a window has not shown the
 >>      buffer the last time this hook was run.
 >
 > Good, so initial buffer display will be automatically handled as well.

It should also include the following idiosyncrasy: Suppose a user
saves away a window in a configuration in some register, kills it and
revives the window from that register a few hours later.  How should
running size change functions handle that case?  The window has
neither changed buffer nor size since the last time it was shown.  I
currently just run the buffer-local hook (since the window was not
there the last time the functions were run) but without further
notice.  If someone thinks that the application should get notified in
some sense about this fact, then please tell me how.

 >> So essentially you would have to rerun occur whenever the Man buffer
 >> is reformatted.
 >
 > It's too ad-hoc to find all Occur buffers created from the Man buffer,
 > and revert all of them.

Is it reverting Man buffers only that causes problems?  I suppose
(auto-)reversal is a wide-spread disease.

 >> Otherwise, I see only one way to handle this.  Before reformatting,
 >> store the context of each marker (in a bookmark-like or diff-like
 >> fashion) and restore the markers from that context.  The matching done
 >> in the restore step would have to identify and ignore "soft" changes
 >> of whitespace.
 >
 > This means additionally to finding all affected Occur buffers like above,
 > instead of reverting them, perform much more complex processing of
 > their markers.
 >
 > It seems a more practical solution is to limit the width of Man buffers
 > to at least 80 columns by default, so splitting such windows will not
 > resize their number of columns, so they won't be reverted and reformatted.

Why is it that we care so much about Man buffers and live with the
fact that, for example, our *info* buffers have rigid width?

martin

bug#32536: displayed width of man pages

[Juri Linkov]

> It should also include the following idiosyncrasy: Suppose a user
> saves away a window in a configuration in some register, kills it and
> revives the window from that register a few hours later.  How should
> running size change functions handle that case?  The window has
> neither changed buffer nor size since the last time it was shown.  I
> currently just run the buffer-local hook (since the window was not
> there the last time the functions were run) but without further
> notice.  If someone thinks that the application should get notified in
> some sense about this fact, then please tell me how.

Hard to tell, we need to see its consequences in practice.

>>> So essentially you would have to rerun occur whenever the Man buffer
>>> is reformatted.
>>
>> It's too ad-hoc to find all Occur buffers created from the Man buffer,
>> and revert all of them.
>
> Is it reverting Man buffers only that causes problems?

This problem is not only in Man buffers, but also in Occur buffers.

Maybe Occur should save points in addition to markers, so if after the
original buffer is reverted, and marker-position value becomes 1, then
use remembered point's value as a number, not invalidated marker.

This is called "graceful degradation".

Currently this is what is used in 'Man-update-manpage'.  You can see
how it saves 'old-pos' from (point), not from (point-marker).

> Why is it that we care so much about Man buffers and live with the
> fact that, for example, our *info* buffers have rigid width?

*Info* buffers are complied, but dynamically generated Man buffers
give us flexibility.

bug#32536: displayed width of man pages

[Juri Linkov]

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

Thanks Martin this is easy now to implement using new hooks.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Man-width.el.patch --]
[-- Type: text/x-diff, Size: 4731 bytes --]

diff --git a/lisp/man.el b/lisp/man.el
index defe992074..211d56f9dd 100644
--- a/lisp/man.el
+++ b/lisp/man.el
@@ -182,6 +182,34 @@ Man-width
                  (integer :tag "Fixed width" :value 65))
   :group 'man)
 
+(defcustom Man-width-min 40
+  "Minimum number of columns allowed for the width of manual pages.
+It defines the minimum width for the case when `Man-width' is customized
+to a dynamically calculated value depending on the frame/window width.
+If the width calculated for `Man-width' is smaller than the minimum width,
+it will be automatically enlarged to the width defined by this variable.
+If the calculated width is smaller than the minimum width, the value
+of this variable has no effect.
+When nil, there is no limit on minimum width."
+  :type '(choice (const :tag "No limit" nil)
+                 (integer :tag "Min width" :value 40))
+  :version "27.1"
+  :group 'man)
+
+(defcustom Man-width-max 80
+  "Maximum number of columns allowed for the width of manual pages.
+It defines the maximum width for the case when `Man-width' is customized
+to a dynamically calculated value depending on the frame/window width.
+If the width calculated for `Man-width' is larger than the maximum width,
+it will be automatically reduced to the width defined by this variable.
+If the calculated width is smaller than the maximum width, the value
+of this variable has no effect.
+When nil, there is no limit on maximum width."
+  :type '(choice (const :tag "No limit" nil)
+                 (integer :tag "Max width" :value 80))
+  :version "27.1"
+  :group 'man)
+
 (defcustom Man-frame-parameters nil
   "Frame parameter list for creating a new frame for a manual page."
   :type '(repeat (cons :format "%v"
@@ -1005,6 +1033,25 @@ man-follow
       (error "No item under point")
     (man man-args)))
 
+(defvar Man-columns nil)
+
+(defun Man-columns ()
+  (let ((width (cond
+                ((and (integerp Man-width) (> Man-width 0))
+                 Man-width)
+                (Man-width
+                 (let ((window (get-buffer-window nil t)))
+                   (frame-width (and window (window-frame window)))))
+                (t
+                 (window-width (get-buffer-window nil t))))))
+    (when (and (integerp Man-width-max)
+               (> Man-width-max 0))
+      (setq width (min width Man-width-max)))
+    (when (and (integerp Man-width-min)
+               (> Man-width-min 0))
+      (setq width (max width Man-width-min)))
+    width))
+
 (defmacro Man-start-calling (&rest body)
   "Start the man command in `body' after setting up the environment"
   `(let ((process-environment (copy-sequence process-environment))
@@ -1041,20 +1088,8 @@ Man-start-calling
 	      (not (or (getenv "MANWIDTH") (getenv "COLUMNS"))))
       ;; Since the page buffer is displayed beforehand,
       ;; we can select its window and get the window/frame width.
-      (setenv "COLUMNS" (number-to-string
-			 (cond
-			  ((and (integerp Man-width) (> Man-width 0))
-			   Man-width)
-			  (Man-width
-			   (if (window-live-p (get-buffer-window (current-buffer) t))
-			       (with-selected-window (get-buffer-window (current-buffer) t)
-				 (frame-width))
-			     (frame-width)))
-			  (t
-			   (if (window-live-p (get-buffer-window (current-buffer) t))
-			       (with-selected-window (get-buffer-window (current-buffer) t)
-				 (window-width))
-			     (window-width)))))))
+      (setq-local Man-columns (Man-columns))
+      (setenv "COLUMNS" (number-to-string Man-columns)))
     ;; Since man-db 2.4.3-1, man writes plain text with no escape
     ;; sequences when stdout is not a tty.	In 2.5.0, the following
     ;; env-var was added to allow control of this (see Debian Bug#340673).
@@ -1525,7 +1560,19 @@ Man-mode
   (set (make-local-variable 'outline-regexp) Man-heading-regexp)
   (set (make-local-variable 'outline-level) (lambda () 1))
   (set (make-local-variable 'bookmark-make-record-function)
-       'Man-bookmark-make-record))
+       'Man-bookmark-make-record)
+  (add-hook 'window-size-change-functions (debounce #'Man-window-change 1) nil t)
+  (add-hook 'window-state-change-functions (debounce #'Man-window-change 1) nil t)
+  (add-hook 'window-selection-change-functions (debounce #'Man-window-change 1) nil t))
+
+(defun Man-window-change (window)
+  (when (window-live-p window)
+    (with-selected-window window
+      (when (and (derived-mode-p 'Man-mode)
+                 (not (eq Man-columns (Man-columns))))
+        (let ((proc (get-buffer-process (current-buffer))))
+          (unless (and proc (not (eq (process-status proc) 'exit)))
+            (Man-update-manpage)))))))
 
 (defun Man-build-section-list ()
   "Build the list of manpage sections."

bug#32536: displayed width of man pages

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Date: Thu, 27 Dec 2018 01:36:05 +0200
> 
> Thanks Martin this is easy now to implement using new hooks.

Thanks for working on this.

> +(defcustom Man-width-min 40
> +  "Minimum number of columns allowed for the width of manual pages.
> +It defines the minimum width for the case when `Man-width' is customized
> +to a dynamically calculated value depending on the frame/window width.
> +If the width calculated for `Man-width' is smaller than the minimum width,
> +it will be automatically enlarged to the width defined by this variable.
> +If the calculated width is smaller than the minimum width, the value
> +of this variable has no effect.
> +When nil, there is no limit on minimum width."
> +  :type '(choice (const :tag "No limit" nil)
> +                 (integer :tag "Min width" :value 40))
> +  :version "27.1"
> +  :group 'man)
> +
> +(defcustom Man-width-max 80
> +  "Maximum number of columns allowed for the width of manual pages.
> +It defines the maximum width for the case when `Man-width' is customized
> +to a dynamically calculated value depending on the frame/window width.
> +If the width calculated for `Man-width' is larger than the maximum width,
> +it will be automatically reduced to the width defined by this variable.
> +If the calculated width is smaller than the maximum width, the value
> +of this variable has no effect.
> +When nil, there is no limit on maximum width."

I suspect some typo(s) in these doc strings, perhaps due to
copy/pasta, because the penultimate sentence of each of them makes no
sense to me, certainly when taken together with the other doc string.
If I'm wrong, and there's no error here, please explain what you
meant.

> +(defun Man-columns ()
> +  (let ((width (cond
> +                ((and (integerp Man-width) (> Man-width 0))
> +                 Man-width)
> +                (Man-width
> +                 (let ((window (get-buffer-window nil t)))
> +                   (frame-width (and window (window-frame window)))))
> +                (t
> +                 (window-width (get-buffer-window nil t))))))
> +    (when (and (integerp Man-width-max)
> +               (> Man-width-max 0))
> +      (setq width (min width Man-width-max)))
> +    (when (and (integerp Man-width-min)
> +               (> Man-width-min 0))
> +      (setq width (max width Man-width-min)))
> +    width))

Careful here: both window-width (why not use its official name, btw?)
and frame-width are insensitive to the size of the font used to
display the man page: they both measure in "canonical" column units.
Maybe this is not a significant problem (and I realize the old code
also worked like that), but perhaps the doc strings of the two new
options should mention this fact, lest the user will be surprised.

> +      (setenv "COLUMNS" (number-to-string Man-columns)))

Here, for example, the 'man' program will interpret COLUMNS at face
value, and will produce lines of that many characters; but if the size
of thefont used to display the man page is significantly different
from the frame's default font, those lines might be wider or narrower
than the window/frame.

Finally, I think this warrants a NEWS entry and perhaps also an update
for the manual.

bug#32536: displayed width of man pages

[Juri Linkov]

>> +(defcustom Man-width-min 40
>> [...]
>> +If the calculated width is smaller than the minimum width, the value
>> +of this variable has no effect.
>> [...]
>> +(defcustom Man-width-max 80
>> [...]
>> +If the calculated width is smaller than the maximum width, the value
>> +of this variable has no effect.
>
> I suspect some typo(s) in these doc strings, perhaps due to
> copy/pasta, because the penultimate sentence of each of them makes no
> sense to me, certainly when taken together with the other doc string.
> If I'm wrong, and there's no error here, please explain what you
> meant.

Yes, one of them is wrong.  The doc string of Man-width-min should be
changed to:

  If the calculated width is larger than the minimum width, the value
  of this variable has no effect.

>> +(defun Man-columns ()
>> +  (let ((width (cond
>> +                ((and (integerp Man-width) (> Man-width 0))
>> +                 Man-width)
>> +                (Man-width
>> +                 (let ((window (get-buffer-window nil t)))
>> +                   (frame-width (and window (window-frame window)))))
>> +                (t
>> +                 (window-width (get-buffer-window nil t))))))
>> +    (when (and (integerp Man-width-max)
>> +               (> Man-width-max 0))
>> +      (setq width (min width Man-width-max)))
>> +    (when (and (integerp Man-width-min)
>> +               (> Man-width-min 0))
>> +      (setq width (max width Man-width-min)))
>> +    width))
>
> Careful here: both window-width (why not use its official name, btw?)

Sorry, I don't understand what is the official name?

> and frame-width are insensitive to the size of the font used to
> display the man page: they both measure in "canonical" column units.
> Maybe this is not a significant problem (and I realize the old code
> also worked like that), but perhaps the doc strings of the two new
> options should mention this fact, lest the user will be surprised.
>
>> +      (setenv "COLUMNS" (number-to-string Man-columns)))
>
> Here, for example, the 'man' program will interpret COLUMNS at face
> value, and will produce lines of that many characters; but if the size
> of thefont used to display the man page is significantly different
> from the frame's default font, those lines might be wider or narrower
> than the window/frame.

It seems this calculation works only for monospace fonts.

> Finally, I think this warrants a NEWS entry and perhaps also an update
> for the manual.

Will do after the final patch.

bug#32536: displayed width of man pages

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: 32536@debbugs.gnu.org
> Date: Thu, 27 Dec 2018 22:54:44 +0200
> 
> >> +(defcustom Man-width-min 40
> >> [...]
> >> +If the calculated width is smaller than the minimum width, the value
> >> +of this variable has no effect.
> >> [...]
> >> +(defcustom Man-width-max 80
> >> [...]
> >> +If the calculated width is smaller than the maximum width, the value
> >> +of this variable has no effect.
> >
> > I suspect some typo(s) in these doc strings, perhaps due to
> > copy/pasta, because the penultimate sentence of each of them makes no
> > sense to me, certainly when taken together with the other doc string.
> > If I'm wrong, and there's no error here, please explain what you
> > meant.
> 
> Yes, one of them is wrong.  The doc string of Man-width-min should be
> changed to:
> 
>   If the calculated width is larger than the minimum width, the value
>   of this variable has no effect.

OK, but I'm still not getting something.  Here's the corrected doc
string:

    "Minimum number of columns allowed for the width of manual pages.
  It defines the minimum width for the case when `Man-width' is customized
  to a dynamically calculated value depending on the frame/window width.
  If the width calculated for `Man-width' is smaller than the minimum width,
  it will be automatically enlarged to the width defined by this variable.
  If the calculated width is larger than the minimum width, the value
  of this variable has no effect.

If the last 2 sentences want to say that the limit is from below, then
they say this in a complicated and confusing way.  How about removing
the last sentence?

> > Careful here: both window-width (why not use its official name, btw?)
> 
> Sorry, I don't understand what is the official name?

window-width is an alias, the real function is window-body-width.

> >> +      (setenv "COLUMNS" (number-to-string Man-columns)))
> >
> > Here, for example, the 'man' program will interpret COLUMNS at face
> > value, and will produce lines of that many characters; but if the size
> > of thefont used to display the man page is significantly different
> > from the frame's default font, those lines might be wider or narrower
> > than the window/frame.
> 
> It seems this calculation works only for monospace fonts.

Like I said: this has some subtle aspects, and I suggest saying that
in the doc string in some way.

> > Finally, I think this warrants a NEWS entry and perhaps also an update
> > for the manual.
> 
> Will do after the final patch.

Thanks.

bug#32536: displayed width of man pages

[Juri Linkov]

tags 32536 fixed
close 32536 27.0.50
quit

This is now pushed to master with NEWS in 7e387c9e52.