[Patch] reformat man buffer on the fly for man.el

[Patch] reformat man buffer on the fly for man.el

[Darren Hoo]

Hi All,

As man works by invoking the man command background, it is not easy to
figure out how wide the buffer is going to be displayed, so the width
guess is not always correct, eg, when there's only one window on the
current frame and man is first run, while it pops to the man buffer by
split-window-right, the lines in the man buffer is longer than the width
of the new window. 

This is not convenient when reading the man page side by side or when
the window is resized. Thus I added function Man-update-manpage, any
comments on the following patch?


--8<---------------cut here---------------start------------->8---
diff --git a/lisp/man.el b/lisp/man.el
index 5619803..bceba6f 100644
--- a/lisp/man.el
+++ b/lisp/man.el
@@ -441,6 +441,7 @@ Otherwise, the value is whatever the function
     (define-key map "s"    'Man-goto-see-also-section)
     (define-key map "k"    'Man-kill)
     (define-key map "q"    'Man-quit)
+    (define-key map "u"    'Man-update-manpage)
     (define-key map "m"    'man)
     ;; Not all the man references get buttons currently.  The text in the
     ;; manual page can contain references to other man pages
@@ -971,6 +972,54 @@ names or descriptions.  The pattern argument is usually an
       (error "No item under point")
     (man man-args)))
 
+(defmacro Man-start-calling (&rest body)
+  "Start the man command in `body' after setting up the environment"
+  `(let ((process-environment (copy-sequence process-environment))
+	;; The following is so Awk script gets \n intact
+	;; But don't prevent decoding of the outside.
+	(coding-system-for-write 'raw-text-unix)
+	;; We must decode the output by a coding system that the
+	;; system's locale suggests in multibyte mode.
+	(coding-system-for-read
+	 (if (default-value 'enable-multibyte-characters)
+	     locale-coding-system 'raw-text-unix))
+	;; Avoid possible error by using a directory that always exists.
+	(default-directory
+	  (if (and (file-directory-p default-directory)
+		   (not (find-file-name-handler default-directory
+						'file-directory-p)))
+	      default-directory
+	    "/")))
+    ;; Prevent any attempt to use display terminal fanciness.
+    (setenv "TERM" "dumb")
+    ;; In Debian Woody, at least, we get overlong lines under X
+    ;; unless COLUMNS or MANWIDTH is set.  This isn't a problem on
+    ;; a tty.  man(1) says:
+    ;;        MANWIDTH
+    ;;               If $MANWIDTH is set, its value is used as the  line
+    ;;               length  for which manual pages should be formatted.
+    ;;               If it is not set, manual pages  will  be  formatted
+    ;;               with  a line length appropriate to the current ter-
+    ;;               minal (using an ioctl(2) if available, the value of
+    ;;               $COLUMNS,  or falling back to 80 characters if nei-
+    ;;               ther is available).
+    (when (or window-system
+	      (not (or (getenv "MANWIDTH") (getenv "COLUMNS"))))
+      ;; 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 (frame-width))
+			  ((window-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).
+    (setenv "MAN_KEEP_FORMATTING" "1")
+    ,@body))
+
 (defun Man-getpage-in-background (topic)
   "Use TOPIC to build and fire off the manpage and cleaning command.
 Return the buffer in which the manpage will appear."
@@ -986,51 +1035,8 @@ Return the buffer in which the manpage will appear."
 	(setq buffer-undo-list t)
 	(setq Man-original-frame (selected-frame))
 	(setq Man-arguments man-args))
-      (let ((process-environment (copy-sequence process-environment))
-	    ;; The following is so Awk script gets \n intact
-	    ;; But don't prevent decoding of the outside.
-	    (coding-system-for-write 'raw-text-unix)
-	    ;; We must decode the output by a coding system that the
-	    ;; system's locale suggests in multibyte mode.
-	    (coding-system-for-read
-	     (if (default-value 'enable-multibyte-characters)
-		 locale-coding-system 'raw-text-unix))
-	    ;; Avoid possible error by using a directory that always exists.
-	    (default-directory
-	      (if (and (file-directory-p default-directory)
-		       (not (find-file-name-handler default-directory
-						    'file-directory-p)))
-		  default-directory
-		"/")))
-	;; Prevent any attempt to use display terminal fanciness.
-	(setenv "TERM" "dumb")
-	;; In Debian Woody, at least, we get overlong lines under X
-	;; unless COLUMNS or MANWIDTH is set.  This isn't a problem on
-	;; a tty.  man(1) says:
-	;;        MANWIDTH
-	;;               If $MANWIDTH is set, its value is used as the  line
-	;;               length  for which manual pages should be formatted.
-	;;               If it is not set, manual pages  will  be  formatted
-	;;               with  a line length appropriate to the current ter-
-	;;               minal (using an ioctl(2) if available, the value of
-	;;               $COLUMNS,  or falling back to 80 characters if nei-
-	;;               ther is available).
-	(when (or window-system
-                  (not (or (getenv "MANWIDTH") (getenv "COLUMNS"))))
-	  ;; 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 (frame-width))
-			      ((window-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).
-	(setenv "MAN_KEEP_FORMATTING" "1")
-	(if (fboundp 'start-process)
+      (Man-start-calling
+       (if (fboundp 'start-process)
 	    (set-process-sentinel
 	     (start-process manual-program buffer
 			    (if (memq system-type '(cygwin windows-nt))
@@ -1052,7 +1058,34 @@ Return the buffer in which the manpage will appear."
 				   exit-status)))
 		(setq msg exit-status))
 	    (Man-bgproc-sentinel bufname msg)))))
-    buffer))
+      buffer))
+
+(defun Man-update-manpage ()
+  "Reformat current manpage by calling the man command again synchronously."
+  (interactive)
+  (when (eq Man-arguments nil)
+    ;;this shouldn't happen unless it is not in a Man buffer."
+    (error "Man-arguments not initialized"))
+  (let ((old-pos (point))
+	(text (current-word))
+	(old-size (buffer-size)) 
+	(inhibit-read-only t)
+	(buffer-read-only nil))
+     (erase-buffer)
+     (Man-start-calling
+      (call-process shell-file-name nil (list (current-buffer) nil) nil
+		    shell-command-switch
+		    (format (Man-build-man-command) Man-arguments)))
+     (if Man-fontify-manpage-flag
+	 (Man-fontify-manpage)
+       (Man-cleanup-manpage))
+     (goto-char old-pos)
+     ;;restore the point, not strictly right.
+     (unless (or (eq text nil) (= old-size (buffer-size)))
+       (let ((case-fold-search nil))
+	 (if (> old-size (buffer-size))
+	     (search-backward text nil t))
+	 (search-forward text nil t)))))
 
 (defun Man-notify-when-ready (man-buffer)
   "Notify the user when MAN-BUFFER is ready.
--8<---------------cut here---------------end--------------->8---

Re: [Patch] reformat man buffer on the fly for man.el

[Stefan Monnier]

> As man works by invoking the man command background, it is not easy to
> figure out how wide the buffer is going to be displayed, so the width
> guess is not always correct,

I think the right fix for that is to display the buffer before it
gets filled, so you don't need any new command like
"Man-update-manpage".  It will also solve the problem that if generating
the manpage takes a long time, it ends up popping up in your face
unexpectedly (since you've lost patience in the mean time and moved on
to something else).


        Stefan

Re: [Patch] reformat man buffer on the fly for man.el

[Darren Hoo]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I think the right fix for that is to display the buffer before it gets
> filled

hmm, that's an option, but my last attempt was to add new function for
newcomers instead of changing the way how man.el works. I suppose your
suggestion needs more changes and might break things for "old" people who
have customized their Man-notify-method.  
  
> so you don't need any new command like  "Man-update-manpage".  

I think I still need this. There's one thing I like Man more than
Info is that manpage can be re-formatted and it is easier for me to 
read large blocks of text with long lines which makes the text less 
cluttered.

When I lookup manpage occassionally I prefer reading some of it with
windows side by side. But when I find myself need to concentrate on one 
looked-up manpage, I would like to C-x 1 then reformat the Man buffer 
and read it from begin to end.

> It will also solve the problem that if generating
> the manpage takes a long time, it ends up popping up in your face
> unexpectedly (since you've lost patience in the mean time and moved on
> to something else).

Generating the manpage is so fast for me that this senario has never
occurred to me. Actually I find it unneccessary to call the command
asynchronouslly for me because I do not have to wait at all.


One question about the following code:

  (if (fboundp 'start-process)
     (start-process ...)
    (call-process ...))

Is it due to once in Emacs history when there is no `start-process' but
only `call-process', Can you fill me in?
 

Re: [Patch] reformat man buffer on the fly for man.el

[Stefan Monnier]

> When I lookup manpage occasionally I prefer reading some of it with
> windows side by side. cBut when I find myself need to concentrate on one
> looked-up manpage, I would like to C-x 1 then reformat the Man buffer
> and read it from begin to end.

That makes sense, indeed.

>> It will also solve the problem that if generating the manpage takes
>> a long time, it ends up popping up in your face unexpectedly (since
>> you've lost patience in the mean time and moved on to something
>> else).
> Generating the manpage is so fast for me that this senario has never
> occurred to me.

Yes, usually it's very quick.  But when it's not (e.g. manpage on
a remote server that's temporarily down), it hurts.

As you say, when it's very quick, there's no point running the process
asynchronously, and neither is it useful to only display the buffer
after the rendering is done.

> One question about the following code:

>   (if (fboundp 'start-process)
>      (start-process ...)
>     (call-process ...))

> Is it due to once in Emacs history when there is no `start-process' but
> only `call-process', Can you fill me in?

The FreeDOS build of Emacs doesn't support start-process (because
FreeDOS doesn't support multiprocessing).


        Stefan

Re: [Patch] reformat man buffer on the fly for man.el

[Xue Fuqiao]

On Wed, Oct 30, 2013 at 8:27 PM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:
>> One question about the following code:
>
>>   (if (fboundp 'start-process)
>>      (start-process ...)
>>     (call-process ...))
>
>> Is it due to once in Emacs history when there is no `start-process' but
>> only `call-process', Can you fill me in?
>
> The FreeDOS build of Emacs doesn't support start-process (because
> FreeDOS doesn't support multiprocessing).

That's true.  Maybe we should add some comments here or to (info
"(elisp) Asynchronous Processes") ?

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: [Patch] reformat man buffer on the fly for man.el

[Glenn Morris]

Xue Fuqiao wrote:

>> The FreeDOS build of Emacs doesn't support start-process (because
>> FreeDOS doesn't support multiprocessing).

> That's true.  Maybe we should add some comments here or to (info
> "(elisp) Asynchronous Processes") ?

It's already mentioned in the MS-DOS section of the Emacs manual.
(Unlike the word "FreeDOS", which appears nowhere in Emacs, BTW.)

No need to mention it outside of its dedicated section, IMO.

Re: [Patch] reformat man buffer on the fly for man.el

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Thu, 31 Oct 2013 12:28:03 -0400
> Cc: Darren Hoo <darren.hoo@gmail.com>,
> 	Stefan Monnier <monnier@iro.umontreal.ca>,
> 	emacs-devel <emacs-devel@gnu.org>
> 
> Xue Fuqiao wrote:
> 
> >> The FreeDOS build of Emacs doesn't support start-process (because
> >> FreeDOS doesn't support multiprocessing).
> 
> > That's true.  Maybe we should add some comments here or to (info
> > "(elisp) Asynchronous Processes") ?
> 
> It's already mentioned in the MS-DOS section of the Emacs manual.
> (Unlike the word "FreeDOS", which appears nowhere in Emacs, BTW.)

"MS-DOS" is not a specific system, it's a family of systems (which
includes FreeDOS, but is not limited to it).  I see no reason to
include in the manual a list of all the systems in that family,
certainly not at this time.

> No need to mention it outside of its dedicated section, IMO.

Agreed.

DOS versions [was Re: [Patch] reformat man buffer on the fly for man.el]

[Glenn Morris]

Eli Zaretskii wrote:

> "MS-DOS" is not a specific system, it's a family of systems (which
> includes FreeDOS, but is not limited to it).  I see no reason to
> include in the manual a list of all the systems in that family,
> certainly not at this time.

I think there would be some minor utility in listing in msdos/README
exactly which systems Emacs is supported under. Is FreeDOS one of those?

Ref eg
http://lists.gnu.org/archive/html/bug-gnu-emacs/2012-11/msg01166.html


BTW, anyone know if FreeDOS considered free software by the FSF these
days?

Ref eg
http://lists.gnu.org/archive/html/emacs-devel/2008-08/msg00009.html
(from several years ago, so quite likely to be outdated)

Re: DOS versions [was Re: [Patch] reformat man buffer on the fly for man.el]

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: xfq.free@gmail.com,  darren.hoo@gmail.com,  monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Thu, 31 Oct 2013 13:37:07 -0400
> 
> Eli Zaretskii wrote:
> 
> > "MS-DOS" is not a specific system, it's a family of systems (which
> > includes FreeDOS, but is not limited to it).  I see no reason to
> > include in the manual a list of all the systems in that family,
> > certainly not at this time.
> 
> I think there would be some minor utility in listing in msdos/README
> exactly which systems Emacs is supported under. Is FreeDOS one of those?

It should be, in theory, but I never tried, so I don't know.

Re: DOS versions [was Re: [Patch] reformat man buffer on the fly for man.el]

[Xue Fuqiao]

On Fri, Nov 1, 2013 at 1:37 AM, Glenn Morris <rgm@gnu.org> wrote:
> BTW, anyone know if FreeDOS considered free software by the FSF these
> days?
>
> Ref eg
> http://lists.gnu.org/archive/html/emacs-devel/2008-08/msg00009.html
> (from several years ago, so quite likely to be outdated)

FreeDOS itself is free software (under GNU GPL).  Some utils[fn:1] like
‘LFNDOS’ and ‘NDN’ are non-free (and there is some public domain code).

Footnotes:

[fn:1] http://www.freedos.org/software/?cat=util

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: [Patch] reformat man buffer on the fly for man.el

[Stefan Monnier]

> the window is resized. Thus I added function Man-update-manpage, any
> comments on the following patch?

Installed, thank you,


        Stefan