man.el

man.el

[Richard Stallman]

Regarding the change below, why is the current window's width more
likely to be correct than the frame's width?  (Neither one is
guaranteed to be right.)


To: bug-gnu-emacs@gnu.org
From: Juri Linkov <juri@jurta.org>
Organization: JURTA
In-Reply-To: <E1Ak5zD-00005U-VQ@fencepost.gnu.org> (Richard Stallman's
	message of "23 Jan 2004 13:24:55 -0500")
Date: Thu, 18 Feb 2004 23:02:03 +0200
Subject: Re: Emacs inventing system documentation
Sender: bug-gnu-emacs-bounces+rms=gnu.org@gnu.org

Richard Stallman <rms@gnu.org> writes:
> I thought Reuben's message was meant as a humorous
> way to report that the term "made up" was not clear.
> So I will change it to "formatted for display".

The second message in the same function could be changed as well.  The
following patch also fixes one bug (using `frame-width' instead of
`window-width' causes too long lines when window is split
horizontally), and sets `outline-regexp'.

2004-02-18  Juri Linkov  <juri@jurta.org>

	* man.el (Man-fontify-manpage): Clean up message.
	(Man-mode): Set outline-regexp.
	(Man-getpage-in-background): Use window-width instead of
	frame-width.

	* woman.el (woman-decode-region): Use window-width instead of
	frame-width.

Index: emacs/lisp/man.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/man.el,v
retrieving revision 1.131
diff -c -r1.131 man.el
*** emacs/lisp/man.el	24 Jan 2004 21:52:12 -0000	1.131
--- emacs/lisp/man.el	18 Feb 2004 23:43:34 -0000
***************
*** 679,685 ****
  	      ;; This isn't strictly correct, since we don't know how
  	      ;; the page will actually be displayed, but it seems
  	      ;; reasonable.
! 	      (setenv "COLUMNS" (number-to-string (frame-width)))))
  	(setenv "GROFF_NO_SGR" "1")
  	(if (fboundp 'start-process)
  	    (set-process-sentinel
--- 679,685 ----
  	      ;; This isn't strictly correct, since we don't know how
  	      ;; the page will actually be displayed, but it seems
  	      ;; reasonable.
! 	      (setenv "COLUMNS" (number-to-string (window-width)))))
  	(setenv "GROFF_NO_SGR" "1")
  	(if (fboundp 'start-process)
  	    (set-process-sentinel
***************
*** 757,763 ****
    "Convert overstriking and underlining to the correct fonts.
  Same for the ANSI bold and normal escape sequences."
    (interactive)
!   (message "Please wait: making up the %s man page..." Man-arguments)
    (goto-char (point-min))
    (while (search-forward "\e[1m" nil t)
      (delete-backward-char 4)
--- 757,763 ----
    "Convert overstriking and underlining to the correct fonts.
  Same for the ANSI bold and normal escape sequences."
    (interactive)
!   (message "Please wait: formatting the %s man page..." Man-arguments)
    (goto-char (point-min))
    (while (search-forward "\e[1m" nil t)
      (delete-backward-char 4)
***************
*** 971,976 ****
--- 971,977 ----
    (auto-fill-mode -1)
    (use-local-map Man-mode-map)
    (set-syntax-table man-mode-syntax-table)
+   (set (make-local-variable 'outline-regexp) Man-heading-regexp)
    (Man-build-page-list)
    (Man-strip-page-headers)
    (Man-unindent)
Index: emacs/lisp/woman.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/woman.el,v
retrieving revision 1.18
diff -c -r1.18 woman.el
*** emacs/lisp/woman.el	22 Sep 2003 15:15:26 -0000	1.18
--- emacs/lisp/woman.el	18 Feb 2004 23:43:37 -0000
***************
*** 2204,2210 ****
      ;; Based loosely on a suggestion by Theodore Jump:
      (if (or woman-fill-frame
  	    (not (and (integerp woman-fill-column) (> woman-fill-column 0))))
! 	(setq woman-fill-column (- (frame-width) woman-default-indent)))
  
      ;; Check for preprocessor requests:
      (goto-char from)
--- 2204,2210 ----
      ;; Based loosely on a suggestion by Theodore Jump:
      (if (or woman-fill-frame
  	    (not (and (integerp woman-fill-column) (> woman-fill-column 0))))
! 	(setq woman-fill-column (- (window-width) woman-default-indent)))
  
      ;; Check for preprocessor requests:
      (goto-char from)

-- 
http://www.jurta.org/emacs/



_______________________________________________
Bug-gnu-emacs mailing list
Bug-gnu-emacs@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-gnu-emacs

Re: man.el

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

> Regarding the change below, why is the current window's width more
> likely to be correct than the frame's width?  (Neither one is
> guaranteed to be right.)

If the frame is split horisontally, window-width is a better guess
than frame-width (and if not split horisontally, it doesn't matter).

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: man.el

[Kevin Rodgers]

Richard Stallman wrote:
 > Regarding the change below, why is the current window's width more
 > likely to be correct than the frame's width?  (Neither one is
 > guaranteed to be right.)

If you try to guess based on the value of Man-notify-method (which
defaults to friendly), it looks like window-width is at least as likely
to be correct (disregarding special-display-regexps etc.):

(defun Man-window-width ()
   "Return the expected width of the window used to display Un*x manual pages.
See `Man-notify-method'."
   ;; see Man-notify-when-ready:
   (cond ((eq Man-notify-method 'newframe) ; make-frame
	 (or (assq 'width Man-frame-parameters)
	     (assq 'width default-frame-alist)
	     (frame-width)))
	((eq Man-notify-method 'pushy)	; switch-to-buffer
	 (window-width))
	((eq Man-notify-method 'bully)	; pop-to-buffer, delete-other-windows
	 (frame-width))
	((and (eq Man-notify-method 'aggressive) ; pop-to-buffer
	      pop-up-frames)
	 (or (assq 'width pop-up-frame-alist)
	     (assq 'width default-frame-alist)
	     (frame-width)))
	((memq Man-notify-method '(aggressive friendly)) ; display-buffer
	 ;; here we ignore special-display-regexps etc.
	 (window-width))
	((memq Man-notify-method '(polite quiet meek)) ; ?
	 ;; depends on how the user chooses to display the buffer, e.g
	 ;; C-x b, C-x 4 b, C-x 5 b
	 (window-width))
	(t				; same as meek
	 (window-width))))

-- 
Kevin Rodgers

Re: man.el

[Alex Schroeder]

Richard Stallman <rms@gnu.org> writes:

> Regarding the change below, why is the current window's width more
> likely to be correct than the frame's width?  (Neither one is
> guaranteed to be right.)

When you split-window-horizontally using C-x 3 and intend to keep
working that way, you'll prefer window-width to frame-width.

Alex.
-- 
.O.  http://www.emacswiki.org/alex/
..O  Schroeder's fourth law:
OOO  None of your friends and coworkers share your taste in music.

Re: man.el

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
> Regarding the change below, why is the current window's width more
> likely to be correct than the frame's width?  (Neither one is
> guaranteed to be right.)

The window's width is more correct than the frame's width when the
frame is split horizontally, the method of notification is not `bully'
or `newframe', and user don't change the window configuration after
invoking man in the background.  Since man formats pages
asyncronically, it should know the number of columns before its
invocation.  But for the moment when man page is ready the user can
change the window configuration (split window, or delete other
windows, or change frame's or window's widths).  This means that
neither window's width nor frame's width is correct, and restoring
the original window configuration before displaying the man page
may be not desirable for the user.

So instead of arguing which of the incorrect methods is more correct,
it could be left completely to user's discretion.  A new defcustom
variable Man-width can have an integer value for explicit number of
columns, or a special value for either frame-width or window-width.
Along with the Man-notify-method option the user can use the Man-width
to specify preferences for displaying man pages.

Index: emacs/lisp/man.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/man.el,v
retrieving revision 1.132
diff -c -r1.132 man.el
*** emacs/lisp/man.el	16 Feb 2004 18:20:31 -0000	1.132
--- emacs/lisp/man.el	21 Feb 2004 01:57:20 -0000
***************
*** 175,180 ****
--- 175,191 ----
  		(const polite) (const quiet) (const meek))
    :group 'man)
  
+ (defcustom Man-width nil
+   "*Number of columns for which manual pages should be formatted.
+ If nil, the width of the frame selected at the moment of man
+ invocation is used.  If non-nil, the width of the window selected
+ at the moment of man invocation is used.  The value also can be a
+ positive integer."
+   :type '(choice (const :tag "Frame width" nil)
+                  (const :tag "Window width" t)
+                  (integer :tag "Specific width" :value 65))
+   :group 'man)
+ 
  (defcustom Man-frame-parameters nil
    "*Frame parameter list for creating a new frame for a manual page."
    :type 'sexp
***************
*** 679,685 ****
  	      ;; This isn't strictly correct, since we don't know how
  	      ;; the page will actually be displayed, but it seems
  	      ;; reasonable.
! 	      (setenv "COLUMNS" (number-to-string (frame-width)))))
  	(setenv "GROFF_NO_SGR" "1")
  	(if (fboundp 'start-process)
  	    (set-process-sentinel
--- 690,701 ----
  	      ;; This isn't strictly correct, since we don't know how
  	      ;; the page will actually be displayed, but it seems
  	      ;; reasonable.
! 	      (setenv "COLUMNS" (number-to-string
! 				 (cond
! 				  ((and (integerp Man-width) (> Man-width 0))
! 				   Man-width)
! 				  (Man-width (window-width))
! 				  ((frame-width)))))))
  	(setenv "GROFF_NO_SGR" "1")
  	(if (fboundp 'start-process)
  	    (set-process-sentinel
***************
*** 757,763 ****
    "Convert overstriking and underlining to the correct fonts.
  Same for the ANSI bold and normal escape sequences."
    (interactive)
!   (message "Please wait: making up the %s man page..." Man-arguments)
    (goto-char (point-min))
    (while (search-forward "\e[1m" nil t)
      (delete-backward-char 4)
--- 773,779 ----
    "Convert overstriking and underlining to the correct fonts.
  Same for the ANSI bold and normal escape sequences."
    (interactive)
!   (message "Please wait: formatting the %s man page..." Man-arguments)
    (goto-char (point-min))
    (while (search-forward "\e[1m" nil t)
      (delete-backward-char 4)
***************
*** 976,981 ****
--- 992,1000 ----
    (auto-fill-mode -1)
    (use-local-map Man-mode-map)
    (set-syntax-table man-mode-syntax-table)
+   (setq imenu-generic-expression (list (list nil Man-heading-regexp 0)))
+   (set (make-local-variable 'outline-regexp) Man-heading-regexp)
+   (set (make-local-variable 'outline-level) (lambda () 1))
    (Man-build-page-list)
    (Man-strip-page-headers)
    (Man-unindent)

The patch for woman.el follows below.  Note that in the woman.el for
the analogous purpose the frame-window can be changed to window-width
unconditionally because woman displays man pages in the same window
where it was invoked.

Index: emacs/lisp/woman.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/woman.el,v
retrieving revision 1.18
diff -c -r1.18 woman.el
*** emacs/lisp/woman.el	22 Sep 2003 15:15:26 -0000	1.18
--- emacs/lisp/woman.el	21 Feb 2004 01:57:23 -0000
***************
*** 807,813 ****
  
  (defcustom woman-fill-frame nil
    ;; Based loosely on a suggestion by Theodore Jump:
!   "*If non-nil then most of the frame width is used."
    :type 'boolean
    :group 'woman-formatting)
  
--- 807,813 ----
  
  (defcustom woman-fill-frame nil
    ;; Based loosely on a suggestion by Theodore Jump:
!   "*If non-nil then most of the window width is used."
    :type 'boolean
    :group 'woman-formatting)
  
***************
*** 2204,2210 ****
      ;; Based loosely on a suggestion by Theodore Jump:
      (if (or woman-fill-frame
  	    (not (and (integerp woman-fill-column) (> woman-fill-column 0))))
! 	(setq woman-fill-column (- (frame-width) woman-default-indent)))
  
      ;; Check for preprocessor requests:
      (goto-char from)
--- 2204,2210 ----
      ;; Based loosely on a suggestion by Theodore Jump:
      (if (or woman-fill-frame
  	    (not (and (integerp woman-fill-column) (> woman-fill-column 0))))
! 	(setq woman-fill-column (- (window-width) woman-default-indent)))
  
      ;; Check for preprocessor requests:
      (goto-char from)

-- 
http://www.jurta.org/emacs/

Re: man.el

[Eli Zaretskii]

> From: Alex Schroeder <alex@emacswiki.org>
> Date: Sat, 21 Feb 2004 01:49:05 +0100
> 
> When you split-window-horizontally using C-x 3 and intend to keep
> working that way, you'll prefer window-width to frame-width.

I don't think it's quite that simple.  The correct choice depends on
where will Emacs pop the window in which it displays the formatted man
page.  Since window popping follows some quite comlpex logic, it could
be wrong to use window-width in the case you cite.

I think we need some machinery to allow us to know in advance where
the window will pop.  Perhaps we should create the window before
running the `man' command, or maybe decide in advance where to pop the
window and force Emacs to pop it exactly where we tell it.

Re: man.el

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sat, 21 Feb 2004 03:04:12 +0200
> 
> So instead of arguing which of the incorrect methods is more correct,
> it could be left completely to user's discretion.

FWIW, I don't like this kind of solutions.  Emacs should not delegate
to the user the need to resolve its inability to DTRT.  User
customization is for selecting from several similarly correct
behaviors, not for fixing misfeatures.

So I think we should find a way for Emacs to behave correctly in this
situation.

Re: man.el

[Juri Linkov]

"Eli Zaretskii" <eliz@elta.co.il> writes:
> I don't think it's quite that simple.  The correct choice depends on
> where will Emacs pop the window in which it displays the formatted man
> page.  Since window popping follows some quite comlpex logic, it could
> be wrong to use window-width in the case you cite.
>
> I think we need some machinery to allow us to know in advance where
> the window will pop.  Perhaps we should create the window before
> running the `man' command, or maybe decide in advance where to pop the
> window and force Emacs to pop it exactly where we tell it.

This looks like a new notification method.  While it might be good
enough to make it sometime the default method, it will not solve
the problems of existing notification methods, which should retain
their current unpredictable (wrt window configuration) behavior
for backwards compatibility.  So I don't see a solution better than
adding a new user option to define the number of columns, because it
mostly depends on user's actions between invoking the man page
formatting and displaying the man buffer.  And one useful property of
this option also is that the user unsatisfied with guesses made by
frame-width or window-width can set a fixed integer value.

-- 
http://www.jurta.org/emacs/

Re: man.el

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 22 Feb 2004 02:32:56 +0200
> 
> This looks like a new notification method.

I'm not sure, but if that's what we want, let's leave the current
notification methods unchanged, for the same reason of backwards
compatibility that you mentioned.

Re: man.el

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
> I'm not sure, but if that's what we want, let's leave the current
> notification methods unchanged, for the same reason of backwards
> compatibility that you mentioned.

Yes, I think we shouldn't change the current notification methods.
Anyhow, all I wanted was to fix only one problem where invoking man on
horizontally split windows causes truncated lines.  Currently there is
no way to redefine the number of columns since the frame-width is
hard-coded in the Man-getpage-in-background function.  Adding a new
option will allow the user to specify the number of columns she wants.

-- 
http://www.jurta.org/emacs/

Re: man.el

[Richard Stallman]

    FWIW, I don't like this kind of solutions.  Emacs should not delegate
    to the user the need to resolve its inability to DTRT.  User
    customization is for selecting from several similarly correct
    behaviors, not for fixing misfeatures.

I agree with that principle.  If it is possible to make Emacs DTRT in
all cases, we should not propose to cop out by "asking the user to
decide".

Re: man.el

[Juri Linkov]

I looked at other functions that use `frame-window' which produces too
long lines in side-by-side windows, and replaced it with `window-width'.

BTW, one of the fixes was made in the file abbrevlist.el with a lone
function `list-one-abbrev-table' which is not used anywhere in Emacs.
I'm not sure if this function should be removed because it might be
used in Emacs Lisp programs outside Emacs and also it looks like
a useful function, but perhaps this functions should be moved
to the abbrev.el file and the abbrevlist.el file be deleted.

Index: emacs/lisp/abbrevlist.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/abbrevlist.el,v
retrieving revision 1.11
diff -c -r1.11 abbrevlist.el
*** emacs/lisp/abbrevlist.el	1 Sep 2003 15:45:04 -0000	1.11
--- emacs/lisp/abbrevlist.el	18 Mar 2004 01:57:40 -0000
***************
*** 39,45 ****
  	  abbrev-table)
  	(setq abbrev-list (sort abbrev-list 'string-lessp))
  	(while abbrev-list
! 	  (if (> (+ first-column 40) (frame-width))
  	      (progn
  		(insert "\n")
  		(setq first-column 0)))
--- 39,45 ----
  	  abbrev-table)
  	(setq abbrev-list (sort abbrev-list 'string-lessp))
  	(while abbrev-list
! 	  (if (> (+ first-column 40) (window-width))
  	      (progn
  		(insert "\n")
  		(setq first-column 0)))
Index: emacs/lisp/descr-text.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/descr-text.el,v
retrieving revision 1.17
diff -c -r1.17 descr-text.el
*** emacs/lisp/descr-text.el	9 Nov 2003 19:38:32 -0000	1.17
--- emacs/lisp/descr-text.el	18 Mar 2004 01:57:40 -0000
***************
*** 589,595 ****
  		(when (>= (+ (current-column)
  			     (or (string-match "\n" clm)
  				 (string-width clm)) 1)
! 			  (frame-width))
  		  (insert "\n")
  		  (indent-to (1+ max-width)))
  		(insert " " clm))
--- 589,595 ----
  		(when (>= (+ (current-column)
  			     (or (string-match "\n" clm)
  				 (string-width clm)) 1)
! 			  (window-width))
  		  (insert "\n")
  		  (indent-to (1+ max-width)))
  		(insert " " clm))
Index: emacs/lisp/international/mule-diag.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/international/mule-diag.el,v
retrieving revision 1.92
diff -c -r1.92 mule-diag.el
*** emacs/lisp/international/mule-diag.el	7 Oct 2003 06:45:46 -0000	1.92
--- emacs/lisp/international/mule-diag.el	18 Mar 2004 01:57:41 -0000
***************
*** 845,851 ****
  		 (setq codings (cons x codings))))
  	   (get (car categories) 'coding-systems))
  	  (if codings
! 	      (let ((max-col (frame-width))
  		    pos)
  		(princ (format "\
    The following are decoded correctly but recognized as %s:\n   "
--- 845,851 ----
  		 (setq codings (cons x codings))))
  	   (get (car categories) 'coding-systems))
  	  (if codings
! 	      (let ((max-col (window-width))
  		    pos)
  		(princ (format "\
    The following are decoded correctly but recognized as %s:\n   "
Index: emacs/lisp/international/quail.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/international/quail.el,v
retrieving revision 1.132
diff -c -r1.132 quail.el
*** emacs/lisp/international/quail.el	10 Nov 2003 04:30:46 -0000	1.132
--- emacs/lisp/international/quail.el	18 Mar 2004 01:57:43 -0000
***************
*** 2289,2296 ****
  			  (or (> (length x) (length y))
  			      (and (= (length x) (length y))
  				   (not (string< x y))))))))
!   (let ((frame-width (frame-width (window-frame (get-buffer-window
! 						 (current-buffer) 'visible))))
  	(single-key-width 3)
  	(single-trans-width 4)
  	(multiple-key-width 3)
--- 2289,2296 ----
  			  (or (> (length x) (length y))
  			      (and (= (length x) (length y))
  				   (not (string< x y))))))))
!   (let ((window-width (window-width (get-buffer-window
!                                      (current-buffer) 'visible)))
  	(single-key-width 3)
  	(single-trans-width 4)
  	(multiple-key-width 3)
***************
*** 2319,2325 ****
  	  (setq multiple-key-width width)))
      (when single-list
        (setq col-width (+ single-key-width 1 single-trans-width 1)
! 	    cols (/ frame-width col-width)
  	    rows (/ (length single-list) cols))
        (if (> (% (length single-list) cols) 0)
  	  (setq rows (1+ rows)))
--- 2319,2325 ----
  	  (setq multiple-key-width width)))
      (when single-list
        (setq col-width (+ single-key-width 1 single-trans-width 1)
! 	    cols (/ window-width col-width)
  	    rows (/ (length single-list) cols))
        (if (> (% (length single-list) cols) 0)
  	  (setq rows (1+ rows)))
***************
*** 2365,2371 ****
  		   (lambda (x)
  		     (let ((width (if (integerp x) (char-width x)
  				    (string-width x))))
! 		       (when (> (+ (current-column) 1 width) frame-width)
  			 (insert "\n")
  			 (indent-to multiple-key-width))
  		       (insert " " x))))
--- 2365,2371 ----
  		   (lambda (x)
  		     (let ((width (if (integerp x) (char-width x)
  				    (string-width x))))
! 		       (when (> (+ (current-column) 1 width) window-width)
  			 (insert "\n")
  			 (indent-to multiple-key-width))
  		       (insert " " x))))
***************
*** 2402,2408 ****
  	(with-current-buffer standard-output
  	  (setq quail-current-package package-def))))
      ;; Then, insert text in the help buffer while paying attention to
!     ;; the width of the frame in which the buffer displayed.
      (with-current-buffer (help-buffer)
        (setq buffer-read-only nil)
        (insert "Input method: " (quail-name)
--- 2402,2408 ----
  	(with-current-buffer standard-output
  	  (setq quail-current-package package-def))))
      ;; Then, insert text in the help buffer while paying attention to
!     ;; the width of the window in which the buffer displayed.
      (with-current-buffer (help-buffer)
        (setq buffer-read-only nil)
        (insert "Input method: " (quail-name)

-- 
Juri Linkov
http://www.jurta.org/emacs/